Concepts

What's worth understanding once so everything else fits. Each section ends with notes verified on the server.

Execution order

When something happens in the zone, a stack always follows the same steps:

Event. Someone walks, talks, clicks, enters… or some time passes.
Trigger. Each trigger of that type checks whether it applies (for example, “did they step on one of MY objects?”).
Selectors. They build the list of users and objects to work with. Without selectors, the user is whoever activated the trigger.
Addons. They get ready: randomness, order, limits, movement physics…
Conditions. By default all of them must be met. With Addon: Condition logic you can ask for “any”, “none” or “at least N”.
Effects. If the conditions are met, the normal effects run; if they fail, only the “on failure” ones run, such as Effect: Send signal on failure or Effect: Execute stacks on failure.

If one event fires several stacks at once, the conditions of all of them are checked first and the effects run afterwards. That way one stack can't change the outcome of another that fired at the same moment.

Inside a stack, without Addon: Execute in order, effects run in tiers: first game effects (join a team, points, leave), then those that move kekos, then those that move or change objects, then variables (give → change → remove) and finally messages, unfreeze and signals. That's why a message already shows a variable's new value.

Verified notes (10)

A stack is every box on the same tile: there are no wires. If you move a box to another tile, it becomes part of another stack.
If you pick up a box and place it again, it comes back with the same settings it had.
Trigger: Repeater, Trigger: Time reached, Trigger: Receive signal, Trigger: Game starts and Trigger: Game ends have nobody who triggers them. To show a message or teleport someone, you need a user selector.
Effect: Write to log works even when the trigger has nobody who fires it: it doesn't need a selector.
Only the owner or someone with rights can use Disable circuits.
While Disable circuits is on, nothing triggers, not even a circuit that tries to switch them back on.
Circuits stay off even if the island reloads or the server restarts.
Circuits have their own clock: a pulse every half second (repeaters, delays, timers) and a sub-pulse every 50 ms (short repeater and fine delays).
Delays and projectiles can arrive up to 50 ms late, never early.
Circuit messages to the zone arrive as a system message starting with “[Circuit]”.

Signals

A signal connects stacks on different tiles. The Effect: Send signal effect points at a Circuits antenna; any stack with Trigger: Receive signal for that antenna runs, and receives the users and objects that travelled with the signal.

In the receiving stack, pick “signal users” or “signal objects” as the source to act on what arrived.
That's how big machines are built: one stack decides, others act, without cramming everything onto one tile.
Effect: Execute stacks runs other stacks directly, without an antenna. A stack that calls itself doesn't loop: the call runs without its own “execute stacks”.
A signal loop A → B → A stops by itself thanks to the execution limit, without freezing the island.

Selectors and sources

Almost every condition and effect has, in its advanced options, a user source or an object source: where the users or objects it applies to come from.

Source	What it takes
User who activated the trigger	Whoever stepped, talked, clicked… It's the default source.
Selector users / objects	What the stack's selectors picked.
Signal users / objects	What came with the signal that fired the stack.
Selected objects	The objects you picked in the box itself.
Reached user	The other keko in a collision, an encounter or the one a bot reached.
User selected by click	The keko that was clicked.

Triggers without a person —Trigger: Repeater, Trigger: Time reached, Trigger: Game starts, Trigger: Game ends or a signal without users— have no “who triggered”. To show a message or teleport, add a user selector such as Selector: Users in area.
If you target the selector users and the selector is empty, the effect reaches nobody: the person who triggered is not used instead.
Filters (Selector: Filter users by variable and friends) always run after selectors. Selector: Remote selectors merges or intersects what other stacks pick, up to three chained levels.

Verified notes (8)

If a selector finds nobody, the effect reaches nobody. The user who triggered it is not used instead.
“Invert” selects everything else in the island, including the circuit boxes themselves.
Selector: By height selects objects and users at once. Kekos are at height 0.
Selector: Objects by type selects the same catalogue object.
Filter boxes always run after the selectors, regardless of height.
Selector: Filter objects and Selector: Filter users pick at random on every trigger.
Selector: Filter users by variable drops anyone without the variable even if there's room left. Ties are broken by id.
The stack used by Selector: Remote selectors doesn't need a trigger: only its selectors are used. At most 3 chained levels.

Addons

An addon does nothing on its own: it changes how the rest of the stack behaves. The most used ones:

Addon: Condition logic: all, any, none or at least N conditions.
Addon: Random effects and Addon: Execute in order: one random effect, or all of them in the order you stacked them.
Addon: Execution limit: how many times the stack may run; each one adds another 100 runs per half second.
Addon: Variable value in text, Addon: User name in text and Addon: Variable text connector: messages that show values, names or words based on a variable.
Addon: Move without animation, Addon: Movement physics, Addon: Movement curve and Addon: Projectile: how objects move (jump, physics, curve, projectile).

Verified notes (12)

In Addon: User name in text and Addon: Object name in text the text is “name”, a tab and the separator. Without a separator, “,” is used.
In Addon: Variable text connector write “value=text”, one line per value, up to 30 lines. If one line is wrong nothing is saved, and there's no warning.
In Addon: Variable text connector, a value without text is shown as a number.
In Addon: Capture chat text, #(n) only matches numbers (or, in text mode, the connector's texts). If it doesn't match, Trigger: Say something doesn't fire.
What Addon: Capture chat text captures only lives in that execution.
In Addon: Level system the variable must have a value. xp_required is the cost of the current tier and is_maxed only exists once the maximum is reached.
In Addon: Time utilities only the parts you tick exist.
In Addon: Time utilities, the parts counted from 1970 are in UTC and the calendar ones use the zone's time zone.
Addon: Animation duration goes from 50 to 2000 ms (500 by default).
With Addon: Move without animation the object jumps to its destination.
In Addon: Movement physics, “blocked by objects” wins over “passes through”.
A freshly placed Addon: Projectile applies curve 50 to everything the stack moves.

Delays and time

Circuits have their own clock, which ticks every half second. That's why times always go in 0.5 s steps: an effect's “wait before running”, repeaters and timers.

An effect with a delay is queued and runs when its time comes. It can arrive up to 50 milliseconds late, never early.
Trigger: Short repeater ticks faster than the half-second pulse, for things that need precision.
Effect: Reset timers makes repeaters start counting again from that moment, but it does not cancel delayed effects already on their way.
A teleport can take up to half a second, because it follows the circuits clock.
Calendar times (Condition: Time matches, Addon: Time utilities) use the time zone you choose in the circuits menu settings.

Verified notes (21)

Trigger: Say something hides the message by default: only the speaker sees it. For everyone to see it, tick “don't hide”.
Bots also fire Trigger: Say something, including their whispers.
In Trigger: Say something, the “any message” mode fires with any text.
Trigger: Idle for a set time and Trigger: Stationary for a set time work in 5-second steps. While the keko stays still, they repeat every time that period passes.
Trigger: Idle for a set time resets when the keko walks, talks, clicks a keko or presses a key.
Trigger: Stationary for a set time only resets when the keko walks.
In Trigger: Perform an action, the laugh (as “laugh”) and the heart (as “blow a kiss”) count, as well as falling asleep and waking up.
Trigger: Click a tile fires even if the keko can't walk to that tile.
Trigger: Fall asleep fires after 3 minutes without any action; it can take half a second longer.
Trigger: Hit by another user and Trigger: Hit another user only count people (not bots), on the 8 surrounding tiles, once per encounter: they have to move apart for it to count again.
Collisions are checked every half second: a very quick brush past may not count.
The Circuits clock counts up. Trigger: Clock reaches a time fires at that exact value.
On the Circuits clock, button 1 starts, pauses and resumes. Pausing does not end the game.
Button 2 on the Circuits clock only works while paused: it stops the clock, sets it back to 00:00 and fires Trigger: Game ends.
Team points only count while a game is running (the clock started). A new game resets them to 0.
In Trigger: Variable changes, “increased” doesn't fire when the value goes down.
In Trigger: Variable changes, “created” only fires the first time the player receives the variable.
In Trigger: Bot reaches an object and Trigger: Bot reaches a user the bot is chosen by name (up to 18 letters, not case-sensitive).
In Trigger: Bot reaches a user the bot is the one who triggers. To act on the keko it reached, use the “reached user” source.
Trigger: Press a key cannot reserve Escape, Enter, Tab or the F1 to F12 keys: they still belong to the player (closing windows, opening the chat, the browser).
While you type in the chat or any text field, Trigger: Press a key receives nothing: your keys go to the text.

Variables

A variable stores a number under a name you choose. First you create it with its box, then you give, change, compare or remove it with other boxes.

Box	Who it belongs to
User variable	Each keko's: their points, lives, key.
Object variable	Each object's: how many times it was used, which team it belongs to.
Room variable	One for the whole zone: the round, the record. It exists from the moment you set it up, starting at 0.
Context variable	Only during one run: born and gone with each trigger.
Reference variable	Uses a shared variable from another zone of the same owner.
Echo variable	Mirrors the value of an internal or smart variable.

When you set up a variable you choose how long it lasts: while in the room (erased when leaving the zone), while the room is active, permanent (survives an island reload) or permanent across rooms (shared with your other zones through a reference).

“Change value” doesn't create the variable: give it first with Effect: Give variable.
Effect: Remove variable deletes it completely; that's not the same as setting it to 0.
Besides your own, the game gives you internal variables such as position, team or time.

Verified notes (16)

Effect: Remove variable deletes the whole variable; it doesn't set it to 0.
~teleport.target_id on a teleporter gives its pair. Writing it pairs it with another teleporter in the zone, same owner and same type, and their old pairs end up paired with each other.
Reference variable can point to a shared variable in another zone of the same owner even if that zone isn't open: it reads the last saved value.
Effect: Change variable value doesn't create the variable: you need Effect: Give variable first.
The Room variable always exists: it's 0 from the moment it's set up.
Inside a stack the order is fixed: give → change → remove → $(…) is read → messages → signal. It doesn't depend on height.
Dividing by 0 and modulo 0 change nothing. Division is integer division.
“Set minimum” is a floor and “set maximum” is a ceiling.
The Context variable is born and dies in each execution.
A “while in room” variable is quietly deleted on leaving, without firing Trigger: Variable changes.
A permanent variable stays after leaving and survives an island reload.
Picking up an object and placing it again in the same zone keeps its variable.
Picking up the variable's box deletes the variable and all its saved values. When you place it again, it's empty.
A variable belongs to its zone. To use it in another one, make it shared and create a Reference variable; only the owner can set it up.
A read-only Reference variable doesn't write.
An Echo variable only accepts internal or smart variables, not ones created by users.

Limits and protections

So that no island can freeze the game, circuits have caps. If you know them, you'll hardly ever notice them.

Each stack runs at most 100 times every half second, counting everyone who fires it. On a full island, spread the work over several stacks or add Addon: Execution limit.
If an island asks for too much work for a long time, its circuits switch themselves off for a few minutes. The Monitor in the circuits menu warns you first with “High load”.
Chains of signals that call other signals have a maximum depth, and delayed effects a queue cap.

Verified notes (10)

Each stack can run at most 100 times every half second. Anything beyond that doesn't run.
A loop (stack A calls B and B calls A) cuts itself off, with no penalty and without freezing the island.
Effect: Execute stacks pointed at its own stack doesn't loop: that call runs without its own “execute stacks” boxes.
The 100 cap counts everyone who triggers that stack. In a full island (about 60 people talking or clicking non-stop on the same stack) the cap can be reached.
If your stack hits the cap, split it into several stacks or stack Addon: Execution limit: each one adds 100 more executions.
Every box has a cost. If an island goes far over the limit, its circuits switch off for 10 minutes.
Picking up a box removes it from its stack instantly.
Effect: Remove user from room can't kick the owner or a moderator.
Effect: Mute user doesn't affect the owner, users with rights or moderators. Neither does the mute supercircuit.
The chat's bad-word filter also applies to circuit and bot texts.

BoomBang's own rules

Circuits act on BoomBang's world, with its rules:

One keko per tile. No circuit movement leaves a keko on top of another.
Objects at level 3 or higher are walked under: they don't block the way.
Only BBoxes and circuit boxes have height; objects only have two orientations.
There are no pets, wall objects, sitting, dancing or hand items: boxes for those work, but nothing is shown.
Avatar effects are potions. A potion set by a circuit lasts while the keko stays in the zone; circuits never touch a bought potion.
Effect: Remove user from room and Effect: Mute user don't affect the island owner or moderators.
Circuit messages arrive as system messages, with “[Circuit]” in front, and go through the game's word filter.

Verified notes (50)

With Invisibility control on, visitors without rights stop seeing the circuit boxes, which keep working. The owner always sees them.
Invisibility control hides the boxes, Invisible click tile, Disable circuits and Room link. Scoreboards, the Circuits clock, chests and the control itself stay visible.
Circuits never change or remove a potion someone bought.
A potion given by a circuit lasts while the keko stays in the zone, and only a circuit can remove it.
The zone's clan is the clan of the island's owner.
A clan's admins are its leader and co-leaders.
Being in the owner's clan doesn't let you see or touch their circuits, or pick up objects with :circuitcode.
Seeing and editing an island's circuits is up to the owner and whoever is on the island's whitelist.
The owner can add their clan in the circuits settings so it gets rights too.
In Trigger: Object lands on object, the chosen objects are the ones UNDERNEATH. If you don't choose any, any object counts.
Trigger: Object lands on object only counts an object moved by a circuit or the ball: if the owner moves it with the editor, it doesn't fire. Circuit boxes don't count.
Trigger: Object lands on object has nobody who triggers it: for messages or teleports you need a user selector.
In Trigger: Object hits object both objects must be chosen, the one that moved and the one already there. With nothing chosen, it never fires.
In Trigger: Object hits object, the triggering user is the keko closest to the collision.
In Trigger: Object reaches tile the tile is written as X,Y. It works for the chosen objects (with none chosen, any object) and also for the ball, for goals.
Moving an object with the editor doesn't fire Trigger: Object reaches tile.
Trigger: User next to another user fires on every step that leaves a keko on one of the 8 tiles around another. Bots and ghost mode don't count.
In Trigger: User next to another user, whoever walked is the triggering user; the other one is the “reached user”.
Condition: Number of users that stepped on object records whoever triggered the stack, without repeats, and is met once N different kekos are reached.
When Condition: Number of users that stepped on object is met, the count goes back to 0 and the counted kekos become the “selector users”: effects with that source reach all of them.
The Condition: Number of users that stepped on object count is lost when the island reloads.
One trigger turns Effect: Drop rain on and the next turns it off, removing any chests left.
Effect: Drop rain drops a chest every “interval” seconds on a free tile of the zone or area, up to the maximum at once.
Whoever steps on a Effect: Drop rain chest picks it up and adds the points to the chosen user variable. Optionally, they get a whisper with {username}, {score} and {points}.
Effect: Drop rain chests don't give objects or coins and don't ask for a code.
Anyone who enters the zone later doesn't see the Effect: Drop rain chests that had already dropped.
Effect: Change object color uses BoomBang colours “color1|color2”. One can be left empty, and that one isn't changed.
With “save” the colour is kept for good; without “save”, it lasts until the server restarts.
Badly written colours aren't saved.
Effect: Send to another room doesn't send anyone to an island that has them on its blacklist: the keko stays where they are. The owner and admins can always enter.
Gestures in Trigger: Perform an action, Condition: Performing an action and Selector: Users by action: 101 laugh 1, 102 laugh 2, 103 fart, 104 spit, 105 heart, 106 special, 107 cry, 108 redbull, 109-118 sound words.
The laugh still counts as “laugh” and the heart as “blow a kiss”. Gestures count for 2 seconds.
Sitting, lying down, dancing, signs and moonwalk don't exist in BoomBang: the boxes work, but nothing is seen.
These supercircuits work but nothing is seen: roomwalkthrough, roomlock, roomrespect, roomchangelook, roomtransform, roomhanditem, roomenable, roomsit, roomlay, roommimic and roommoonwalk.
A keko always takes up its own tile: a circuit never puts one keko on top of another.
Objects at level 3 or higher don't block: you walk under them.
BoomBang objects only have two orientations, and only if they can be flipped.
Kekos don't turn their head separately: head-only turns don't rotate anything.
There are no pets in BoomBang: boxes meant for pets don't find anyone.
There are no wall objects in BoomBang.
Avatar effects are potions: when a box asks for an effect number, that number is the potion id.
Joining a team or teleporting doesn't give the keko any visible effect.
Boxes use medals. A medal's code is its id; its title is accepted too.
A keko's look is its colours: the character isn't included.
The achievement score is the sum of the points of unlocked achievements shown on the profile.
Effect: Add event wins adds to the “Event Champion” achievement and only works on staff islands.
A keko falls asleep (AFK) after 3 minutes without any action.
With the island muted by the owner (:muteisland) only the owner, the whitelist and admins can talk; everyone else doesn't fire Trigger: Say something.
The roommute supercircuit mutes the zone on its own and never lifts a mute set by the owner.
A moderator in invisible mode does not count for circuits: selectors do not see them, they trigger nothing and no effect touches them.