This document is a broad overview of the Circuits system - covering all the important concepts and entities you need to know about!

What are Circuits?

Circuits is Rec Room’s visual scripting system. It’s the way to add behavior and interactivity to your Rec Room creations

If you want to build:

Game rules with timers and scoring
A vehicle that you can drive around
A drum machine

...you’ll use Circuits to make it work!

How do I use Circuits?

As with most creation tasks in Rec Room, you’ll use the Maker Pen to create and edit Circuits.

All the bits and pieces you need to make a circuit are in the Maker Pen Palette, and you spawn them in your room the same way you spawn a shape or a prop. All the basic tools work as normal: Move, Rotate, Scale, Clone, Delete, Undo, etc.

When building with circuits, you’ll also make heavy use of:

The Wire tool - use this to add wires that connect things together and make things happen.
The Edit tool - use this to “open up” circuit boards so you can see what’s hidden inside (more on this soon).
The Config tool - use this to show the Config menu, where you can adjust how your circuit objects work.

Hello World!

If you’re anything like me, you will be keen to just try it out as opposed to reading this whole document. So let’s walk through a very simple example, so you can see circuits in action and get a feel for how it works:

System Tour

Let’s take a tour of the entire Circuits system. Once you’ve read this entire section, you’ll be familiar with every part of the system. But please understand that it will take some time and practice to truly master it! Programming in Circuits has a lot in common with programming in any language.

So the bad news is: It can be complicated, and there’s a lot to practice and learn. You’ll probably feel overwhelmed sometimes.

The good news is it’s incredibly powerful, and once you’ve mastered it you’ll know quite a lot about actual programming! Plus, there’s an amazing community of creators ready to help you.

OK, let’s get started.

Room Layer vs Circuit Layer

The first thing to know is that a Rec Room room has two “layers”:

The Room Layer - this is the basic room. Generally speaking, everything you can see when you’re not holding a Maker Pen is in the room layer. Objects (like basketballs, chairs, etc.) and other players live in the room layer.
The Circuit Layer - this is the hidden “creation realm” in Rec Room. It reveals itself when you equip your Maker Pen. Circuit Objects (like chips, boards, components, and the wires that connect them) live in the circuit layer.

You can think of the circuit layer as the engine in a car. Usually you can’t see it - you just see a cool-looking car driving around. But pop the hood and you’ll see the complex machinery that makes it work.

Equipping the Maker Pen is like popping the hood on your room - things definitely look more complex, but it’s where you can make serious changes to how things work!

Syncing, Execution and Heat

If you’re just getting started with circuits, you can just wire objects together and it will mostly work like you expect.

But as your creations get more complex, you’ll need a deeper understanding of how things work “under the hood” so that you can be sure that your circuits (a) work correctly under all conditions, and (b) are working efficiently so that you don’t run into performance problems.

Let’s start by introducing three important concepts:

Syncing - at a basic level Rec Room simulates the experience of being with other people in a room filled with real objects. Player A might be in Seattle, while Player B is in Tokyo. To create the illusion that they are in the same room, we need to sync the room state back and forth, so that changes made by Player A are seen by Player B, and vice versa. Syncing is achieved by sending messages over the internet. Rec Room sends hundreds of “sync” messages per second back and forth between players to keep everything in sync. You can learn more about the basics of Rec Room networking by Reading Rec Room Networking 101.
Execution - you can think of execution as “sending electricity down the wires” to activate circuit objects. You can also call this “running” a circuit. “Running” a circuit and “executing” a circuit mean the same thing, and we use the two terms interchangeably. We’ll dig deeper into this later, but as a starting point:
- Like any computer code, circuit execution happens on an actual CPU on an actual device. Maybe this circuit is executing on my iPhone, or your PC, or Stephanie’s Oculus Quest. The key point is that it’s running on someone’s actual, physical device.
- The best way to think about it is that circuit execution is hosted by a specific player. If I say “I’m running this circuit”, what I mean is “this circuit is executing on my device”. If I say “Player X is running this circuit”, it means “this circuit is running on Player X’s device”.
Heat - both syncing and execution use actual, physical resources in the real world. Neither network bandwidth (syncing) nor CPU cycles (execution) are infinite! “Heat” is how these limited resources are represented in the Circuits System.
- Sync heat - is how much network traffic your circuits are sending. Less is better. Max out the sync heat gauge, and your circuits will stop executing (since sending any more traffic will cause you to disconnect from Rec Room).
- Exec heat - is how much CPU time your circuits are consuming. Less is better. Max out the exec heat gauge, and your circuits will stop executing (since taking up more CPU time would badly impact the frame rate of the game).

The various limits are shown as gauges in the Circuits V2 sections of the palette:

CPU = Exec heat. Stay under 100%.
Net = Sync heat. Note that there are two values shown:
- % = how much sync traffic your circuits are generating (stay under 100%)
- Sync event limit = some components (see below) generate “sync events” to tell other players that something has happened. You are currently limited to five sync events per frame.
Chips = How many chips you can have in your room total (currently 3,000). Once you reach the limit you won’t be able to create (spawn, clone, copy, etc.) any more chips.

Note: These limits are intentionally quite conservative as we roll the system out and understand its behavior “in the wild”. We will be working to increase these limits significantly over time.

Circuit Objects

There are four types of circuit objects that you need to know about. Each type of object performs a different role in the system, and has different rules for how they work. The four types are:

Rec Room objects
Chips
Boards
Components

Let’s look at each in more detail...

Rec Room objects

Most things you see in a room are Rec Room objects (there are some exceptions, but not many). For example, a basketball is a Rec Room object.

Live in the room layer - i.e., always visible
Automatically synced - i.e., all players in the room will see the basketball in the same place at the same time
Cost ink

Some RR objects (e.g., a button) can generate events in the circuit layer. We call these “input objects”.

Chips

Chips are the basic building block of circuits. Most chips are pretty simple - for example the Add chip which takes two numbers and outputs their sum. Or a Variable chip which can store a number or string for later use. But some chips are quite complex (we’ll talk about those later).

Live in the circuit layer - i.e., only visible when holding a Maker Pen
Physical state is synced - the presence/absence of a chip (and location in the room) is synced.
Execution state is not synced - a chip could be executing for player A, but not for player B.
No ink cost

Chips have input and output ports which are connected with wires, creating a circuit graph. To do anything cool with circuits, you’ll need to learn how to build and work with circuit graphs!

Chips generally don’t do anything until they are executed. When executed, they do their thing (e.g., add two numbers) and produce some kind of result. Chips can be executed in two ways:

Input exec port - this the “standard” way to execute a chip. Connect a wire to the orange exec input. When an exec signal arrives at the port via the wire, the chip will execute. Results are sent to the output data ports (if any), and exec continues at an output exec port.
Auto-exec on read - some chips don’t have (or need) an input exec port. These chips auto-execute when something reads their output data ports. For example, the Add chip doesn’t have an input exec port, it auto-execs when something reads its “value” output.

Here’s an example of a circuit graph executing - the flashing wires indicate the different execution path based on the input:

Boards

Boards are basically containers for chips. You can edit into a board to create a complex circuit graph, then edit back out to hide the complexity.

Like chips, boards have input and output ports that allow you to connect wires. Ports are visible on both the inside and the outside of a board. This means you can connect a wire to the outside of a board, and receive that signal inside the board. This is one of the ways circuit graphs inside a board communicate with the outside world.

Ports are grouped into named functions, which can be executed by wiring to the board. In the future, you’ll be able to call these functions remotely by using the Function chip, but that is not available yet!

Live in the circuit layer - i.e., only visible when holding a Maker Pen
Physical state is synced - the presence/absence of a board (and location in the room) is synced.
Execution state is not synced - a board could be executing for player A, but not for player B.
No ink cost

Note that only chips and boards can be placed in boards. You can’t put a RR object or a component in a board.

There are a few different types of board. They are all fundamentally similar (“containers for chips”), but there are important details:

Object boards - every RR object has an “object board” (note: This is not true yet… but we’re working on it!). This is a circuit board that is permanently connected to the object. Object boards allow you to send circuit signals to/from any RR object.
Player boards - every player in the room has a “player board”. This is a circuit board that is permanently connected to a player. Player boards allow you to send circuit signals to/from any player. Note that you can’t wire directly to a player board, since players can join/leave rooms at any moment. More on that later…

Components

Components are similar to chips, but they have a superpower - they create “room effects”. When a component executes in the circuit layer, something happens in the room layer. For example, there are components to play sound effects, create visual effects, display 3D text, or move connected objects (components that move connected objects are called gizmos).

Live in the circuit layer - i.e., only visible when holding a Maker Pen
Physical state is synced - the presence/absence of a board (and location in the room) is synced.
Execution state is not synced - a component could be executing for player A, but not for player B.
Room effects are synced - e.g., when one player executes a sound effect component, everyone in the room will hear it.
- Some components allow you to opt-out of syncing room effects.

Execution Model

To really master building with Circuits, you need to fully understand the execution model. It’s pretty simple, but there are important nuances and implications that you need to understand and exploit to get maximum performance out of the system.

Let’s start with the basic rules:

Basic rules

Room sync themselves - everything that happens in the room layer is automatically synced.
Circuits run per-player - circuits are executed by a specific player in the room, not by all players.
Manually sync your circuits - sometimes it’s important to sync circuit state to other players (for example, you may want everyone to have the same value for a “score” variable). You don’t want to overdo this (for sync heat reasons), but when it’s important you can and should do it manually.

As a rough rule of thumb, you can interpret these rules as “stuff in the room layer is automatically synced, stuff in the circuit layer is not”.

This isn’t 100% true, as there are some important exceptions (a big one being that the physical presence/absence of chips, boards and components in the circuits layer is automatically synced).

But it’s a good rough guide to keep in mind as you build!

Let’s look at each rule in more detail...

1. Rooms sync themselves

Rule #1 means that you can expect anything that happens in the room layer to be synced to all players (see Rec Room Networking 101 for more detail). If I throw a basketball, you see me throw the basketball. There may be minor differences due to network lag (the time it takes to send a sync message from Seattle to Tokyo, for example), but generally speaking all players will agree on the state of the room. As a circuit builder, you don’t have to do anything special to make this happen - rooms sync themselves!

2. Circuits run per-player

All players have an identical copy of the circuit graphs. If you add or remove a chip, that operation will be synced.

Circuit execution, however, is not synced. Execution happens “per-player”. What does this mean exactly?

Circuits are always executed by players in the room. There are no exceptions to this. It could be you, it could be me, it could be that player over there. It could be all of us at the same time! But a circuit graph always runs on someone’s device. There is always an answer to the question “who is running this circuit?”
Managing who runs what is an important skill when creating with Circuits. There are some simple rules and patterns to follow that will get you a long way without a deep understanding. But to get maximum quality and performance out of the system, you’ll need to actively manage execution based on a clear understanding of where it's happening and why.
While it’s possible to run circuits on any player, in most cases you’ll use one of two options (we’ll talk about why in a moment):
- The Authority Player - this is a special player chosen by the system (as described in Rec Room Networking 101 - “Room Authority” and RA are the same thing). There is always one (and only one) RA. If the current RA leaves the room for any reason (they go somewhere else, they disconnect, or they crash), RA duties are immediately and seamlessly transferred to another player. If you were the first player in the room, you are likely RA. If you are the only player in the room, you are definitely RA!
- The Local Player - this is the player running on a given device. For example, let’s say we have two players in a room:
  - Player A is playing on an iPhone
  - Player B is playing on a Quest
  - Player A is the Local Player on the iPhone
  - Player B is the Local Player on the Quest
- You can be both Local and RA at the same time! If you’re the only player in a room, you are definitely both.

Let’s go through a simple example to see how this works in practice.

Let’s say player A and player B are in the same room.
A moves their avatar over to a button and pushes it.
Player B sees A’s avatar standing next to the button. They see A’s hand reach out and push the button. They see the button depress in, and hear the sound of it “clicking”. All of this stuff happens in the room layer, so it’s automatically synced.
From this point on, the action happens in the circuit layer!
Due to rule #2 (circuits run per-player), things happen differently for A and B. By default, Button objects execute for the local player. This means that...
- For player A, the “button pressed” output exec port fires on the button’s object board.
- For player B, the “button pressed” output exec port does not fire.

To summarize that: When you press a button, the resulting circuit execution happens for the local player. It’s possible to change that, but that’s the default behavior.

Let’s say the button is connected to a light component. You might wonder how - if the button only executes for the local player - how it is that everyone sees the light turn on/off?

That’s because of how components work - while they execute per-player like any circuit object, their room effects are synced. So when any player executes the light to turn it on, the “on” property of the light is automatically synced. This means that - in practice - whoever presses the button, everyone sees the light turn on/off - and the same basic principle applies to VFX, Text, Gizmos, etc.

[Pic of button → light component circuit, showing sync events]

3. Manually sync your circuits

Sometimes, the fact that circuits run per-player causes problems. Consider this simple scoreboard circuit:

If the same player keeps pressing the +1 button over and over, the scoreboard will work as expected. Each press will increment the score (shown in red) by 1.

But what happens when another player presses the button? Uh oh… suddenly the score resets to 1. What is going on?

The problem is a result of rule #2… because circuits execute per player, each player has their own copy of the “Score” variable. When Player A presses the button, they are incrementing their Score variable. When Player B presses the button, they are incrementing their Score variable. There’s nothing keeping Score in sync for A and B.

So this is a case where we need to manually sync our circuits. And it’s easy to do that: We open up the config menu of the Score variable, and turn the “Synced” toggle on:

Now, whenever “Score” is updated, it will automatically sync the change to all players. Now our scoreboard works correctly no matter who presses the button. The downside is that Score now uses some sync heat any time it updates.

TLDR

To summarize, the three rules are:

Rooms sync themselves - “If you can see it when you’re not holding the maker pen, it’s synced!”
Circuits run per-player - “Circuit execution happens on one person’s device”
Manually sync your circuits - “If it's important that everyone has the same value for a variable, turn on syncing for that variable.”

You may ask - why do circuits run per-player? Why aren’t they automatically synced like RR objects in the room? Surely that would be simpler? It would. It would also be much more limited. In fact that’s how the original Rec Room circuits worked. Circuits V2 embraces a more complex networking model so that circuit logic can be as fast and reactive (e.g., you fire a gun or hit a drum and it happens reliably and immediately) as the RRO objects we build. It also dramatically reduces network traffic.

The “GM Pattern”

The GM pattern is a way of constructing circuit graphs that makes them reliable and robust. It’s the right way to implement game rules (e.g., timers, scores, game states, etc.). It’s modeled after the idea of a “Game Master” from D&D - i.e., one person is in charge of keeping track of the rules, scores, etc.!

Here’s the basic idea:

No matter which player starts execution, the important “housekeeping” functions are actually handled by the RA player.
This means that only the RA runs the circuit graphs to update the timer, the score, or whatever needs to happen.
Important variables (e.g., the current timer, or the current score) are synced.
If the current RA leaves, the new RA can pick up where they left off.

Building things with the GM pattern can be a little more complex, but the benefit is that your game rules are now robust to players joining and leaving the room.

Consider this “non-GM Pattern” countdown timer circuit:

This circuit will start when a player presses the button, countdown for 10 seconds, then play a buzzer sound when the timer reaches zero.

As long as no-one leaves, everything will work fine! But what happens if the player who presses the button leaves the room before the timer reaches zero? (Remember that, by default, buttons execute on the local player).

If that happens, the timer will freeze. For everyone left in the room, the timer will appear to break. That’s no good!

Here’s the same countdown timer built with the GM pattern:

In this version of the circuit, the key thing is the “RA 1Hz Tick” chip (actually a board with other chips inside it). This board generates an exec signal once-per-second only for the RA player.

This means that whoever is the RA player will get the “tick” exec signal. If that RA leaves and another player becomes RA, the new RA will start getting the tick. The key thing is the RA player - and only the RA player - gets the tick!

The “tick” exec signal from RA 1Hz Tick is sent straight to an “If” chip, which checks to see if a (synced) variable called “Running” is True. If not, nothing happens! In other words, if the countdown timer isn’t “Running”, the tick is ignored.

Now all that needs to happen is the button sets “Running” to True. Now when RA 1Hz Timer ticks, the “If” chip will continue execution, and the countdown happens!

This means that if the current RA leaves, the new RA will immediately take over, and the counter will keep counting down as if nothing happened. Perfect!

Note that the variables are synced in the GM pattern… this is so that - in the event of a handoff - the new RA can continue on from the right place.

You can find the “RA 1Hz Tick” board as an Invention in the Invention store!