Wirescript Language Reference

Wirescript is a high-level language that compiles to Brickadia’s logic gates. It replaces manual gate-by-gate wiring with a readable, imperative syntax while keeping the gates’ own execution model.

Table of Contents

1. Syntax: Language syntax reference: declarations, statements, blocks, statement terminators, comments, and doc comments.
2. Types: The type system: primitives (int, float, bool, string, entity, controller, character, vector, rotator, color, exec), compound types (ref T, T[], Map<K, V>, tuples, unions, records, enums), and type coercion rules.
3. Expressions: Operators (arithmetic, comparison, logical, bitwise, string concatenation), operator precedence, string interpolation, conditional expressions, field access, index access, and function calls.
4. Statements: var, let, buffer, arrays, maps, in, out, if, match/if let/let else, on (handlers), event, emit, assignment, and expression statements; plus the module-level annotations a file opens with (@fold/@nofold, @layout("code")/@layout("cube"), @flat).
5. Builtin Functions: All built-in functions grouped by category: math/trig, vector, entity, controller/character, display, gamemode, raycasting, random, string formatting, and color.
6. Chips: Anonymous chips (chip {}), chip let, chip on, named chips with parameters, mod (inline expansion), ref/* params, nested chips, open and closed chips, and compiling without microchips (@flat).
7. Execution Context: Pure vs exec context, what requires exec, handler exec chains, exec unions after handlers, and explicit exec parameters.
8. Enums: Tagged unions: declaring enum variants (unit, positional, named payload), construction, .Discriminant, match, if let / let else, generic enums, and the built-in Option/Result.
9. Best Practices: Gate count and scaling: why every call site is a copy (for mod and chip alike), the call-site multiplier, single-dispatch event queues, deferred flags, and bitmask state.
10. Constant Folding: Compile-time evaluation of pure gates with constant inputs, guarded by an in-game-certified semantics table; fold barriers; the certification story and reproducibility guarantees.
11. Testing: Writing a program that checks itself in game: the on Loaded() trigger, a check mod over reference counters, staying silent unless something fails, making the failure line diagnostic, comparing two paths rather than one path against a constant, and what an in-game run cannot prove.
12. Game Knowledge: Brickadia behavior the language does not define but programs depend on: rich text markup, the fonts the game ships, input action and axis glyphs, and every action name.
13. Diagnostics: Every WSxxx diagnostic code the compiler emits, grouped by category (context, names, types, calls, generics, config, …), with a one-line meaning and trigger for each.
14. Upgrading: Breaking changes and how to migrate existing .ws code across versions; links the full CHANGELOG.md.

Quick Example

// A simple counter that increments on each round start
var count: int = 0

on RoundStart() {
  count = count + 1
}

out total = count

How It Works

Wirescript compiles down to Brickadia’s logic gates and the wires between them. Every var becomes a variable gate, every operator becomes an expression gate, and every on handler becomes an exec chain rooted at an event gate. The compiler handles gate placement, port wiring, and type coercion automatically.

Wirescript has two execution contexts:

• Pure context: Expressions that define continuous signal-flow relationships (like wiring gates together). These evaluate whenever their inputs change.
• Exec context: Imperative code that runs in response to events (like a handler body). These execute sequentially when triggered.

Writing correct Wirescript depends on this distinction. See Execution Context for details.

Learn

Learn about programming and logic in Brickadia at your own speed.

Already program? Start with Wirescript for Programmers. Want ready-made circuits instead? See Parts.

Tools

Write Wirescript in the playground or in VS Code, compile it to a .brz save, and paste the save in-game.

Contents

• Writing and compiling
• Pasting a circuit in-game
• The starter library
• Code layout
• Reading an error

Writing and compiling

The playground runs in your browser with nothing to install. Write a file, press Compile (or Ctrl+Shift+B), and it downloads a .brz save. Errors show as red underlines as you type.

VS Code needs the Brickadia Wirescript extension: install it from that page, or search for “Brickadia Wirescript” in VS Code’s Extensions view. Then open a .ws file. You get errors as you type, completions, hover, go to definition, rename, formatting, and these docs inside the editor. Ctrl+Shift+B compiles the open file and puts the .brz on the clipboard, ready to paste into Brickadia.

The command line comes with the Wirescript SDK, also the SDK button in the playground’s toolbar. Its tools need Node.js 18 or later: node check.mjs door.ws checks a file, and node compile.mjs door.ws writes door.brz.

Every example in these lessons has a Compile button too, next to the copy button. It downloads that example as a save, so you can try it without writing anything.

The docs editor is the Editor tab at the bottom right of every docs page. It opens the playground’s editor in a drawer, with the same errors, completions and hover, plus Compile and Playground buttons. The pencil button on an example loads that example into it, so you can change it and compile the result. It does not save your work: it holds one piece of text, and loading another example replaces it. Write anything you want to keep in the playground or VS Code.

Pasting a circuit in-game

A compiled .brz is an ordinary Brickadia save holding one microchip brick. Paste it in-game, either through Brickadia’s load dialog by the file’s path, or straight from the clipboard after VS Code’s Ctrl+Shift+B, and place it where you want it.

The microchip is the circuit. Its pins are small bricks on its sides, each labeled with its name. You wire them to the rest of your build with the wire tool, like any other component.

The starter library

Many examples begin with import { escape } from "sanitize". That line brings in helpers from sanitize.ws, a small library that comes with these lessons. An example’s Compile button and the docs editor fetch it for you. To build those examples in the playground or VS Code, save sanitize.ws in the same folder as your own file. This is the whole file:

// Escape markup in a display name before showing it. A `mod`, so each use is a single gate.
mod escape(text: string) -> string {
  return text.Replace("<", "&lt;")
}

// Clean free-form player input: trim, cap the length, then escape.
// Capping first keeps the cut from landing inside an `&lt;`.
fn sanitize(raw: string, maxLen: int = 24) -> string {
  return raw.Trim().Substring(0, maxLen).Replace("<", "&lt;")
}

escape makes a name safe to show, and sanitize also trims it and cuts it to a length. Safe Text explains both, and Imports explains import.

Code layout

The compiler normally arranges a chip’s gates to keep its wires short, with no link to where the code sits in the file. To see each line of code as a row of gates when you open the chip, put @layout("code") at the top of the file, followed by a blank line:

@layout("code")

@left in a: bool
@left in b: bool
let both = a && b
@right out lit = both

Earlier lines sit higher, and indentation shows in the gates. This helps while you learn to read compiled chips. See @layout("code") for the details.

Reading an error

When a file has a mistake, the compiler stops and says where. This pin uses a name the language keeps for itself:

@left in on: bool

Read the first line of the error:

Error: [WSP001] expected Ident, got 'on' (Kw)

It names the problem (on is a keyword, Kw) and gives the line and column. More errors usually follow, all caused by the first one. Fix the first and compile again.

Some reserved words make tempting pin names: in, out, on, from, type, match, buffer, emit, fn, mod, const, static, await and chip. Use another word (trigger, door, go).

Every error code is listed in Diagnostics.

Next: First Circuit.

First Circuit

Your first circuit is a chip with one pin in and one pin out, and nothing between them but a wire. You will wire a switch to one side and a light to the other.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make

switch Enabled -> chip a
chip b -> light Enabled

Code

@left in a: bool
@right out b = a

@left in a: bool puts a pin named a on the chip’s left side. It takes a bool: on or off. @right out b = a puts a pin named b on the right side and gives it whatever arrives at a.

What does the light do when you flip the switch?

Run

1. Compile the example and paste it in-game. The chip has a pin labeled a on its left and one labeled b on its right.
2. Place a Switch to the left of the chip and a Point Light to the right.
3. Wire the Switch’s Enabled output to pin a.
4. Wire pin b to the Point Light’s Enabled input.
5. Flip the switch. The light turns on and off with it.

Under the Hood

Open the chip. Inside there is only a wire from a to b. The pins on the chip’s sides are rerouters: @left and @right each add one. Leave the side annotations off and the chip has no gates at all. The source decides which pins a compiled chip has and what connects them.

The rerouters are why the side annotations exist. Your wires end on them, not on the chip, so they work as a socket: to replace the chip, break it and paste the new version over the same rerouters, and the wires stay as they were.

Modify

1. Replace the Switch with a Button, wired from its Held output. Now the light is on only while you hold the button.

2. Give the output a label of its own: @label("Light") @right out b = a. The pin’s floating label now reads “Light”.

   @left in a: bool
   @label("Light") @right out b = a
   

3. Flip the light: change the output to b = !a. ! is NOT, so the light is now on while the switch is off, and off while it is on.

   @left in a: bool
   @right out b = !a
   

   Compile it, break the old chip and paste the new one over its rerouters. The Switch and the light stay wired. Open the chip again: the wire now passes through one NOT gate.

Make

Make a chip with two inputs and two outputs that passes each input straight across to its own output, then wire two switches to two lights through it.

switch1 Enabled -> chip a
switch2 Enabled -> chip b
chip outA -> light1 Enabled
chip outB -> light2 Enabled

Next: Gates and Wires.

Gates and Wires

A gate is a brick that computes something from its inputs, like AND or addition. Wirescript writes gates as expressions: every operator becomes one gate, and every name you use becomes a wire to the gate that made it.

Contents

• Code
• Run
• Under the Hood
• Use it: a two-way hall light
• Make

switch1 Enabled -> chip a
switch2 Enabled -> chip b
chip both -> light1 Enabled
chip either -> light2 Enabled

Code

@left in a: bool
@left in b: bool
@right out both = a && b
@right out either = a || b

&& is AND: true when both sides are. || is OR: true when either is. With two switches wired to a and b, and two lights on both and either, which lights are on for each of the four switch positions?

Run

1. Compile the chip and paste it in-game. Place two Switches and two Point Lights.
2. Wire each Switch’s Enabled to a and b, and both and either to each light’s Enabled.
3. Try all four positions. both lights only with both switches on. either lights with any switch on.

Under the Hood

Open the chip. It holds one AND gate and one OR gate, each wired from both pins, and nothing else.

The same circuit built by hand is two gate bricks and six wires. Wirescript writes the bricks and wires for you, and the source stays readable as the circuit grows.

let gives a value a name without adding a gate. The name is a wire you can use again:

@left in a: bool
@left in b: bool
let both = a && b
@right out lit = both
@right out dark = !both

! is NOT. This chip has two gates (AND and NOT): both names the AND gate’s output, and both outputs read it.

Use it: a two-way hall light

A hallway light with a switch at each end should change whenever either switch is flipped. That is exclusive OR, written ^^: true when exactly one side is true.

@left in near: bool
@left in far: bool
@right out light = near ^^ far

Wire a Switch at each end to near and far, and light to a Point Light’s Enabled. Flipping either switch changes the light.

Make

Make a chip with three switch inputs whose light turns on when at least two of them are on.

switch1 Enabled -> chip a
switch2 Enabled -> chip b
switch3 Enabled -> chip c
chip lit -> light Enabled

Next: Pure and Exec.

Pure and Exec

Wires carry two kinds of signal. Telling them apart is the most important idea in this series.

• A pure wire carries a value that is always there, like the switch’s on/off. A gate on a pure wire recomputes whenever its inputs change. Every circuit so far has been pure.
• An exec wire carries a pulse: a moment when something happens, like a button being pressed. An exec pulse runs a chain of steps, one after another, and each step can change something.

Think of a light switch and a doorbell. The switch is always either up or down (pure). The doorbell rings at a moment, and the ring makes something happen (exec).

Contents

• Code
• Run
• Under the Hood
• Modify: a door that closes by itself
• Make
• Good to Know

button Held -> chip pressed
chip solid -> changer "Collision Enabled"
chip solid -> changer Visibility

Code

@left in pressed: exec
var shut: bool = true
@right out solid = shut.Value

on pressed {
  shut = !shut
}

pressed is an exec pin: an input whose job is to start something. var shut is a variable: a value the circuit remembers and can change. on pressed { ... } is a handler. It runs its steps once each time pressed fires, and only then. shut = !shut flips the variable. shut.Value reads the variable as a pure value, so solid follows it.

Wire a Button to pressed. What happens on the first press? The second? What happens while you hold the button down?

Run

1. Compile the chip and paste it in-game. Build a door from a few bricks and give one of them a Brick Property Changer.
2. Wire a Button’s Held output to pressed.
3. Wire solid to the Brick Property Changer’s Collision Enabled and Visibility inputs. One output can feed both.
4. Press the button: the door vanishes. Press again: it is back. Holding the button does nothing more, because the handler runs once per press, when pressed turns on.

Under the Hood

Open the chip. The variable is a Variable gate. The handler is a short chain: a Get Variable reads shut, a NOT flips it, and a Set Variable stores it. The chain’s exec input is wired from pressed. Held is an on/off value, not a pulse, but wiring it into an exec pin works: the chain runs when Held turns on, not while it stays on. solid is wired from the Variable gate’s value, a pure wire.

on fires when its trigger turns on. on !pressed { ... } fires when it turns off. That reads pressed as an on/off value, so declare the pin bool for it: an exec pin stands for the moment something happens, not for a value that stays on or off.

Modify: a door that closes by itself

@left in pressed: exec
var shut: bool = true
@right out solid = shut.Value

on pressed {
  shut = false
  await Sleep(_, delay = 3.0)
  shut = true
}

await Sleep(_, delay = 3.0) pauses this chain for three seconds, then carries on. Treat the line as a “wait” block for now: the _ and the other forms of await come in a later lesson.

Press the button: the door opens, and three seconds later it shuts. Change the delay. What happens if you press again while it is open?

Make

Make a door that opens while the button is held and closes when it is released, using on pressed and on !pressed. Declare the pin @left in pressed: bool for this, since !pressed reads its value. Then compare it with @right out solid = !pressed, which does the same with one pure gate and no handler. Reach for a handler when something has to be remembered or waited for.

button Held -> chip pressed
chip solid -> changer "Collision Enabled"
chip solid -> changer Visibility

Good to Know

• Declare a pin exec when it only starts handlers, and bool when the circuit also reads its value (!pressed, if pressed, out x = pressed).
• A handler on a pin runs once when the wired value turns on, not continuously while it stays on.
• A Button’s Held is on only while someone holds it. A Switch’s Enabled stays on until it is flipped back.

Next: Remembering Values.

Remembering Values

A var keeps its value until a handler changes it. The value stays through other presses and other players’ actions, and when the world is saved and loaded again.

Contents

• Code
• Run
• Under the Hood: let and var
• Use it: a press-count sign
• Make

button Held -> chip pressed
chip text -> decal Text

Code

@left in pressed: exec
var count: int = 0
@right out text = "Pressed ${count.Value} times"

on pressed {
  count += 1
}

var count: int = 0 is a whole number that starts at 0. count += 1 adds one to it. "Pressed ${count.Value} times" builds text with the count in the middle. String Interpolation has the details.

What does the sign say after three presses?

Run

1. Compile the chip and paste it in-game. Place a Button and a brick with a Text Decal.
2. Wire the Button’s Held to pressed, and text to the Text Decal’s Text input.
3. Press the button a few times. The sign counts.

Under the Hood: let and var

A let is a name for a wire. It holds nothing. Its value is whatever its gates compute right now. A var is a Variable gate that holds a value until a handler writes a new one.

There are two ways to read a var:

• count.Value, outside a handler, is a pure wire from the Variable gate. After a handler writes it, this wire shows the new value on the next tick, the game’s next update.
• count, inside a handler, reads the variable at that step of the chain. A step after a write sees the new value.

@left in pressed: exec
var count: int = 0
var last: int = 0
@right out shown = last.Value

on pressed {
  count += 1
  last = count
}

Inside the handler, last = count runs after count += 1, so it copies the new count.

A var can hold other kinds of value too. var shown: string = "" holds text, and a handler can write a whole message into it: shown = "Welcome".

Use it: a press-count sign

The first example is already a useful part: a visitor counter for a door, or a score for a button game.

Make

Make a sign that counts presses of one button and resets to 0 when a second button is pressed.

button1 Held -> chip pressed
button2 Held -> chip reset
chip text -> decal Text

Next: Reacting to the Game.

Reacting to the Game

Handlers so far ran when a pin turned on. The game itself also starts handlers: a clock that ticks, the chip loading, a player walking into a zone. This lesson also adds if, constants and the arithmetic shortcuts.

Contents

• A clock
• When it loads
• Someone walks in
• Deciding with if
• Shortcuts
• Good to Know
• Make

A clock

const BLINK_SECONDS = 0.5

var lit: bool = false
@right out light = lit.Value

on Clock(interval = BLINK_SECONDS) {
  lit = !lit
}

on Clock(interval = ...) runs its handler every interval seconds, forever. const BLINK_SECONDS = 0.5 names a fixed value. Change it in one place to change the speed.

Wire light to a Point Light’s Enabled. It is on for half a second, then off for half a second.

When it loads

var loads: int = 0
@right out sign = "Loads: ${loads.Value}"

on Loaded() {
  loads += 1
}

on Loaded() runs its handler once when the chip is pasted, and once more each time the world loads with it in. Wire sign to the Text of a brick with a Text Decal: it reads “Loads: 1” as soon as you paste it. A variable keeps its value when the world is saved, so after the next load it reads “Loads: 2”.

Use on Loaded() to set a circuit up: fill a list, send a first message, start a sign at the right text.

Someone walks in

import { escape } from "sanitize"

@left in room: zone

on ZoneEntered(zone = room) -> (character) {
  character.ShowChatMessage("Hello, ${escape(character.GetDisplayName())}!")
}

@left in room: zone is a pin for a zone. Give a brick an Attached Zone and wire its Zone Ref output to room. on ZoneEntered(zone = room) runs when a player walks into it, and -> (character) names the player who did. ShowChatMessage sends a message only that player sees.

A display name is chosen by the player and can contain <, which text displays read as the start of formatting. import { escape } from "sanitize" brings in one helper from the lessons’ starter library, sanitize.ws, which makes a name safe to show. The Compile button fetches the library with the example; to build it in the playground or VS Code, save the starter library beside your file. Use it whenever a circuit shows text a player chose.

Deciding with if

@left in pressed: exec
var count: int = 0
@right out text = "Count: ${count.Value}"

on pressed {
  if count >= 9 {
    count = 0
  } else {
    count += 1
  }
}

if runs one block or the other. This counter goes up to 9, then back to 0. >= compares, as do ==, <, >, <= and !=.

Shortcuts

count += 1 is count = count + 1. The same works for -=, *= and /=.

Good to Know

• Clock starts when the chip loads and keeps going. Give it enabled = someBool to turn it on and off. Its first pulse comes one interval after it starts, not at once.
• ZoneEntered and ZoneLeft are right for reacting to one player, like this greeting. Over a long game a few can be missed, so do not keep a list or a count of who is inside from them. To know who is in a zone, ask the zone itself with fillFromZonePlayers (Ready Check), on a Clock when it must stay current.
• Some events and actions only an admin may use: a chip containing them is blocked when someone without admin rights pastes it. Chat commands, the list of every player, broadcasts to everyone, and the world’s weather and time of day are among them. Lessons that need them are marked “needs admin to load” in the tree.

Make

Make a light that blinks only while a switch is on (on Clock(interval = 0.5, enabled = ...)), and a door that opens for three seconds whenever someone walks into a zone in front of it.

switch Enabled -> chip blinking
chip light -> light Enabled
zone "Zone Ref" -> chip room
chip solid -> changer "Collision Enabled"
chip solid -> changer Visibility

Next: Is It Working?.

Is It Working?

When a circuit does nothing, the compiler usually cannot tell you why. The wires are valid but do not do what you meant. This lesson is about seeing inside a running circuit.

Contents

• Show the values
• Silent failures to check first
• Testing alone
• Make

Show the values

Add a debug output that turns the circuit’s state into text, and wire it to a Text Decal. To see each time a handler runs, send a chat line from it:

const NEEDED = 3

@left in pressed: bool
var count: int = 0
@right out lit = count.Value >= NEEDED
@right out debug = "pressed: ${pressed}  count: ${count.Value}  lit: ${lit}"

on pressed {
  count += 1
  BroadcastChatMessage("button pressed, count is now ${count}")
}

The sign shows what the circuit sees, live, and the chat line appears each time the handler runs. If no line appears when you press, the handler’s trigger is the problem, not its steps. Remove both once the circuit works.

BroadcastChatMessage sends to everyone in the world, and only an admin can load a chip that uses it. Use it on your own server while you debug, and take it out before you share the circuit.

Silent failures to check first

• A pin is not wired. An unwired input reads as zero, false or empty. If a handler never runs, check its trigger pin’s wire first.
• A wire goes to the wrong port. Components have many inputs. The light’s Enabled and Cast Shadows are both bools.
• Reading a list past its end gives the last value read, not zero, so a wrong index can look almost right.
• A handler that waits forever. A chain paused at an await that never resumes runs the steps before it and never the ones after. The circuit looks half working.

Testing alone

Most circuits can be tested by one player: buttons, switches, zones and clocks all work with only you in the world. When a circuit is for several players, test each piece alone first, then together.

Make

Take the circuit from Remembering Values and add a debug pin that shows the count and whether the last press was the button’s first.

button Held -> chip pressed
chip text -> decal1 Text
chip debug -> decal2 Text

Next: pick a lesson from the tree on the Learn page.

Wirescript for Programmers

If you already program, most of Wirescript reads like a small typed language. This page lists what works differently, then gives a short test for every lesson so you can skip the ones you already understand.

Contents

• What is different
• Test out
• Where to go next

What is different

• The program is a circuit. A compiled file is one microchip of gates and wires, and every gate evaluates every tick, 60 times a second. There is no main and no instruction pointer: @right out lit = a && b is an AND gate that is always computing.
• Two contexts, pure and exec. Pure expressions are wiring: they follow their inputs. Exec code lives in handlers and runs as a chain of steps, in order. Writes, array reads, Random and for are steps, so they only exist in a handler. See Pure and Exec.
• let is a wire, var is storage. A let names a gate’s output and costs nothing. A var is a Var gate that only handlers write. Every var survives a world save and load. Nothing resets unless you build a reset.
• Two ways to read a var. count.Value is a pure wire holding the value as of the start of this tick. Bare count inside a handler reads it at that step, so it sees a write made earlier in the same chain.
• Handlers fire on edges. A pin that only starts handlers is declared exec (@left in pressed: exec). Wire a bool output such as a Button’s Held into it and on pressed { ... } runs once when Held turns on. Holding a button is one press. on !pressed runs when it turns off. It reads the value, so declare pressed: bool for that. The game starts handlers too: on Clock(interval = 0.5), on ZoneEntered(zone = room) -> (character).
• Handlers have no order between them. Two on roots that fire in the same tick, a Clock included, run in no fixed order. Order exists only inside one chain.
• No short-circuiting. Both sides of && and || are wires into one gate, so both are always computed. In a handler, a call with side effects on the right still runs when the left already decides: guard it with a nested if.
• Time is explicit. await Sleep(_, delay = 1.0) pauses a chain, and await hit waits for a pulse (one that came earlier is dropped). buffer before = x is x one tick ago, and a loop of pure wires needs one.
• No loops in pure code. for i in 0..n { } is a step. It compiles to a loop plane, a chip of its own that runs every iteration within the current tick, about 100,000 iterations per tick at most. Work spread over many ticks is a buffer emit and an await.
• mod inlines, fn calls. A mod’s body is copied into every call: 50 gates called from 10 places is 500 gates. A fn is one callable plane with a Function Call gate per call. It reads a pin or a let only as a parameter (WS113) and cannot return a record or an enum (WS114).
• Failures are silent numbers. Divide or remainder by zero gives 0. An unwired input reads 0, false or empty. A read past the end of an array gives that gate’s previous value, not 0: check .OutOfBounds, and .Found for a map key.
• Players are keyed by user id. A death makes a new character, so per-player state lives in a Map<string, T> keyed by GetUserId().
• Some gates need admin. Broadcasts, chat commands, player join, leave, spawn and death events, and environment writes only load for an admin. The rest of the chip loads without them.

This chip uses most of the list:

@left in pressed: exec
@left in reset: exec
var count: int = 0
var squares: int[]
var total: int = 0
var big: int = 0
buffer before: int = count.Value
@right out sign = "count ${count.Value}, a tick ago ${before}, sum ${total.Value}, ${big.Value} over 10"

fn square(n: int) -> int {
  return n * n
}

on pressed {
  count += 1
  squares.push(square(count))
  total = squares.sum()
  var n: int = 0
  for s in squares {
    if s > 10 {
      n += 1
    }
  }
  big = n
  await Sleep(_, delay = 1.0)
  count += 1
}

on reset {
  count = 0
  total = 0
  big = 0
  squares.clear()
}

squares.sum() is one gate. A for runs its body once per element, so keep it for work no single array method does, like the count here. An array read in pure code is an error, not a wire:

var squares: int[]
@left in i: int
@right out pick = squares[i]

Test out

Answer the questions for a lesson without looking. If you get them right, skip the lesson. Open the answers to check.

Basics

1. Tools: why does @left in on: bool fail to compile?
2. First Circuit: how many gates does @right out b = a make?
3. Gates and Wires: let both = a && b, then two outputs both and !both. How many gates?
4. Pure and Exec: what does on pressed fire on, level or edge? How many times while the button is held?
5. Remembering Values: in on pressed { count += 1; last = count }, does last get the old count or the new one?
6. Reacting to the Game: run a handler every half second, and greet the player who walks into a zone.
7. Is It Working?: name three reasons a circuit can do nothing with no error.

Branches

• State. Reading a Variable: in a handler, right after count += 1, what does count.Value read? Buffers: build a set/reset latch from pure wires. Variables, Resetting: what does a var hold after the world is saved and loaded?
• Values. Numbers: what is 7 / 0? Lists: what does xs[5] give on a three-element array? Maps: how do you tell a missing key from one that holds 0? Converting Values: what type does round(2.6) return?
• Logic. Choosing a Value: what does a pure if c then x else y compile to, and does a divide by zero in the arm not taken do harm? Toggles and Latches: a button that turns a light on and off.
• Strings. Text Values: is "0" true or false? Safe Text: why escape a display name?
• Templates. Interpolation: what does "${true}" print? Word Forms: print a bool as “Yes” or “No”.
• Events. Custom Events: what does the receiver get for a constant argument? Waiting: what happens to a pulse that arrives before its await?
• Abstraction. Mods and Functions: when is a fn smaller than a mod? Imports: what happens to a library’s on handlers under import { name } from "lib"?
• Data Shapes. Records in Storage: how many gates does a var holding { x: int, y: int } cost?
• Enums. Enums from Pins: what does a match give for an int that names no variant? Option and Result: read the value out of an Option.
• Loops. Counting Loops: how long does a 1,000-iteration for take? Loops Across Ticks: a back-edge loop sits inside an if. Where must its let x: exec signal be declared?
• Random. Dice: can Random(1, 6) give 6? How do you use one roll in two places?
• Input. Seat Controls: does on input.Forward > 0.5 run every tick the key is held? Remote Control: how does a circuit read the keys of a player who is not sitting anywhere?
• References. Per-Player State: why not key a score map by character? Ref Values: what happens when a handler reads through an empty ref?
• Prefabs. Lifecycle and Storage: do a spawned copy and its spawner share variables? Talking to a Copy: can a copy’s handlers run before the spawner’s first event arrives?
• Admin. Admin Gates: what happens when a player without admin rights pastes a chip with one admin gate in a handler?

Where to go next

• Syntax, Types and Statements: the language in full.
• Execution Context: pure and exec in detail.
• Best Practices: gate counts and how programs scale.
• Parts: ready-made circuits to paste and read.
• The Learn tree, for any lesson you did not test out of.

Variables

The Remembering Values lesson used one var to count presses. This lesson covers what a variable can hold, how it differs from a let, and how long it remembers.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

button Held -> chip toggle
chip text -> decal Text
chip lamp -> light Enabled

Code

@left in toggle: exec
var isOpen: bool = false
var opened: int = 0
let word = if isOpen.Value then "OPEN" else "CLOSED"
@right out text = "${word} (opened ${opened.Value} times)"
@right out lamp = isOpen.Value

on toggle {
  isOpen = !isOpen
  if isOpen {
    opened += 1
  }
}

A shop sign with a button behind the counter. There are two variables, each with a type and a starting value: isOpen is a bool that starts false, and opened is an int (a whole number) that starts at 0.

word is a let. if isOpen.Value then "OPEN" else "CLOSED" picks one of two values. Unlike the if block in a handler, it runs no steps: it is a gate that always shows one value or the other, and it changes the moment isOpen does. A let holds nothing of its own.

Press the button three times, then save the world and load it again. What does the sign say?

Run

1. Compile the chip and paste it in-game. Place a Button, a brick with a Text Decal, and a Point Light.
2. Wire the Button’s Held to toggle, text to the Text Decal’s Text, and lamp to the Point Light’s Enabled.
3. Press the button. The sign reads “OPEN (opened 1 times)” and the light comes on. Press again: “CLOSED”, light off, and the count stays at 1.
4. Save the world and load it. The sign and the light come back exactly as you left them.

Under the Hood

Open the chip. Each var is a Variable gate (the game names it Var), with its starting value written into the gate. The let is a Select gate wired from isOpen’s Variable gate. It picks a value and stores nothing.

The handler is a chain: a Get Variable reads isOpen, a NOT flips it, a Set Variable stores it, a second Get Variable reads it for the if, and a Branch picks the path. opened += 1 is a single Increment Variable gate.

The Variable gates are part of the chip’s bricks, so their values are saved with the world and come back when it loads.

A variable can hold any one kind of value: bool, int, float (a number with a fraction), string (text), and more that later lessons cover. Leave out the starting value and it starts at that type’s zero: var count: int starts at 0, var label: string starts empty.

Modify

1. Change var isOpen: bool = false to true. A freshly pasted copy now starts open, with the light on.

2. Add a variable declared inside the handler:

   @left in pressed: exec
   var kept: int = 0
   var lastLocal: int = 0
   @right out text = "kept ${kept.Value}, local ${lastLocal.Value}"
   
   on pressed {
     var local: int = 0
     local += 1
     kept += 1
     lastLocal = local
   }
   

   Press a few times. kept climbs, but local is always 1. A var inside a handler is set back to its starting value every time the handler runs. In the chip, that is an extra Set Variable at the start of the chain. A var at the top of the file keeps its value between runs.

3. Count closings too: add var closed: int = 0, add one to it in an else branch of the if, and show both counts on the sign.

Make

Make a lamp with two buttons, On and Off. A variable remembers whether the lamp is on, the light follows it, and a sign shows how many times it has been switched on. Pressing On while it is already on should not add to the count. Save and load the world to check that it remembers.

button1 Held -> chip turnOn
button2 Held -> chip turnOff
chip lamp -> light Enabled
chip text -> decal Text

Good to Know

• Every var at the top of a file is stored in the chip’s bricks, so a world save and load brings each value back as it was. Nothing starts over by itself. For a fresh start, the circuit needs a way to set its variables back.
• You may meet static var in the reference. It keeps its value inside a mod. At the top of a file a plain var already does, so these lessons never need it.

Next: Reading a Variable.

Reading a Variable

There are two ways to read a variable, and they can give different answers in the same moment. This lesson shows when each one sees a new value.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

button Held -> chip pressed
chip text -> decal Text

Code

@left in pressed: exec
var count: int = 0
var before: int = 0
var after: int = 0
@right out text = "before ${before.Value}, after ${after.Value}, now ${count.Value}"

on pressed {
  before = count
  count += 1
  after = count
}

Inside the handler, the bare name count reads the variable at that step of the chain. before = count runs before the add, and after = count runs after it. Outside the handler, count.Value is a pure wire from the Variable gate.

What does the sign say after the first press? After the second?

Run

1. Compile the chip and paste it in-game. Place a Button and a brick with a Text Decal.
2. Wire the Button’s Held to pressed, and text to the Text Decal’s Text.
3. Press once. The sign reads “before 0, after 1, now 1”. Each press moves all three along by one.

Under the Hood

Open the chip. The handler’s chain has two Get Variable gates for count: one before the Increment Variable and one after it. Each Get Variable reads the variable when the chain reaches it, so the second one sees the new value.

The text has no Get Variable at all. Its Format String gate is wired straight from the Variable gates’ value outputs.

The game updates every wire about 60 times a second. Each update is a tick. A handler’s steps all run inside one tick, one after another. Pure gates, and the .Value wires they read, settle once per tick, so while a handler runs they still show what the variable held when the tick began. The sign shows the new count one tick after the press, far too soon to notice.

Modify

1. Swap the first two lines of the handler so count += 1 comes first. Now before and after always match.

2. Build some text from count.Value in a let, and copy it in the handler:

   @left in pressed: exec
   var count: int = 0
   var copied: string = ""
   let label = "count is ${count.Value}"
   @right out text = copied.Value
   
   on pressed {
     count += 1
     copied = label
   }
   

   Press once: the sign says “count is 0”. label is a pure wire, and at the moment the handler copies it, it has not caught up with the add yet. Each press shows the count from before that press.

3. Fix it by building the text inside the handler, where the bare name reads the new value:

   @left in pressed: exec
   var count: int = 0
   var copied: string = ""
   @right out text = copied.Value
   
   on pressed {
     count += 1
     copied = "count is ${count}"
   }
   

   When the text only shows the count, it needs no copy at all: @right out text = "count is ${count.Value}" builds it outside the handler, with no extra variable, and follows each press a tick later.

Make

Make a dice sign. Each press of a button rolls a new number with Random(1, 6), which gives a whole number from 1 to 6 and, like a variable write, runs as a step inside a handler. The sign shows this roll and the one before it: “now 4, before 2”. Think about which line has to come first.

button Held -> chip roll
chip text -> decal Text

Good to Know

• Outside a handler, count.Value is the value as of the start of this tick. You will also see a bare count used outside a handler: it is the same read. These lessons write .Value so the delay is visible in the code.
• Inside a handler, count.Value is still that same pure wire, so after a write it shows the old value. Read the bare name, count, instead.
• Text built in a let and used by a handler that has just written one of its variables shows the value from before the write. It looks like a display that lags one press behind.

Next: Buffers.

Buffers

A buffer passes a value on one tick late. With that delay a circuit can feed its own output back into itself, so memory can be built from gates alone, with no variable and no handler.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

button1 Held -> chip set
button2 Held -> chip reset
chip alarm -> light Enabled

Code

@left in set: bool
@left in reset: bool
let state = set || (held && !reset)
buffer held: bool = state
@right out alarm = state

This is a latch: set turns it on, reset turns it off, and it remembers in between.

buffer held: bool = state makes held whatever state was one tick ago. The line above already uses held, before it is declared: that is the loop. state is on while set is pressed, or while it was on a tick ago and reset is not pressed.

Walk through it. Press set: state turns on. A tick later held is on, so state stays on after you let go. Press reset: state turns off, and a tick later so does held.

What happens if you hold both buttons at once?

Run

1. Compile the chip and paste it in-game. Place two Buttons and a Point Light.
2. Wire one Button’s Held to set, the other’s Held to reset, and alarm to the Point Light’s Enabled.
3. Press set: the light comes on and stays on. Press reset: it goes off and stays off. Hold both: set wins, and the light is on.

Under the Hood

Open the chip. There is an OR, an AND, a NOT and one Buffer (Ticks) gate set to wait one tick. Follow the wires: OR, into the buffer, into the AND, and back into the OR. The wires make a loop, and the buffer sits in it.

Every loop of wires needs a buffer somewhere in it. The game works out all pure gates together each tick, and a loop without a delay would need its own answer before it could work out its answer. The compiler refuses one. Here an output pin feeds itself:

@left in set: bool
@left in reset: bool
@right out alarm: bool = set || (alarm && !reset)

Error: [WS005] cycle in the wire graph has no barrier (a Buffer, Queue or EdgeDetector must break it); 3 gate(s) in the loop:

The error goes on to list each gate in the loop. Put a buffer anywhere in it and the loop is legal.

The : bool on the buffer matters. state uses held before the compiler reaches the buffer’s line, so without a type it does not yet know what held holds:

@left in set: bool
@left in reset: bool
let state = set || (held && !reset)
buffer held = state
@right out alarm = state

Error: [WS004] no overload for '&&' on any, bool

The message is about &&, but the fix is on the next line: give the buffer its type.

Modify

1. Make reset win when both are held: let state = !reset && (set || held).

2. A buffer can count ticks. This one adds one to its own value every tick:

   buffer tick: int = tick + 1
   @right out text = "Ticks: ${tick}"
   

   Wire text to a Text Decal’s Text. It climbs by about 60 every second.

3. Turn the latch into a burglar alarm. Give a brick an Attached Zone and wire its Occupied output to set instead of the first button. The light comes on when someone walks in and stays on after they leave, until the reset button is pressed.

Make

Make a quiz buzzer for two players. Each player has a button and a light. The first to press lights their own light, and the other player’s button then does nothing until a third button resets both. Use one latch per player, and let each latch’s set be blocked by the other latch.

button1 Held -> chip buzz1
button2 Held -> chip buzz2
button3 Held -> chip reset
chip lit1 -> light1 Enabled
chip lit2 -> light2 Enabled

Good to Know

• A buffer delays by one tick, about a sixtieth of a second, so the delay itself is too short to see.
• on already runs once when a button goes down, not while it is held. You do not need a buffer to catch the moment of a press.
• A buffer read before its declaration needs a type. Without one the compiler reports WS004, pointing at whatever operator first uses the buffer.

Next: Resetting.

Resetting

Variables keep their values through presses, players and world loads. Nothing starts over by itself, so most circuits with state need a reset: one input that puts every variable back where it began.

Contents

• Code
• Run
• Under the Hood
• Use it: a reset that passes on
• Modify
• Make
• Good to Know

button1 Held -> chip red
button2 Held -> chip blue
button3 Held -> chip reset
chip text -> decal Text

Code

@left in red: exec
@left in blue: exec
@left in reset: exec
var redScore: int = 0
var blueScore: int = 0
var lastPoint: string = "none"
@right out text = "Red ${redScore.Value}, Blue ${blueScore.Value} (last: ${lastPoint.Value})"

on red {
  redScore += 1
  lastPoint = "red"
}

on blue {
  blueScore += 1
  lastPoint = "blue"
}

on reset {
  redScore = 0
  blueScore = 0
  lastPoint = "none"
}

A scoreboard for two teams. Each team’s button adds a point and records who scored last. The reset handler writes every variable back to the value it was declared with.

After a few points, what does the sign say right after a reset?

Run

1. Compile the chip and paste it in-game. Place three Buttons and a brick with a Text Decal.
2. Wire the Buttons’ Held outputs to red, blue and reset, and text to the Text Decal’s Text.
3. Score a few points for each team. Press reset: the sign reads “Red 0, Blue 0 (last: none)”, the same as when it was pasted.

Under the Hood

Open the chip. There are three chains, one per handler. The reset chain is three Set Variable gates in a row, each writing a constant, wired from the reset pin.

When you add a variable to a circuit, add it to the reset handler too. A variable left out keeps its old value through every reset, which can look like a bug somewhere else.

Use it: a reset that passes on

A bigger build has several chips, each with its own state. Instead of running a wire from one reset button to every chip, each chip can pass the reset on to the next once it has finished its own. This is a daisy chain.

@left in point: exec
@left in reset: bool
var score: int = 0
var passing: bool = false
@right out text = "Score: ${score.Value}"
@right out resetNext = passing.Value

on point {
  score += 1
}

on reset {
  score = 0
  passing = true
}

on !reset {
  passing = false
}

resetNext turns on after this chip’s reset steps have run, and turns off when the reset button is let go. on !reset runs when reset turns off. It reads the pin’s value, so reset is a bool in this chip. Wired into the next chip’s reset, that rising resetNext starts the next chip’s reset, and so on down the line.

1. Paste the chip three times. Give each copy its own Button on point and its own Text Decal on text.
2. Wire a Button’s Held to the first copy’s reset. Wire the first copy’s resetNext to the second copy’s reset, and the second’s resetNext to the third’s reset.
3. Score a few points on each, then press the reset button. All three signs go back to 0, each one just after the one before it.

Modify

1. Wire an Attached Zone’s Occupied output to reset instead of the button. The scores clear whenever someone steps into the zone.

2. Keep a best score that survives a reset. Add var best: int = 0, set it whenever a team’s score passes it, show it on the sign, and leave it out of the reset handler.

3. Flash a light for two seconds after each reset. Add var flash: bool = false and @right out light = flash.Value, then end the reset handler with:

     flash = true
     await Sleep(_, delay = 2.0)
     flash = false
   

Make

Make a round counter chip with @left in reset: exec that counts how many times it has been reset, and shows “Round 3” on a sign. Put it at the end of a chain of two scoreboards, so one button clears the scores and starts a new round.

circuit1 "Scoreboard"
circuit2 "Scoreboard"
chip "Round"
button1 Held -> circuit1 point
button2 Held -> circuit2 point
button3 Held -> circuit1 reset
circuit1 resetNext -> circuit2 reset
circuit2 resetNext -> chip reset
circuit1 text -> decal1 Text
circuit2 text -> decal2 Text
chip text -> decal3 Text

Good to Know

• A world save and load keeps every variable, so a circuit starts over only when its reset runs.
• A Button’s Held stays on for as long as it is held, but on reset runs once per press. Holding the reset button does not keep resetting.

Next: pick a lesson from the tree on the Learn page.

Numbers

Wirescript has two kinds of number. An int is a whole number. A float is a number that can have a fraction, like 2.5. Both are 64-bit, which means an int can go up to 9,223,372,036,854,775,807, and a float can hold very large and very small numbers. This lesson is about what happens when you divide them.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

button1 Held -> chip addPizza
button2 Held -> chip addPerson
chip text -> decal Text

Code

@left in addPizza: exec
@left in addPerson: exec
var pizzas: int = 0
var people: int = 0
let slices = pizzas.Value * 8
let each = slices / people.Value
let spare = slices % people.Value
@right out text = "${slices} slices, ${people.Value} people: ${each} each, ${spare} spare"

on addPizza {
  pizzas += 1
}

on addPerson {
  people += 1
}

Each pizza has 8 slices, shared between everyone. * multiplies. / divides, and an int divided by an int gives an int: the remainder is dropped, so 7 / 2 is 3. % gives the remainder that / dropped, so 7 % 2 is 1.

With 2 pizzas and 3 people, how many slices does each person get, and how many are spare? What does the sign say with 1 pizza and nobody there yet?

Run

1. Compile the chip and paste it in-game. Place two Buttons and a brick with a Text Decal.
2. Wire the Buttons’ Held outputs to addPizza and addPerson, and text to the Text Decal’s Text.
3. Add one pizza before anyone arrives. The sign reads “8 slices, 0 people: 0 each, 0 spare”. Dividing by zero gives 0, not an error.
4. Add 3 people and another pizza: “16 slices, 3 people: 5 each, 1 spare”.

Under the Hood

Open the chip. There is one Multiply, one Divide and one Modulo gate, all pure, wired from the two Variable gates. Divide and Modulo both take slices and people, so they always agree with each other.

A number written with a point, like 8.0, is a float. Without one, like 8, it is an int. When one side of +, -, *, / or % is a float, the result is a float and keeps its fraction: 7.0 / 2 is 3.5.

Modify

1. Show the exact share in pizzas. as float turns a value into a float before the divide:

   @left in addPizza: exec
   @left in addPerson: exec
   var pizzas: int = 0
   var people: int = 0
   let share = pizzas.Value as float / people.Value
   @right out text = "Each person gets ${share} pizzas"
   
   on addPizza {
     pizzas += 1
   }
   
   on addPerson {
     people += 1
   }
   

   as applies before the /, so this is (pizzas as float) / people. With 2 pizzas and 4 people, each person now gets half a pizza instead of 0.

2. Order enough pizza. Everyone wants 3 slices, and pizzas come whole. Show how many to buy: (people.Value * 3 + 7) / 8. Adding 7 before dividing by 8 rounds up instead of down. Try it with 1, 3 and 8 people.

3. Take a square root of a number that goes negative:

   @left in down: exec
   var level: float = 4.0
   @right out text = "sqrt(${level.Value}) = ${sqrt(level.Value)}"
   
   on down {
     level -= 2.0
   }
   

   The first press shows the root of 2. The second shows the root of 0. The third asks for the root of -2, which has no answer as a real number: the sign shows 0.

Make

Make a stopwatch. While a Switch is on, a Clock adds one to an int every tenth of a second (on Clock(interval = 0.1, enabled = running)). The sign shows the time as seconds and tenths, like “12.3 s”, using / and % on the int. A Button sets it back to 0.

switch Enabled -> chip running
button Held -> chip reset
chip text -> decal Text

Good to Know

• Dividing by zero, or taking the remainder by zero, gives 0.
• A result that is not a real number, such as the square root of a negative number, or one too large for a float, is read as 0 by the gate it goes into.

Next: True and False.

True and False

A bool is the simplest value: true or false. Switches and buttons give bools, lights take them, and every comparison makes one. This lesson also shows what happens when a bool meets a number.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

switch1 Enabled -> chip a
switch2 Enabled -> chip b
switch3 Enabled -> chip c
chip text -> decal Text
chip passed -> light Enabled

Code

@left in a: bool
@left in b: bool
@left in c: bool
let votes = a + b + c
@right out text = "${votes} of 3 say yes"
@right out passed = votes >= 2

Each of three judges has a switch. When a bool is used in arithmetic, true counts as 1 and false as 0, so a + b + c is the number of switches that are on.

votes >= 2 compares two numbers and gives a bool: true when there are at least two yes votes. The other comparisons work the same way: == (equal), != (not equal), <, >, <= and >=.

With two switches on, what does the sign say, and is the light on?

Run

1. Compile the chip and paste it in-game. Place three Switches, a brick with a Text Decal, and a Point Light.
2. Wire each Switch’s Enabled to a, b and c. Wire text to the Text Decal’s Text and passed to the Point Light’s Enabled.
3. Flip the switches. The sign counts the yes votes, and the light is on with two or three of them.

Under the Hood

Open the chip. Two Add gates sum the three pins, and a Greater/Equal gate compares the total with 2. No gate turns the bools into numbers first: the Add gate takes them as they are.

A comparison is a gate like any other, and its bool output can go anywhere a bool can: a light, an if, a variable, or another operator such as &&.

Modify

1. Show each vote on the sign: "${a} ${b} ${c}: ${votes} of 3". A bool in text shows as true or false.

2. Give judge a two votes: let votes = a * 2 + b + c. Now a and one other judge are enough, but b and c alone are not.

3. Combine comparisons on a stored number. This chip counts presses and its light is on only for even counts above 5:

   @left in pressed: exec
   var count: int = 0
   let isEven = count.Value % 2 == 0
   let big = count.Value > 5
   @right out text = "${count.Value}: even ${isEven}, big ${big}"
   @right out lamp = isEven && big
   
   on pressed {
     count += 1
   }
   

   count.Value % 2 == 0 reads as “the remainder after dividing by 2 is 0”. % comes before ==, as * comes before +.

Make

Make a “two-key” vault door: two switches far apart must both be on, and the door opens only if the number of presses on a third button is exactly 3. Wire the result to a Brick Property Changer’s Collision Enabled and Visibility so the door vanishes when it opens.

switch1 Enabled -> chip key1
switch2 Enabled -> chip key2
button Held -> chip pressed
chip solid -> changer "Collision Enabled"
chip solid -> changer Visibility

Good to Know

• A number used where a bool is wanted is true when it is not zero, so -1 as a condition is true.
• But comparing a bool with a number compares it as exactly 1 or 0: 1 == true is true, and -1 == true is false.
• a == b on two bools is true when they match, both on or both off: the opposite of ^^.

Next: Vectors and Colors.

Vectors and Colors

Some values are made of several numbers. A color is four: red, green, blue and alpha. A vector is three, a point or a direction: x, y and z. A rotator is three angles: pitch, yaw and roll. This lesson builds them, takes them apart, and puts a color on a light.

Contents

• Code
• Run
• Under the Hood
• Taking values apart
• Modify
• Make
• Good to Know

switch1 Enabled -> chip red
switch2 Enabled -> chip green
switch3 Enabled -> chip blue
chip lamp -> light Color
chip lit -> light Enabled

Code

@left in red: bool
@left in green: bool
@left in blue: bool
@right out lamp = Color(red, green, blue)
@right out lit = red || green || blue

Color(r, g, b) makes a color from three numbers, each from 0 (none) to 1 (full). A fourth number, alpha, is optional. Here each channel comes from a switch: a bool is 1 when on and 0 when off, so each switch turns one channel fully on or off.

With the red and green switches on and blue off, what color is the light?

Run

1. Compile the chip and paste it in-game. Place three Switches and a Point Light. Turn off the light’s Use Brick Color setting: while it is on, the light takes the brick’s color and ignores the wire.
2. Wire each Switch’s Enabled to red, green and blue. Wire lamp to the Point Light’s Color and lit to its Enabled.
3. Try the switches. Red and green together make yellow, all three make white, and with all three off the light is off.

Under the Hood

Open the chip. Color(...) is one Make Color gate with the three pins wired into its R, G and B inputs. lit is two OR gates.

Taking values apart

Each part of a value has a name: .r .g .b .a on a color, .x .y .z on a vector, and .pitch .yaw .roll on a rotator. Each reads one float.

@left in pressed: exec
var spot: vector = Vec(0.0, 0.0, 0.0)
let step = Vec(1.0, 2.0, 0.5)
@right out text = "${spot.Value as string}, height ${spot.Value.z}"

on pressed {
  spot = spot + step
}

Vec(x, y, z) makes a vector. + on two vectors adds them part by part, so each press moves spot by 1 along x, 2 along y and 0.5 along z. spot.Value as string writes the whole vector as text, X=1.000 Y=2.000 Z=0.500 after the first press, and spot.Value.z reads just the height.

Reading a part is a Split Vector gate (or Split Color, Split Rotation). Reading several parts of the same value the same way (.x, .y, .z) shares one split gate.

Modify

1. Add a @left in dim: bool pin and dim the light while it is on: @right out lamp = if dim then Color(red, green, blue) * 0.25 else Color(red, green, blue). A number times a color multiplies every channel.

2. Pick a random color on each press. Random on two colors picks each channel at random between them:

   @left in pressed: exec
   var shade: color = Color(1.0, 1.0, 1.0)
   @right out lamp = shade.Value
   @right out text = shade.Value.ToHex()
   
   on pressed {
     shade = Random(Color(0.0, 0.0, 0.0), Color(1.0, 1.0, 1.0))
   }
   

   Like a variable write, Random runs as a step in a handler. .ToHex() turns a color into text, so a sign can show which color was picked.

3. Turn a rotator one eighth of a circle per press. Rotation(pitch, yaw, roll) takes angles in degrees:

   @left in pressed: exec
   var steps: int = 0
   let facing = Rotation(0.0, steps.Value * 45.0, 0.0)
   @right out aim = facing
   @right out text = "yaw ${facing.yaw}"
   
   on pressed {
     steps = (steps + 1) % 8
   }
   

   A Spot Light has a Rotation input that takes a rotator. Wire aim to it, and text to a Text Decal to watch the yaw count up by 45.

Make

Make a light that steps from blue to red. Each press moves it one step of five, and the sixth press starts again at blue. Keep a step count with %, and mix the two colors with arithmetic: Color(1.0, 0.0, 0.0) * t + Color(0.0, 0.0, 1.0) * (1.0 - t), where t is a float that goes from 0.0 (blue) to 1.0 (red).

button Held -> chip pressed
chip lamp -> light Color

Good to Know

• Color channels run from 0 to 1, not 0 to 255. ColorSRGB(255, 128, 0, 255) builds a color from 0 to 255 values instead.
• Random on two colors picks all four channels at random, alpha included.
• Asking a value for a part it does not have, such as .z on a color, is a compile error, never a silent zero.

Next: Converting Values.

Converting Values

Values often need to change type: a whole number into a float so a divide keeps its fraction, a float back into a whole number, a number into text. Some conversions happen by themselves. For the rest, as asks for one.

Contents

• Code
• Run
• Under the Hood
• Conversions that happen by themselves
• What as converts
• any
• Modify
• Make
• Good to Know

button Held -> chip roll
chip text -> decal Text

Code

@left in roll: exec
var total: int = 0
var rolls: int = 0
var last: int = 0
let average = total.Value as float / rolls.Value
let nearest = round(average) as int
@right out text = "Rolled ${last.Value}. Average ${average}, about ${nearest}"

on roll {
  last = Random(1, 6)
  total += last
  rolls += 1
}

Each press rolls a die. Random(1, 6) gives a whole number from 1 to 6, and runs as a step in the handler like a variable write. The handler adds the roll to total and counts it in rolls.

value as T converts a value to type T. total.Value as float turns the total into a float before the divide, so the average keeps its fraction. round(average) rounds to the nearest whole number, but its answer is still a float. as int makes it an int.

After rolling a 3 and then a 4, the average shows its fraction. What would it show without as float?

Run

1. Compile the chip and paste it in-game. Place a Button and a brick with a Text Decal.
2. Wire the Button’s Held to roll, and text to the Text Decal’s Text.
3. Press a few times. The average moves toward 3.5 as the rolls add up, and about shows the nearest whole number.

Under the Hood

Open the chip. Each as is one Convert gate: one before the Divide, one after the Round. The text needs no Convert of its own: ${} builds the text with a Format String gate, which writes any value it is given.

Conversions that happen by themselves

• bool to a number. true is 1 and false is 0, as in True and False.
• int and float. Mixing them in arithmetic gives a float, as in Numbers.
• Anything into text inside ${}.
• Text to bool, where a bool is wanted: text is true when it is not empty. The compiler checks != "" for you.

@left in pressed: exec
var message: string = ""
@right out lamp: bool = message.Value
@right out text = message.Value

on pressed {
  message = if message == "" then "Hello" else ""
}

Each press shows or clears a message, and the light is on while there is one. The chip has a Not Equal gate between the message and lamp, comparing it with empty text.

What as converts

• bool, int, float and string into one another.
• A float to an int drops the fraction toward zero: 2.7 as int is 2, and -2.7 as int is -2. Use round first to get the nearest instead.
• A number to a bool is true when it is not zero.
• Text to a number reads the number at its start: "42abc" as int is 42, and "abc" as int is 0.
• A vector, rotator or color into text: X=1.000 Y=2.000 Z=3.000 for a vector.

A conversion the game cannot make, such as a vector into a number, would only give the target type’s empty value, so the compiler warns (WS109) instead. The full list is in Type Conversion.

any

any is a type that stands for every type. A pin declared @left in probe: any accepts whatever is wired to it, and probe as string shows it as text:

@left in probe: any
@right out text = probe as string

any throws the type away, so the compiler can no longer check what you do with the value. A variable can hold any too, and keeps whatever kind of value was stored last. To use it as a number again, ask for its type with getType(). Inside the if, the compiler knows held is an int:

@left in probe: any
@left in grab: exec
var held: any = 0
var total: int = 0
on grab {
  held = probe
  if held.getType() is Type.Int {
    total = total + held
  }
}
@right out sum: int = total

Use a real type whenever you know it. The reference covers the rest in any Type.

Modify

1. Remove as float from average. After a 3 and a 4 it shows 3: the divide is now between two ints and drops the remainder.
2. Count sixes. Add var sixes: int = 0, add one when last == 6, and show the share of sixes as a whole percent: `(sixes.Value as float / rolls.Value
   • 100.0) as int`.
3. Light a lamp while the average is above 3.5: @right out lucky = average > 3.5.

Make

Make a fuel gauge. Each press of a button adds 7 liters to a 40-liter tank, but the tank never goes past 40. A sign shows “21 of 40 liters (52%)”, with the percent as a whole number, and a light is on while the tank is at least three quarters full. A second button empties it.

button1 Held -> chip fill
button2 Held -> chip empty
chip text -> decal Text
chip full -> light Enabled

Good to Know

• round, floor, ceil and sqrt give back a float, even when the answer is whole. Add as int when you need an int. min, max, abs and clamp give back the type they are given: an int stays an int.
• Text that does not start with a number converts to 0, with no error.

Next: Lists.

Lists

A variable holds one value. A list holds many: one value per slot, in order. The slots are numbered from 0, so the first value is in slot 0, the second in slot 1, and so on. In code a list is called an array. It is declared with var and keeps its contents between presses.

Contents

• Code
• Run
• Under the Hood
• Reading past the end
• Modify
• Make
• Good to Know

button1 Held -> chip roll
button2 Held -> chip step
chip text -> decal Text

Code

@left in roll: exec
@left in step: exec
var rolls: int[]
var count: int = 0
var index: int = 0
var shown: int = 0
@right out text = "${count.Value} rolls. Roll ${index.Value + 1} was ${shown.Value}"

on roll {
  rolls.push(Random(1, 6))
  count = rolls.length()
}

on step {
  index = (index + 1) % count
  shown = rolls[index]
}

var rolls: int[] is an array of ints. The [] after the type makes it a list. It starts empty. rolls.push(...) adds a value to the end, and rolls.length() says how many there are.

rolls[index] reads one element. The first is at index 0, the second at 1, and so on. Each press of step moves index on by one, and % count wraps it back to 0 after the last roll.

Array reads, pushes and lengths are steps, so they all happen inside handlers. The sign reads from ordinary variables that the handlers fill in.

Roll three times, then press step four times. Which roll does the sign show?

Run

1. Compile the chip and paste it in-game. Place two Buttons and a brick with a Text Decal.
2. Wire the Buttons’ Held outputs to roll and step, and text to the Text Decal’s Text.
3. Roll a few times, then step through them. The sign walks through the rolls in order and wraps around.

Under the Hood

Open the chip. The array is one Array Var gate. The roll chain is a Random, a Push To Array and a Get Array Length. The step chain ends in a Get Array Element. Every one of them has an exec input, because the game has no pure gate that reads an array.

So the compiler refuses an array read outside a handler:

var rolls: int[] = [4, 2, 6]
@right out first = rolls[0]

Error: [WS007] array index read 'rolls[...]' outside an exec context

= [4, 2, 6] makes the array start with those values. It works only for values known when you compile.

Reading past the end

Press step before any roll. There is no element at index 0 yet, but the read does not fail. A read past the end of an array gives back the previous value that gate read, not 0, so a wrong index can look like real data.

Each read also reports .OutOfBounds, which is true when the index was not in the list.

@left in roll: exec
@left in step: exec
var rolls: int[]
var index: int = 0
var shown: int = 0
var missing: bool = false
@right out text = "slot ${index.Value}: ${shown.Value} (missing: ${missing.Value})"

on roll {
  rolls.push(Random(1, 6))
}

on step {
  index += 1
  let item = rolls[index]
  shown = item
  missing = item.OutOfBounds
}

Roll twice, then step. Slot 1 is real. Step again: slot 2 says missing, and still shows slot 1’s roll.

Modify

1. Show the biggest roll so far. In the roll handler, add best = rolls.max().Value with a new var best: int = 0, and show it on the sign. max() is one gate however long the list is. Like an element read, it gives .Value and a second part, .IsEmpty.

2. Add a third button that clears the list: rolls.clear(), then set count and index back to 0.

3. Keep only the last five rolls. After the push, drop the oldest one when there are too many:

   if rolls.length() > 5 {
     rolls.remove(0)
   }
   

   remove(0) takes out slot 0, and every later value moves down a slot.

Make

Make a waiting line. One button hands out tickets numbered 1, 2, 3 and so on, and pushes each number onto the end of a list. A second button serves the ticket at the front: it shows that number on a sign and removes it from the list. The sign also shows how many tickets are waiting. Pressing serve with nobody waiting should not show an old ticket again.

button1 Held -> chip ticket
button2 Held -> chip serve
chip text -> decal Text

Good to Know

• An array starts empty unless its declaration lists constant values.
• A read past the end of an array gives the gate’s previous value, not 0. Check .OutOfBounds whenever the index might be wrong.
• Every rolls[i] is its own gate and its own read. To use one read twice, bind it to a let, as item is above.
• To find a value by a name instead of a slot number, such as a score per player, use a map: the next lesson.

Next: Maps.

Maps

A list finds a value by its slot number. Often what you know is something else: which player walked in, or which team scored. A map files each value under a key you choose, like a phone number filed under a name in an address book. Give it the key and it gives back the value.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

zone "Zone Ref" -> chip room

Code

import { escape } from "sanitize"

@left in room: zone
var visits: Map<string, int>

on ZoneEntered(zone = room) -> (character) {
  let id = character.GetUserId()
  let before = visits.get(id)
  let count = if before.Found then before.Value + 1 else 1
  visits.set(id, count)
  character.ShowChatMessage("Visit number ${count}, ${escape(character.GetDisplayName())}")
}

• Map<string, int> is a map with string keys and int values. The first type in the <> is the key, the second is the value.
• character.GetUserId() is the player’s user id, a string that stays the same for that player on every visit. It is the key.
• visits.get(id) looks the key up and gives two things: .Found, whether the key was there at all, and .Value, the value filed under it.
• if before.Found then before.Value + 1 else 1 picks one of two values: one more than the old count if the player has been here before, 1 if not.
• visits.set(id, count) files the new count under the id, replacing any old one.
• escape(...) makes a name the player chose safe to show in chat.

You walk into the zone three times, then a friend walks in for the first time. What does the friend’s message say?

Run

1. Compile the chip and paste it in-game. Give a brick an Attached Zone.
2. Wire the Attached Zone’s Zone Ref to room.
3. Walk in and out a few times. Each visit, you get a chat message with your count. A second player gets their own count, starting at 1.

Under the Hood

Open the chip. visits is one Map Var gate, and it stays one gate however many players it holds. Its Map Var Ref output is wired into each gate that reads or writes the map.

The handler is a chain. Get User Id turns the character into an id. Get Map Element looks the id up, and Set Map Element files the new count. Both take their Key from the same Get User Id. Between them, an Add works out one more than the old count, and a Select picks it when the Found output is true, or 1 when it is false. The message is a Get User Display Name, a Replace in String for the escape, a Format String and a Show Chat Message. That is eleven gates, plus the zone pin.

Like an array, a map has no pure gate that reads it. Every map gate has an exec input, so a read outside a handler is an error:

var visits: Map<string, int>
@right out first = visits.get("a").Value

Error: [WS007] map read 'visits.get(...)' outside an exec context

To show something from a map on a sign, copy it into a var inside the handler, and wire the sign from that.

Keys can be int, string, a reference to a thing in the world, or a brick. Anything else is an error:

var heights: Map<float, int>

Error: [WS039] map key type must be int, string, an object (entity/character/controller) or a brick, got float

Modify

1. Show how many different players have visited. Add var players: int = 0, and at the end of the handler set players = visits.length(). length() gives the number of keys. Wire @right out sign = "${players.Value} players have visited" to a Text Decal.

2. Add a second zone that makes the chip forget you. has asks only whether a key is there, and remove takes a key and its value out:

   @left in room: zone
   @left in forget: zone
   var visits: Map<string, int>
   
   on ZoneEntered(zone = room) -> (character) {
     let id = character.GetUserId()
     let before = visits.get(id)
     let count = if before.Found then before.Value + 1 else 1
     visits.set(id, count)
     character.ShowChatMessage("Visit number ${count}")
   }
   
   on ZoneEntered(zone = forget) -> (character) {
     let id = character.GetUserId()
     if visits.has(id) {
       visits.remove(id)
       character.ShowChatMessage("Forgotten.")
     } else {
       character.ShowChatMessage("I don't know you yet.")
     }
   }
   

   After the forget zone, your next visit is number 1 again.

3. Give prizes on some visits. The keys of a map do not have to be players: this one is keyed by the visit number, and only three numbers have a prize. A list would need a slot for every number in between.

   @left in room: zone
   var visits: Map<string, int>
   var prizes: Map<int, string> = { 1 => "a sticker", 5 => "a hat", 10 => "a crown" }
   
   on ZoneEntered(zone = room) -> (character) {
     let id = character.GetUserId()
     let before = visits.get(id)
     let count = if before.Found then before.Value + 1 else 1
     visits.set(id, count)
     let prize = prizes.get(count)
     if prize.Found {
       character.ShowChatMessage("Visit ${count}: you win ${prize.Value}!")
     }
   }
   

   { 1 => "a sticker", ... } fills the map when you compile. Each key => value pair is one entry, and the entries are stored in the Map Var gate itself, so they cost no extra gates.

Make

Make a lap counter. Walking into a finish zone adds a lap for that player and tells them their lap count. On their third lap they get “You finished!” and their entry is removed, so they can race again from lap 1. A sign shows how many players are racing right now.

zone "Zone Ref" -> chip finish
chip text -> decal Text

Good to Know

• A map starts empty unless its declaration lists constant keys and values.
• A map holds one value per key. set on a key that is already there replaces its value.
• For a key that might be missing, check .Found or has() rather than counting on what .Value holds.
• Every get is its own gate and its own read. To use one read twice, bind it to a let, as before is above.
• Key players by GetUserId(), not by their character: a player who dies comes back as a new character. Per-Player State compares the keys you could pick and when each one starts over.

See Maps and Map Types in the reference.

Next: pick a lesson from the tree on the Learn page.

Truth Tables

A truth table lists every way a circuit’s inputs can be set, and what its output is for each one. It is the plan for a logic circuit: fill in the table first, then write the expression that matches it.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

switch1 Enabled -> chip a
switch2 Enabled -> chip b
switch3 Enabled -> chip c
chip lit -> light Enabled

Code

Here are the four logic operators from Gates and Wires as one table. 1 means on (true) and 0 means off (false).

• && (AND) is on only in the last row, where both inputs are on.
• || (OR) is off only in the first row, where both are off.
• ^^ (XOR, “exclusive or”) is on when the inputs differ.
• ! (NOT) has one input and gives the opposite.

Two inputs make four rows. Each new input doubles the rows, so three inputs make eight. Here is a vote with three switches: the light turns on when at least two of them are on.

To turn the table into code, read it another way: the light is on when a and b are both on, or a and c are, or b and c are. Each pair is an &&, and the pairs join with ||:

@left in a: bool
@left in b: bool
@left in c: bool
@right out lit = (a && b) || (a && c) || (b && c)

The parentheses make the grouping easy to read. && binds tighter than || already, so the circuit is the same without them.

Check the code against the table: in the row 1 1 1, every pair is on. Is the light on? In how many of the eight rows is it on?

Run

1. Compile the chip and paste it in-game. Place three Switches and a Point Light.
2. Wire each Switch’s Enabled to a, b and c.
3. Wire lit to the Point Light’s Enabled.
4. Walk through the table: try all eight positions. The light is on in four of them, the four rows with two or three switches on.

Under the Hood

Open the chip. There are five gates: three ANDs, one for each pair, and two ORs that join them. Each && and || in the source is one gate.

Two expressions that give the same truth table are the same circuit, as far as anyone flipping the switches can tell. De Morgan’s laws are the two most useful pairs:

• !(a && b) is the same as !a || !b. “Not both” means “at least one is off”.
• !(a || b) is the same as !a && !b. “Neither” means “both are off”.

This chip computes both sides of the first law. Fill in the truth table for x and y, then flip the switches to check that two lights wired to them always agree:

@left in a: bool
@left in b: bool
@right out x = !(a && b)
@right out y = !a || !b

Open it. x is a single NAND gate (“not and”): the compiler joins a ! written around an && into one gate. y is three gates, two NOTs and an OR. The same happens for !(a || b), which becomes one NOR gate. When you have a choice, write the form with the ! outside.

Modify

1. Count the votes instead. A bool counts as 1 when on and 0 when off wherever a number is expected, so you can add switches:

   @left in a: bool
   @left in b: bool
   @left in c: bool
   @right out lit = a + b + c >= 2
   

   Its truth table is the same as the first chip’s. Open it: two Add gates and a Greater/Equal gate.

2. Change the rule to “every switch is on”, then to “exactly one switch is on”. Write the truth table first, then the expression.

3. Chain XOR: @right out lit = a ^^ b ^^ c. Fill in the eight rows. The light is on when an odd number of switches are on: one or three. This is a parity check, and it gives you a light that any of three switches can change, like the hall light with a third switch.

Make

Make a vote for four switches where the light turns on when at least three are on. Write out the sixteen-row table, then write it two ways: with && and || only, and by counting. Check both against the table in-game.

switch1 Enabled -> chip a
switch2 Enabled -> chip b
switch3 Enabled -> chip c
switch4 Enabled -> chip d
chip logic -> light1 Enabled
chip counted -> light2 Enabled

Good to Know

• a && b always computes both sides, even when a alone already decides: wires do not skip anything. In a handler, an action called on either side still runs, so to do it only when a is on, put an if inside an if.
• An input pin with no wire reads as off. A three-switch chip with only two switches wired treats the third as 0.
• A Switch’s Enabled stays on until it is flipped back, so a truth table is easy to walk through with switches. Button Held is on only while it is held.

Next: Choosing a Value.

Choosing a Value

The logic operators give on or off. Often you want to pick between two other values instead: a red light or a green one, one message or another. The if you met in Reacting to the Game chooses which steps run. This lesson’s if chooses a value.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know
• Other ways to choose

chip2 "Counter"
chip "Color"
button Held -> chip2 pressed
chip2 presses -> chip presses
chip color -> light Color
switch Enabled -> light Enabled

Code

@left in presses: int
let pick = presses % 3
@right out color = if pick == 0 then Color(1.0, 0.0, 0.0)
  else if pick == 1 then Color(0.0, 1.0, 0.0)
  else Color(0.0, 0.0, 1.0)

• @left in presses: int is a number pin. A small counter chip, given in Run, counts a button’s presses and feeds the number in here.
• % is the remainder after dividing. presses % 3 counts 0, 1, 2, then back to 0: 4 presses leave a remainder of 1, and 6 leave 0.
• Color(r, g, b) makes a color from its red, green and blue parts, each from 0.0 to 1.0. Color(1.0, 0.0, 0.0) is red.
• if pick == 0 then A else B is a value: A when the condition is true, B when it is false. The B here is another if, so the choice has three answers. then and else can start new lines, as they do here.

With no presses yet the light is red. What color is it after four presses? After nine?

Run

1. Compile the chip and paste it in-game. Place a Button, a Switch and a Point Light.

2. Paste this counter chip as well. It adds one each time pressed turns on. Remembering Values explains how.

   @left in pressed: exec
   var count: int = 0
   @right out presses = count.Value
   
   on pressed {
     count += 1
   }
   

3. Wire the Button’s Held to the counter’s pressed, the counter’s presses to the first chip’s presses, and color to the Point Light’s Color. Turn off the light’s Use Brick Color setting: while it is on, the light takes the brick’s color and ignores the wire.

4. Wire the Switch’s Enabled straight to the Point Light’s Enabled, and flip it on.

5. Press the button. The light goes red, green, blue, red again. Four presses leave it green, and nine leave it red.

Under the Hood

Open the color chip. There is one Modulo gate for presses % 3. Both comparisons read it, because let pick names one wire. Then there are two Select gates, one for each if.

A Select gate has two value inputs, Input A and Input B, and a bool input, Select B. Its output is Input B while Select B is on, and Input A while it is off. An if puts the condition on Select B, the then value on Input B, and the else value on Input A. The second Select’s output is the first one’s Input A: that is the chain.

A Select gate does not choose which input to compute. Both are computed all the time, and the gate passes one of them along. So an if value always does the work of both arms, and the condition only picks which answer is used:

@left in a: int
@left in b: int
@right out q = if b != 0 then a / b else 0

This chip has a Divide gate wired straight to its pins, and it divides even while b is 0. That is harmless here, because the game’s Divide gives 0 when you divide by zero. But the if did not protect the division: the arm that is not chosen still runs. The “Both arms evaluate” note on the reference’s Expressions page has the details, including the exception for an arm that writes a variable inside a handler.

Modify

1. Add a fourth color. Change % 3 to % 4 and add one more else if pick == 2 then ... before the last else. Try Color(1.0, 1.0, 0.0), which is yellow.

2. Choose text the same way. Add an output for a Text Decal’s Text that names the color:

   @left in presses: int
   let pick = presses % 3
   @right out color = if pick == 0 then Color(1.0, 0.0, 0.0)
     else if pick == 1 then Color(0.0, 1.0, 0.0)
     else Color(0.0, 0.0, 1.0)
   @right out name = if pick == 0 then "red" else if pick == 1 then "green" else "blue"
   

   Open it: the two outputs share the one Modulo and both Equal gates, and each has its own pair of Selects.

3. Add a @left in dim: bool pin from a Switch, and an output for the Point Light’s Brightness that is one number while dim is on and a larger one while it is off. Pick the numbers by trying them in-game.

Make

Make a three-light signal: a red, a yellow and a green Point Light, each with its own @right out pin wired to its Enabled, so that one press of a button moves which one is on. Use presses % 3, and an == for each light in place of an if.

chip2 "Counter"
chip "Signal"
button Held -> chip2 pressed
chip2 presses -> chip presses
chip red -> light1 Enabled
chip yellow -> light2 Enabled
chip green -> light3 Enabled

Good to Know

• An unwired number pin reads as 0. Before the counter is wired, presses is 0 and the light is red.
• Divide and Modulo give 0 when the second input is 0, rather than failing. That is why an untaken arm that divides by zero does no harm, and also why it can hide a mistake: a wrong 0 looks like a real answer.

Other ways to choose

A chain of ifs is not the only way to pick one of several values. The same color picker can be written two more ways.

With match over an enum, each choice gets a name instead of a number. Hue.FromInt(n) turns the number into the enum’s value with that position (0 is Red, 1 Green, 2 Blue), and match gives the value for each one. It compiles to the same Selects as the if chain:

enum Hue { Red, Green, Blue }

@left in presses: int
@right out color = match Hue.FromInt(presses % 3) {
  Red   => Color(1.0, 0.0, 0.0),
  Green => Color(0.0, 1.0, 0.0),
  Blue  => Color(0.0, 0.0, 1.0),
}

With a list, the choices sit in order and the number reads one by its position. A list can only be read inside a handler, so the chip keeps the pick in a var and reads the list each time presses changes (on Change(presses)):

const COLORS = [Color(1.0, 0.0, 0.0), Color(0.0, 1.0, 0.0), Color(0.0, 0.0, 1.0)]

@left in presses: int
var shown: color = Color(1.0, 0.0, 0.0)
@right out color = shown.Value

on Change(presses) {
  shown = COLORS[presses % 3]
}

The list costs the same few gates however many choices it holds, while an if chain or a match grows by a gate or two per choice, so a list wins once there are many. Enums and Lists cover both in full.

Next: Toggles and Latches.

Toggles and Latches

The circuits in Truth Tables forget: their output depends only on what the switches say right now. A button is different. Its Held is on only for a moment, so a light that should stay on after the press needs a circuit that remembers. This lesson builds two: a toggle, which flips on each press, and a latch, which one button turns on and another turns off.

Contents

• Code
• Run
• Under the Hood
• Use it: a set/reset latch
• Modify
• Make
• Good to Know

button Held -> chip pressed
chip light -> light Enabled

Code

@left in pressed: exec
var lit: bool = false
@right out light = lit.Value

on pressed {
  lit = Toggle()
}

Toggle() is a gate with a memory of its own: one on/off value. Each time a handler’s chain runs through it, it flips that value and gives the new one. lit = Toggle() stores the answer in the variable, and light follows the variable.

pressed is an exec pin. Wired from a Button’s Held, on pressed runs its chain when Held turns on: the moment it goes from off to on, called the rising edge. on !pressed runs when it turns off, the falling edge, but it needs a bool pin, as the next example shows.

The first press turns the light on. What does the second press do? What happens while you hold the button down?

Run

1. Compile the chip and paste it in-game. Place a Button and a Point Light.
2. Wire the Button’s Held to pressed, and light to the Point Light’s Enabled.
3. Press the button: the light turns on. Press it again: off. Holding the button does nothing more, because the chain runs once, on the rising edge.

Under the Hood

Open the chip. The Toggle gate has an Exec input, and two outputs: Exec Out, which carries the pulse on to the next step, and Output, its on/off value. The next step is a Set Variable that stores Output in lit.

pressed is wired straight into the Toggle’s Exec input. That is what on pressed compiles to: the Button’s Held reaches an exec input, which runs the chain when Held turns on. on !pressed puts a NOT gate in between, so the chain runs when pressed turns off. The NOT reads the pin’s value, so a pin used with on ! stays a bool.

This chip counts both edges. Wire text to a Text Decal’s Text, then press, hold, and let go:

@left in pressed: bool
var downs: int = 0
var ups: int = 0
@right out text = "down ${downs.Value}, up ${ups.Value}"

on pressed {
  downs += 1
}

on !pressed {
  ups += 1
}

A long hold still counts one down, and the up comes only when you let go.

Use it: a set/reset latch

A latch has two inputs. set turns it on and reset turns it off, and between presses it stays as it was. An alarm is one: one button arms it, another disarms it, and a light shows which happened last.

The latch’s value depends on three things: set, reset, and its own value a moment ago.

@left in set: bool
@left in reset: bool
let state: bool = set || (held && !reset)
buffer held: bool = state
@right out q = state

Read state as: on while set is held, or if it was on and reset is not held. That “was on” is held: what the latch holds, not a Button’s Held.

buffer held: bool = state makes held a copy of state delayed by one tick, the game’s next update. The latch reads its own past value, so its wires form a loop: state feeds held, and held feeds state. Every wire loop must pass through a buffer. Without one, the compiler stops with WS005.

held is used on the line above the one that declares it. That is allowed for a buffer, but the buffer then needs its type, : bool. Leave the type out and the compiler cannot tell what held is when it reaches the &&:

@left in set: bool
@left in reset: bool
let state: bool = set || (held && !reset)
buffer held = state
@right out q = state

Error: [WS004] no overload for '&&' on any, bool

The message talks about &&, but the fix is the missing : bool on the buffer.

To run the latch, wire two Buttons’ Held to set and reset, and q to a Point Light’s Enabled. Press set: the light comes on and stays on after you let go. Press reset: it goes off and stays off. Open the chip: an OR, an AND, a NOT, and a Buffer (Ticks) gate whose output wires back into the AND.

The toggle runs on exec pulses and stores into a variable. The latch is pure: nothing in it runs in steps, and it remembers only through its buffer.

Modify

1. Make the toggle flip when the button is let go instead: change on pressed to on !pressed, and the pin to @left in pressed: bool so !pressed can read it. Press and hold: nothing happens until you release.

2. The toggle does not need the variable. A handler can declare an output pin of its own, wired straight from the Toggle gate’s Output:

   @left in pressed: exec
   
   on pressed {
     @right out light: bool = Toggle()
   }
   

   Open it: there is no Variable gate, just the Toggle.

3. In the latch, holding both buttons at once turns the light on: set wins. Change it so that reset wins: !reset && (set || held). Write the truth table for set, reset and held both ways and find the row where they differ.

Make

Make a “which was pressed last” sign: two buttons and two lights. Pressing the first lights the first light and turns off the second. Pressing the second does the opposite. One latch is enough: the second light is !q.

button1 Held -> chip set
button2 Held -> chip reset
chip q -> light1 Enabled
chip notQ -> light2 Enabled

Good to Know

• on fires once when the wired value turns on, never again while it stays on. A button held down for a minute is one press.
• A Button’s Held is on only while someone holds it, which is why the toggle and the latch need memory to keep the light on.

Next: Bits.

Bits

An int is a whole number. Inside the computer, it is stored as 64 on/off values called bits. Think of it as a row of 64 switches. The bitwise operators work on all of those switches at once, so one wire can carry the state of many switches, and one gate can test them all.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

switch1 Enabled -> chip s0
switch2 Enabled -> chip s1
switch3 Enabled -> chip s2
switch4 Enabled -> chip s3
chip text -> decal Text

Code

A number written in binary shows its bits. 0b starts a binary number, and each digit is one bit, with the lowest on the right. Each bit is worth twice the one to its right: 1, 2, 4, 8, and so on.

This chip packs four switch pins into one number, one bit per switch:

@left in s0: bool
@left in s1: bool
@left in s2: bool
@left in s3: bool
let code = s0 | (s1 << 1) | (s2 << 2) | (s3 << 3)
@right out text = "code ${code}, ${BitCount(code)} on"

• A bool counts as 1 or 0 where a number is expected, so s1 is the number 1 while its switch is on.
• << shifts left: x << 2 moves every bit of x two places up. 1 << 2 is 0b0100, which is 4. So s2 << 2 is 4 while s2 is on, and 0 while it is off.
• | is bitwise OR: each bit of the result is on if that bit is on in either side. Here each switch has its own bit, so OR puts them together.
• BitCount(x) counts how many bits of x are on.

Switches s0 and s3 are on, and the others off. What does the sign say?

Run

1. Compile the chip and paste it in-game. Place four Switches in a row and a brick with a Text Decal.
2. Wire each Switch’s Enabled to s0, s1, s2 and s3, and text to the Text Decal’s Text.
3. Flip the switches. With s0 and s3 on, the sign reads code 9, 2 on: 1 + 8 is 9. All four on is 15, the largest a four-bit number can be.

Under the Hood

Open the chip. There are three Shift Left (Bitwise) gates, one for each of s1, s2 and s3 (s0 is already in place), three OR (Bitwise) gates joining them, and one Bit Count. The switch pins wire straight into the shift gates: the game reads an on bool as 1.

Here are all the bitwise operators, on four-bit examples. Each works bit by bit:

These are different from the logic operators &&, || and !, which treat the whole value as a single on or off. One & does 64 ANDs, one per bit.

A mask is a number that picks out bits. code & 0b0100 keeps the bit worth 4 and clears every other, so it is 4 when s2 is on and 0 when it is off. Some common uses:

@left in code: int
@right out s2On = (code & 0b0100) != 0
@right out third = (code >> 2) & 1
@right out withS0 = code | 0b0001
@right out withoutS0 = code & ~0b0001
@right out flipped = code ^ 0b1111

• s2On tests one bit: is it on?
• third reads the same bit as a number, 0 or 1: shift it down to the bottom, then mask it.
• withS0 turns the bit worth 1 on, and withoutS0 turns it off. ~0b0001 is every bit except the lowest.
• flipped flips the low four bits. ~code would flip all 64, so to flip only some of them, XOR with a mask, or write ~code & 0b1111.

Mind the parentheses in s2On. & binds more loosely than == and !=, so without them code & 0b0100 == 4 would mean code & (0b0100 == 4): the comparison first, then & with its true or false, which tests the wrong switch. That is almost never what you want, so the compiler warns about it (WS117) and asks for parentheses:

@left in code: int
@right out bad = code & 0b0100 == 4

(code & 0b0100) == 4 tests the bit, and code & (0b0100 == 4) says you really meant the comparison’s result.

The compiler also joins a ~ around & or | into one gate: ~(a & b) becomes a single NAND (Bitwise) gate, and ~(a | b) a single NOR (Bitwise), as ! does for the logic operators.

Modify

1. Add a light for each switch that reads its bit back out of code: @right out lamp3 = (code & 0b1000) != 0. Wire it to a Point Light’s Enabled and check it follows s3.

2. Show the bits in a row. Add an output for a second Text Decal that writes each bit as 1 or 0, highest first:

   @left in s0: bool
   @left in s1: bool
   @left in s2: bool
   @left in s3: bool
   let code = s0 | (s1 << 1) | (s2 << 2) | (s3 << 3)
   @right out row = "${(code >> 3) & 1}${(code >> 2) & 1}${(code >> 1) & 1}${code & 1}"
   

3. Count in binary. Replace the four switches with one Button, the counter chip from Choosing a Value (Button Held to its pressed), and an @left in presses: int pin wired from the counter’s presses. Give four Point Lights one bit each, from (presses & 1) != 0 up to (presses & 0b1000) != 0. Press the button and watch the lights count to 15 and start over.

Make

Make a chip that takes two sets of four switches, packs each into a number, and shows on a sign how many switches are set the same in both sets. XOR is on wherever two bits differ, so BitCount(a ^ b) counts the differences.

switch1 Enabled -> chip a0
switch2 Enabled -> chip a1
switch3 Enabled -> chip a2
switch4 Enabled -> chip a3
switch5 Enabled -> chip b0
switch6 Enabled -> chip b1
switch7 Enabled -> chip b2
switch8 Enabled -> chip b3
chip text -> decal Text

Good to Know

• An int is 64 bits, and comparing two ints compares all 64 of them.
• A bool wired into a number input reads as exactly 1 or 0.
• >> compiles to the game’s Shift Right (Arithmetic) gate. On the positive numbers in this lesson it moves bits down.

Next: Code Door.

Code Door

This project uses Bits for a door with four switches beside it. Set the switches to the secret code and the door opens. A light beside the switches glows brighter for each switch that is set right.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

switch1 Enabled -> chip s0
switch2 Enabled -> chip s1
switch3 Enabled -> chip s2
switch4 Enabled -> chip s3
chip solid -> changer "Collision Enabled"
chip solid -> changer Visibility
chip glow -> light Brightness
switch5 Enabled -> light Enabled

Code

const CODE = 0b1011

@left in s0: bool
@left in s1: bool
@left in s2: bool
@left in s3: bool
let code = s0 | (s1 << 1) | (s2 << 2) | (s3 << 3)
let right = 4 - BitCount(code ^ CODE)
@right out solid = code != CODE
@right out glow: float = right

• const CODE = 0b1011 is the secret code, written in binary so each digit is one switch: s3 on, s2 off, s1 on, s0 on, reading left to right.
• code packs the four switches into one number, as in Bits.
• solid is on while the code is wrong. Wired to the door, it keeps the door there until the code matches.
• code ^ CODE is XOR: a bit of it is on wherever a switch differs from the code. BitCount counts those wrong switches, so 4 - BitCount(...) is the number of right ones.
• glow: float makes the output a decimal number, the kind a light’s Brightness takes. right is a whole number, and the light reads it as a decimal.

All switches start off. How many are right before you touch anything? Which switches do you flip to open the door?

Run

1. Compile the chip and paste it in-game. Build a door from a few bricks and give one of them a Brick Property Changer. Place four Switches in a row beside it, and a Point Light.
2. Wire each Switch’s Enabled to s0, s1, s2 and s3. Put s3 on the left, so the row of switches reads like the binary number.
3. Wire solid to the Brick Property Changer’s Collision Enabled and Visibility inputs.
4. Wire glow to the Point Light’s Brightness, and give the light’s Enabled a Switch of its own, flipped on.
5. With every switch off, one switch is right: s2, which the code wants off. Flip s0, s1 and s3 on. The light grows brighter at each one, and on the last the door vanishes.

Under the Hood

Open the chip. The packing is the same three Shift Left and three OR (Bitwise) gates as before. After it come an XOR (Bitwise), a Bit Count, a Subtract for 4 - ..., and a Not Equal for solid.

There is no gate for CODE. A const is written into the gates that use it: the number 11 is typed straight into an input of the XOR and of the Not Equal. Anyone who opens the chip can read the code there.

The light gives the code away too. Flip any switch. If the light gets brighter, leave it, and if it gets dimmer, flip it back. Four tries find the code.

Modify

1. Choose your own code: change CODE to another four-bit number, from 0b0000 to 0b1111. Add a sign that shows the hint as text, @right out hint = "${right} of 4 right", wired to a Text Decal’s Text.

2. Make the hint something you ask for. Add @left in peek: bool from a Button’s Held, and make the light dark unless it is held: @right out glow: float = if peek then right else 0.

3. Make the door wait for a button. Here it opens only when someone presses Try, and it stays as it is until the next press, whatever the switches do in between:

   const CODE = 0b1011
   
   @left in s0: bool
   @left in s1: bool
   @left in s2: bool
   @left in s3: bool
   @left in attempt: exec
   let code = s0 | (s1 << 1) | (s2 << 2) | (s3 << 3)
   var shut: bool = true
   @right out solid = shut.Value
   
   on attempt {
     shut = code != CODE
   }
   

   Wire a Button’s Held to attempt. Now no light tells you which switches are right, and flipping a switch after the door opens does not close it.

Make

Make a door with eight switches and two codes: a guest code and an owner code, where either one opens it. Then add a light that shows which of the two was used.

switch1 Enabled -> chip s0
switch2 Enabled -> chip s1
switch3 Enabled -> chip s2
switch4 Enabled -> chip s3
switch5 Enabled -> chip s4
switch6 Enabled -> chip s5
switch7 Enabled -> chip s6
switch8 Enabled -> chip s7
chip solid -> changer "Collision Enabled"
chip solid -> changer Visibility
chip owner -> light Enabled

Good to Know

• A door needs both Collision Enabled (players cannot walk through) and Visibility (players can see it). Wire solid to both.
• A Switch’s Enabled stays on until it is flipped back, so in the first version the door closes again as soon as any switch moves.
• An unwired switch pin reads as off. With s3 unwired, the code 0b1011 can never match.

Next: pick a lesson from the tree on the Learn page.

Text Values

Signs, chat lines and labels all carry text. In Wirescript a piece of text is a string, and it moves along wires like any other value. This lesson builds a shop sign that two buttons change, and a light that shows whether the sign has anything on it.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

button1 Held -> chip away
button2 Held -> chip back
chip text -> decal1 Text
chip count -> decal2 Text
chip lit -> light Enabled

Code

const AWAY = "Back in 5 minutes"

@left in away: exec
@left in back: exec
var note: string = ""
@right out text = "Shop: " .. note.Value
@right out lit: bool = note.Value
@right out count = "${note.Value.Length()} characters"

on away {
  note = AWAY
}

on back {
  note = ""
}

Text goes between quotes. "" is the empty string: text with nothing in it. var note: string = "" is a variable that holds text and starts empty.

.. joins two pieces of text into one, so "Shop: " .. note.Value is the words Shop: followed by whatever the note says.

note.Value.Length() counts the characters in the note.

lit is declared bool, but it is given a string. Where a bool is wanted, a string reads as false when it is empty and true when it holds anything at all.

What does each output show before any press, after pressing away, and after pressing back?

Run

1. Compile the chip and paste it in-game. Place two Buttons, two bricks with a Text Decal each, and a Point Light.
2. Wire one Button’s Held to away and the other’s to back.
3. Wire text to one Text Decal’s Text and count to the other’s Text. Wire lit to the Point Light’s Enabled.
4. At first the sign reads Shop: , the count reads 0 characters, and the light is off.
5. Press away. The sign reads Shop: Back in 5 minutes, the count reads 17 characters, and the light comes on. Press back and all three return to how they started.

Under the Hood

Open the chip. note is a Variable gate, and each handler is one Set Variable that writes a fixed text into it.

• text comes from an Append String gate, the game’s join gate. Its inputs are Shop: and the variable’s value.
• count comes from a Get String Length gate feeding a Format String gate. That is the ${...} from Remembering Values: one gate that fills values into a template.
• lit comes from a Not Equal gate that compares the note with "". You did not write it: the compiler adds it wherever a string is used as a bool.

When every piece of a join is fixed text, the compiler joins it for you and no Append String is placed for it. Only a join with a value that can change needs a gate.

Quotes and escapes

A string can use double quotes or single quotes. They mean the same thing, so pick the one that saves you work. Single quotes let the text hold double quotes as they are:

'Ring the "bell"'
"Ring the \"bell\""

Both lines are the same text. A backslash in front of a character is an escape: \" is a double quote inside double quotes, \' a single quote inside single quotes, \\ a backslash, and \$ a dollar sign that does not start a ${...}. Escape Sequences lists them all. For a new line on a sign, use the <br> tag from the Rich Text lesson.

Modify

1. Change AWAY to 'Ring the "bell"'. Compile and press away: the sign shows the quotes. How many characters does the count show now?

2. == compares two strings and gives a bool. Add a pin that is on only while the note says exactly AWAY, and wire it to a second light:

   const AWAY = "Back in 5 minutes"
   
   @left in away: exec
   @left in back: exec
   var note: string = ""
   @right out text = "Shop: " .. note.Value
   @right out isAway = note.Value == AWAY
   
   on away {
     note = AWAY
   }
   
   on back {
     note = ""
   }
   

   != is the opposite: true while the two texts differ.

3. Use one button for both jobs. Inside a handler, if note is the same test as lit: true while the note is not empty.

   const AWAY = "Back in 5 minutes"
   
   @left in pressed: exec
   var note: string = ""
   @right out text = "Shop: " .. note.Value
   
   on pressed {
     if note {
       note = ""
     } else {
       note = AWAY
     }
   }
   

   Open the chip: the if is a Branch gate, and its condition is the same Not Equal against "" that the compiler added for lit.

Make

Make a doorbell sign: pressing a Button shows Ding! on a Text Decal for three seconds, then clears it, and a light stays on while the sign has text. await Sleep(_, delay = 3.0) from Pure and Exec does the waiting.

button Held -> chip ring
chip text -> decal Text
chip lit -> light Enabled

Good to Know

• Length() counts characters as the game sees them (code points), so ★ is 1. Some emoji are several code points joined together: a figure with a skin tone and a gender sign counts 5, though it draws as one picture.
• Only the empty string is false. " ", "0" and "false" all hold something, so they read as true.
• An input pin that nothing is wired to reads as empty text.

Next: Taking Text Apart.

Taking Text Apart

Text often holds more than you need: a player’s full display name when you want only the first word, or a number written as digits. This lesson cuts text into pieces, changes its case, and reads numbers out of it. The text comes from players walking into a zone, so no admin rights are needed.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

zone "Zone Ref" -> chip room
chip text -> decal Text

Code

import { escape } from "sanitize"

@left in room: zone
var visitor: string = "Nobody yet"
@right out text = "Last visitor: ${visitor.Value}"

on ZoneEntered(zone = room) -> (character) {
  let name = character.GetDisplayName().Trim()
  let parts = name.Split(" ")
  let first = if parts.Found then parts.Left else name
  character.ShowChatMessage("Hi ${escape(first)}!")
  let initial = name.Substring(0, 1).ToUpper()
  visitor = "${escape(initial)} (${name.Length()} characters)"
}

The zone handler is the one from Reacting to the Game. Each new piece is a method called on a string with a dot:

• GetDisplayName() gives the name the player chose to show.
• Trim() removes spaces from both ends.
• Split(" ") cuts the text at the first space. It gives three values: Left is the text before the space, Right is the text after it, and Found says whether there was a space at all.
• Substring(0, 1) takes 1 character, starting at position 0. Positions count from 0, so position 0 is the first character.
• ToUpper() turns letters into capitals. ToLower() does the opposite.

if parts.Found then parts.Left else name picks the first word when there is a space, and the whole name when there is not. escape(...) is the helper from Reacting to the Game that makes player text safe to show. Safe Text explains why it is needed.

A player named sam the builder walks in. What does the chat say to them, and what does the sign say? What changes for a player named Sam?

Run

1. Compile the chip and paste it in-game. Give a brick an Attached Zone and wire its Zone Ref to room.
2. Wire text to a Text Decal’s Text.
3. Walk into the zone. Chat greets you by the first word of your name, and the sign shows your initial in capitals and how long your name is.
4. Ask a friend with a different name to walk in, or change your display name and walk in again. The sign shows whoever came last.

Under the Hood

Open the chip. The handler’s chain starts at the zone event, then passes through a Get User Display Name gate. Reading a name is a step in the chain, so GetDisplayName() only works inside a handler.

After it come gates that need no exec: Trim String, Split String (with outputs named Left, Right and Found), a Select that picks the first word or the whole name, Get Substring, String to Upper and Get String Length. Two Replace in String gates are the two escape calls. The chain ends with Show Chat Message and the Set Variable that updates the sign.

Modify

1. Greet the rest of the name too. parts.Right is everything after the first space, so use it only when parts.Found says there was one:

   import { escape } from "sanitize"
   
   @left in room: zone
   
   on ZoneEntered(zone = room) -> (character) {
     let name = character.GetDisplayName().Trim()
     let parts = name.Split(" ")
     if parts.Found {
       character.ShowChatMessage("Hi ${escape(parts.Left)}, also known as ${escape(parts.Right)}!")
     } else {
       character.ShowChatMessage("Hi ${escape(name)}!")
     }
   }
   

2. Find gives the position where some text first appears, or -1 when it does not appear. Because positions count from 0, the position of the first space is also the length of the first word:

   @left in room: zone
   
   on ZoneEntered(zone = room) -> (character) {
     let name = character.GetDisplayName().Trim()
     let space = name.Find(" ")
     if space < 0 {
       character.ShowChatMessage("One word, ${name.Length()} characters")
     } else {
       character.ShowChatMessage("Your first word has ${space} characters")
     }
   }
   

3. Text can hold a number. ParseNumber() reads it, and gives two values: Value, the number, and Success, which is false when the text is not a number. This keypad builds text from button presses, then sets a light’s brightness from it:

   @left in one: exec
   @left in two: exec
   @left in enter: exec
   var typed: string = ""
   var level: float = 5.0
   @right out shown = typed.Value
   @right out brightness = level.Value
   
   on one {
     typed = typed .. "1"
   }
   
   on two {
     typed = typed .. "2"
   }
   
   on enter {
     let n = typed.ParseNumber()
     if n.Success {
       level = n.Value
     }
     typed = ""
   }
   

   Wire three Buttons’ Held to one, two and enter, shown to a Text Decal’s Text, and brightness to a Point Light’s Brightness. Type 12 and press enter. ParseInt() works the same way for whole numbers, with an int for its Value.

Make

Make a keypad lock: three digit buttons, an enter button and a door. Pressing enter reads the typed digits with ParseInt(), opens the door for three seconds when the number equals a const CODE = 213, and clears the typed text either way. Show the typed digits on a sign while the player types.

button1 Held -> chip one
button2 Held -> chip two
button3 Held -> chip three
button4 Held -> chip enter
chip text -> decal Text
chip solid -> changer "Collision Enabled"
chip solid -> changer Visibility

Good to Know

• Length() and Substring count code points, so a character such as ★ is one character, not two.
• A display name is chosen by its player. It can be one word or many, and it can contain <. Trim it before you split it, and escape any part of it you show.

Next: Rich Text.

Rich Text

Text the game shows can carry formatting: bold, color, size, line breaks and small icons. The formatting is written as tags inside the string itself, so a circuit can change how a sign looks the same way it changes what it says. This lesson builds a shop sign driven by two switches.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

switch1 Enabled -> chip shopOpen
switch2 Enabled -> chip busy
chip text -> decal Text

Code

@left in shopOpen: bool
@left in busy: bool
let word = if shopOpen then "OPEN" else "CLOSED"
let hex = if shopOpen then "44dd44" else "dd4444"
let note = if busy then "<i>Busy, please wait</>" else "Come on in"
@right out text = '<size="48"><b><color="${hex}">${word}</></></><br>${note}'

A tag is a word between < and >. The game reads it as an instruction and does not show it:

• <size="48"> makes the text after it 48 points tall.
• <b> makes it bold, and <i> makes it italic.
• <color="44dd44"> colors it. The color is six hex digits: two each for red, green and blue, so 44dd44 is green and dd4444 is red.
• <br> starts a new line.
• </> closes the most recently opened tag. The three </> after ${word} close the color, then the bold, then the size, so the second line is ordinary text.

The template uses single quotes, so the double quotes inside each tag need no escaping.

What does the sign show with shopOpen on and busy on? With both off?

Run

1. Compile the chip and paste it in-game. Place two Switches and a brick with a Text Decal.
2. Wire one Switch’s Enabled to shopOpen and the other’s to busy.
3. Wire text to the Text Decal’s Text.
4. With both switches off, the sign shows a large red bold CLOSED over a smaller Come on in. Flip shopOpen: the word turns green and reads OPEN. Flip busy: the second line changes to Busy, please wait in italics.

Under the Hood

Open the chip. There are three Select gates, one for each if, and one Format String gate. The Format String’s template holds every tag, and the Selects fill in the color, the word and the note. To the circuit, a tag is only text. The sign is what reads it.

The if choices are bound to names with let before they go into the template. That keeps the template short, and it is also the safe way to write it: put a choice in a let, then put the name inside ${...}.

Modify

1. A color tag does not need a closing </>. It lasts until another color tag replaces it, even across a <br>. Color both lines, with no </> at all:

   @left in shopOpen: bool
   let status = if shopOpen then '<color="44dd44">OPEN' else '<color="dd4444">CLOSED'
   @right out text = '${status}<br>Snacks and drinks<br><color="ffffff">Ask inside'
   

   The second line takes the status color, and the third line is white because a new color tag replaced it.

2. Use a character that is not on your keyboard. There is no escape code for it: copy the character and paste it into the string, for example '<size="40">★ Open ★'. It counts as one character in Length().

Make

Make a sign for a door with two switches, locked and alarm. It shows a green Unlocked or a red Locked on the first line, and while alarm is on, a second line in bold yellow that reads ALARM.

switch1 Enabled -> chip locked
switch2 Enabled -> chip alarm
chip text -> decal Text

Good to Know

• Tags work anywhere the game shows text: Text Decals, chat, status messages. Rich Text Markup lists them all, including fonts.
• <icon>Name</> draws one of the game’s own icons inline, at the size of the text around it. These docs do not list the icon names yet.
• A wire carries at most 10,000 characters of text, and the rest is cut off. Every tag counts toward that, so a sign that colors every character can hit the limit long before it looks full.
• A player’s own name can contain tags too. Showing it unchanged lets it restyle your sign. Safe Text fixes that.

Next: Safe Text.

Safe Text

A player picks their own display name, and a name can contain anything, including tags. When a circuit shows that name, the game reads those tags as formatting. This lesson shows the problem, then fixes it with the two helpers in the lessons’ starter library.

Contents

• Code
• Run
• Under the Hood
• Use it: a guest sign
• Modify
• Make
• Good to Know

switch Enabled -> chip safe
chip text -> decal Text

Code

import { escape } from "sanitize"

const TRICKY = '<size="96"><color="ff0000">Sam'

@left in safe: bool
let shown = if safe then escape(TRICKY) else TRICKY
@right out text = "Guest: ${shown}<br>Welcome!"

TRICKY stands in for a player whose display name is <size="96"><color="ff0000">Sam. The switch picks whether the sign shows it as it is, or after escape.

escape replaces every < with <. That is the standard way to write a < that is not the start of a tag: the game shows it as a plain <, so the tag appears as text instead of being obeyed.

With the switch off, what does the word Welcome! look like? With it on?

Run

1. Compile the chip and paste it in-game. Place a Switch and a brick with a Text Decal.
2. Wire the Switch’s Enabled to safe, and text to the Text Decal’s Text.
3. With the switch off, the name’s tags take over: Sam and everything after it, Welcome! included, is huge and red.
4. Flip the switch on. The sign shows the name exactly as it was typed, tags and all, and Welcome! looks normal.

Under the Hood

Open the chip. escape added one Replace in String gate, which searches for < and puts < in its place. A Select chooses between the escaped and the raw text, and a Format String builds the sign.

The library is a file named sanitize.ws, and import { escape } from "sanitize" brings in one helper from it. This is the whole file:

// Escape markup in a display name before showing it. A `mod`, so each use is a single gate.
mod escape(text: string) -> string {
  return text.Replace("<", "&lt;")
}

// Clean free-form player input: trim, cap the length, then escape.
// Capping first keeps the cut from landing inside an `&lt;`.
fn sanitize(raw: string, maxLen: int = 24) -> string {
  return raw.Trim().Substring(0, maxLen).Replace("<", "&lt;")
}

• escape is a mod. A mod is copied into every place that uses it, so each escape(...) becomes one Replace in String gate right there.
• sanitize is a fn. A function is built once, on its own small board, and each place that uses it gets a Function Call gate that runs it. maxLen: int = 24 gives the second input a default, so sanitize(name) means sanitize(name, 24).

Use it: a guest sign

sanitize is for text that must also fit a space. It trims spaces from the ends, keeps at most maxLen characters, then escapes what is left. This sign keeps the last guest’s name short enough for a narrow sign, and greets the guest by their full name in chat:

import { escape, sanitize } from "sanitize"

const SIGN_WIDTH = 12

@left in room: zone
var guest: string = "Nobody yet"
@right out text = '<size="32">Last guest:<br><b>${guest.Value}</>'

on ZoneEntered(zone = room) -> (character) {
  let name = character.GetDisplayName()
  guest = sanitize(name, SIGN_WIDTH)
  character.ShowChatMessage("Welcome, ${escape(name)}!")
}

Wire an Attached Zone’s Zone Ref to room and text to a Text Decal’s Text, then walk into the zone.

The cap comes before the escape because escaping turns one < into four characters. If the cut came after, it could land in the middle of an < and leave a broken piece such as &l at the end of the sign. Cutting first means every < that survives the cut is escaped whole. The cost is that the result can be longer than maxLen when the name contains <.

Which one to use:

• escape(text) when the whole text should be shown, such as a name in a chat line.
• sanitize(text, maxLen) when the text must fit, such as a sign, a label or one row of a list.

Modify

1. Change SIGN_WIDTH to 4 and walk in again. Only the start of your name fits.
2. Run your sign through the switch test: replace name with TRICKY from the first example in the sanitize call, and check that the sign shows the tags as text.
3. Greet the guest in chat by the first word of their name only, with Split(" ") from Taking Text Apart. Split the raw name first, then escape the word you show: escaping is always the last step before text is displayed.

Make

Make a sign that lists the last three guests, one per line, newest first. Keep three vars, move each one down a line when someone new walks in, and sanitize every name before it is stored.

zone "Zone Ref" -> chip room
chip text -> decal Text

Good to Know

• Every place that shows text reads tags, chat included, so a name in a chat line can restyle that line too. Escape any text a player chose before you show it, wherever it goes.
• escape only changes <. Text without a < comes out unchanged.

Next: Matching Text.

Matching Text

A chain of if text == "..." ... else if text == "..." gets long fast, and cutting the useful part out of text takes a Find and a Substring every time. match does both in one place: it lists what the text might look like, runs the first arm that fits, and hands you the pieces. This lesson greets players by the shape of their name, so no admin rights are needed.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

zone "Zone Ref" -> chip room
chip text -> decal Text

Code

import { escape } from "sanitize"

@left in room: zone
var said: string = "Nobody yet"
@right out text = said.Value

on ZoneEntered(zone = room) -> (character) {
  let name = character.GetDisplayName().Trim()
  let greeting = match name {
    "" => "Hello, stranger!",
    "Builder" | "Brickadian" => "Hello, fellow builder!",
    "${first} ${_}" => "Hi ${escape(first)}! Love the long name.",
    _ => "Hi ${escape(name)}!",
  }
  character.ShowChatMessage(greeting)
  said = greeting
}

match name { ... } checks name against each arm in order, top to bottom, and gives the value after the => of the first one that fits:

• "" fits only the empty text. A plain string in an arm means “exactly this”.
• "Builder" | "Brickadian" fits either one. | reads as “or”.
• "${first} ${_}" looks like text with ${...} in it, but in an arm it works the other way round. Instead of putting a value into the text, it takes one out: it fits any text with a space in it, and first becomes everything before the first space. ${_} matches the rest without naming it.
• _ fits anything. A match on text must end with it (or a name), since no list of exact strings covers every possible name.

The arms are tried in order, so put specific ones above general ones. If the _ arm came first, nothing below it would ever run, and the compiler would warn you.

A player named Builder walks in. What does the chat say? What about sam the builder, and Sam?

Run

1. Compile the chip and paste it in-game. Give a brick an Attached Zone and wire its Zone Ref to room.
2. Wire text to a Text Decal’s Text.
3. Walk into the zone. Chat greets you, and the sign shows the last greeting. A one-word name gets the last arm; a name with a space gets the third.

Under the Hood

Open the chip. A match that gives a value is a stack of Select gates, one for each arm except the last, just like the if ... then ... else from Choosing a Value:

• "" is one Compare Equal.
• "Builder" | "Brickadian" is two Compare Equal gates joined by a Logical OR.
• "${first} ${_}" is a Find in String looking for " ", a Compare Greater or Equal checking that it found one, and a Get Substring that cuts out first. ${_} needs no gate, since nothing reads it.

These are the same gates you would build by hand with ==, Find and Substring. match just writes them for you.

Modify

1. An arm can have a condition after if, called a guard. The arm only runs when the pattern fits and the guard is true; when the guard is false, match moves on to the next arm. The guard can read the names the pattern took out:

   import { escape } from "sanitize"
   
   @left in room: zone
   
   on ZoneEntered(zone = room) -> (character) {
     let name = character.GetDisplayName().Trim()
     character.ShowChatMessage(match name {
       "${first} ${_}" if first.Length() > 8 => "Hi ${escape(first)}, what a first name!",
       "${first} ${_}" => "Hi ${escape(first)}!",
       _ => "Hi ${escape(name)}!",
     })
   }
   

2. The text around the holes decides where they go. A hole at the end takes everything after the text before it, and a hole at the start takes everything before the text after it:

   import { escape } from "sanitize"
   
   @left in room: zone
   
   on ZoneEntered(zone = room) -> (character) {
     let name = character.GetDisplayName().Trim()
     character.ShowChatMessage(match name {
       "Sir ${rest}" => "Welcome, Sir ${escape(rest)}.",
       "${who}Bot" => "Beep boop, ${escape(who)}.",
       "[${tag}] ${who}" => "${escape(who)} from team ${escape(tag)}",
       _ => "Hi!",
     })
   }
   

   "Sir ${rest}" can also be written "Sir " .. rest, joining the parts with .. the way you join text. Both build the same gates.

3. match works on numbers too. An arm can be an exact number, or a range low..high, which fits numbers from low up to, but not including, high:

   @left in room: zone
   var visits: int = 0
   
   on ZoneEntered(zone = room) -> (character) {
     visits += 1
     character.ShowChatMessage(match visits {
       1 => "You are the first visitor!",
       2..10 => "Visitor number ${visits}.",
       n if n % 100 == 0 => "Visitor ${n}, a round number!",
       _ => "Welcome back.",
     })
   }
   

Make

Make a keypad lock: three digit buttons, an enter button and a door. The digit buttons add 1, 2 or 3 to a typed text, and a sign shows it. On enter, match the typed text with arms that run steps instead of giving a value (each arm is a { ... } block):

• the code "213" opens the door for three seconds;
• a code starting with 3 says “Codes never start with 3” in chat;
• a code longer than three digits says “Too long” (a guard on typed.Length());
• anything else says “Wrong code”.

Clear the typed text after every try.

button1 Held -> chip one
button2 Held -> chip two
button3 Held -> chip three
button4 Held -> chip enter
chip text -> decal Text
chip solid -> changer "Collision Enabled"
chip solid -> changer Visibility

Good to Know

• In a pattern, ${name} makes a new name for the text it matched. It never reads a name that already exists, and the compiler warns when the two share a name. To compare against a value you already have, use a guard: "hi ${n}" if n == friend => ....
• Matching is case-sensitive: "builder" does not fit "Builder". Match on name.ToLower() and write the arms in lower case to ignore case.
• A literal between two holes is found at its first appearance: "${a}-${b}" splits x-y-z into x and y-z.
• match also works on enums, where each arm names a variant.

Next: pick a lesson from the tree on the Learn page.

Interpolation

Most text a circuit shows mixes fixed words with live values: a score, a count, a name. ${} puts a value into a piece of text. This lesson shows what it compiles to, and why it is cheaper than joining the pieces yourself.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

chip2 "Counter"
chip "Sign"
button1 Held -> chip2 addRed
button2 Held -> chip2 addBlue
chip2 red -> chip red
chip2 blue -> chip blue
chip joined -> decal1 Text
chip templated -> decal2 Text

Code

@left in red: int
@left in blue: int
@right out joined = "Red " .. red .. ", Blue " .. blue .. ", Total " .. (red + blue)
@right out templated = "Red ${red}, Blue ${blue}, Total ${red + blue}"

Text in quotes is a string. .. joins two strings into one, and turns a number into text on the way. ${...} inside a string puts the value of what is between the braces at that spot. The text around it stays as written. A string with ${} in it is called a template.

Both outputs build the same words. Which one takes fewer gates? Guess a number for each before you open the chip.

Run

1. Compile the chip and paste it in-game. Place two Buttons and two bricks with a Text Decal.

2. Paste this counter chip as well. It counts each button’s presses, the way Remembering Values does, and puts the two counts on pins. The next lessons in this branch use it too.

   @left in addRed: exec
   @left in addBlue: exec
   var redCount: int = 0
   var blueCount: int = 0
   @right out red = redCount.Value
   @right out blue = blueCount.Value
   
   on addRed { redCount += 1 }
   on addBlue { blueCount += 1 }
   

3. Wire the first Button’s Held to the counter’s addRed and the second’s to addBlue. Wire the counter’s red and blue to the first chip’s red and blue.

4. Wire joined to one Text Decal’s Text and templated to the other’s.

5. Press each button a few times. The two signs always read the same.

Under the Hood

Open the first chip and count the gates.

• joined is five Append String gates in a row. Each .. is one gate, and each gate joins exactly two pieces. Three values with text in front of each make six pieces, and six pieces take five joins. In general, N values with text in front of each cost 2N-1 gates.
• templated is one Format String gate. Its Format String is Red {0}, Blue {1}, Total {2}: each ${} became a numbered slot, and the values are wired into the gate’s Input A, Input B and Input C.
• red + blue is one Add gate, and both outputs share it.

A Format String gate has seven inputs, Input A to Input G, so one gate holds up to seven values. Write more and the compiler splits the template across several gates and joins their outputs, so you never have to count:

@left in n: int
@right out row = "${n} ${n - 1} ${n - 2} ${n - 3} ${n - 4} ${n - 5} ${n - 6} ${n - 7} ${n - 8}"

This row has nine values. Open the chip: there are three Format String gates, one with seven slots, one with two, and one that joins the first two.

A brace in the text

The Format String gate reads {0} as a slot, so braces mean something to it. In a ${} template you can still type { and } as text: the compiler doubles each one in the gate’s text so the gate does not take it for a slot.

@left in red: int
@right out sign = "{red} = ${red}"

Open the chip: the gate’s Format String is {{red}} = {0}. Wire sign to a Text Decal and check that it shows single braces. To show a $, write \$.

Modify

1. Add who is ahead. if ... then ... else picks one of two values: here "Red" when red > blue is true, "Blue" when it is false. Give it a name with let, then put the name in the template.

   @left in red: int
   @left in blue: int
   let leader = if red > blue then "Red" else "Blue"
   @right out text = "Red ${red}, Blue ${blue}. ${leader} leads."
   

   What does the sign say when the scores are equal?

2. Fix the tie: an else can hold another if. if red == blue then "Nobody" else if red > blue then "Red" else "Blue".

3. Put the two scores on separate lines with <br>, and color the names with <color="RRGGBB"> (Rich Text Markup). Write the template in single quotes so the double quotes in the tag need no escaping: '<color="ff4040">Red ${red}<br><color="4080ff">Blue ${blue}'. It is still one gate: tags are just more text.

Make

Make a sign for three teams that shows each score and the total, written as one template. How many gates does it take? How many would the .. version take?

button1 Held -> chip red
button2 Held -> chip blue
button3 Held -> chip green
chip text -> decal Text

Good to Know

• A bool in a slot prints as a number: true shows 1. Word Forms prints words instead.

See String Interpolation for the reference.

Next: Fmt.

Fmt

A ${} template holds its text and its values together. Fmt keeps them apart: you write the template once, with lettered slots, and fill it with values each time you use it. One template can then serve many signs.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

chip2 "Counter"
chip "Sign"
button1 Held -> chip2 addRed
button2 Held -> chip2 addBlue
chip2 red -> chip red
chip2 blue -> chip blue
chip redText -> decal1 Text
chip blueText -> decal2 Text

Code

const LINE = "{A}: {B}"

@left in red: int
@left in blue: int
@right out redText = Fmt(LINE, "Red", red)
@right out blueText = Fmt(LINE, "Blue", blue)

const LINE = "{A}: {B}" names a fixed piece of text. Fmt(format, ...) uses the Format String gate directly. The first argument is the format: the template text. The rest are the values, up to seven of them. The first value fills {A}, the second fills {B}, and so on up to {G}. These letters are the names the gate’s own tooltip uses for its inputs.

Red is pressed twice and Blue once. What does each sign show? Now change LINE to "{B} for {A}". What do they show?

Run

1. Compile the chip and paste it in-game. Place two Buttons and two bricks with a Text Decal.
2. Paste the counter chip from Interpolation. Wire the Buttons’ Held to its addRed and addBlue, its red and blue to this chip’s red and blue, and redText and blueText to each Text Decal’s Text.
3. Press the red button twice and the blue one once. The signs read Red: 2 and Blue: 1.

Under the Hood

Open the chip: two Format String gates, both with the Format String {A}: {B}. In each, Input A holds its word, set inside the gate, and Input B is wired from a pin. A const is not a gate: its text is copied into every gate that uses it, so changing LINE changes both signs.

• A slot can be used more than once and in any order: Fmt("{B} {A} {B}", x, y) prints y x y.
• The numbered form {0} to {6} also works: {0} is Input A. It is what ${} compiles to, as you saw in Interpolation. Use the letters in your own templates: the options in the next lessons are written with them.
• Passing more than seven values is a compile error (WS011): the gate has no eighth input. ${} splits long templates for you, and Fmt does not.

Modify

1. Change LINE to "{A} team: {B} points". Both signs change, and you edited one line.

2. Add a third value: how many points each team still needs to win.

   const GOAL = 10
   const LINE = "{A}: {B} ({C} to go)"
   
   @left in red: int
   @left in blue: int
   @right out redText = Fmt(LINE, "Red", red, GOAL - red)
   @right out blueText = Fmt(LINE, "Blue", blue, GOAL - blue)
   

3. The format does not have to be fixed. Pick one of two templates with a Switch: the format is then a wire into the gate’s Format String input.

   const SHORT = "{A}: {B}"
   const LONG = "Team {A} has {B} points"
   
   @left in wide: bool
   @left in red: int
   let line = if wide then LONG else SHORT
   @right out redText = Fmt(line, "Red", red)
   

   Wire a Switch’s Enabled to wide and flip it.

Make

Make a scoreboard for four teams. Use one const template for every row, and join the four rows into one sign with a ${} template that puts <br> between them. How many Format String gates does it take?

button1 Held -> chip red
button2 Held -> chip blue
button3 Held -> chip green
button4 Held -> chip yellow
chip board -> decal Text

Good to Know

• In a format string, a brace you type starts a slot, and a slot the gate cannot fill prints 0: Fmt("literal{a}brace") shows literal0brace. Fmt passes its format to the gate as written, unlike ${}, which doubles your braces.
• A numbered slot with no value wired prints 0: Fmt("{0}{1}", 1) shows 10.

See String Formatting for the reference.

Next: Number Options.

Number Options

A slot can carry an option that changes how its number prints: commas between the thousands, or a fixed number of decimals. Leading zeros have no option, so this lesson builds them by hand, then prints real dates and times.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

chip2 "Counter"
chip "Sign"
button Held -> chip2 addRed
chip2 red -> chip presses
chip big -> decal1 Text
chip share -> decal2 Text
chip both -> decal3 Text

Code

@left in presses: int
@right out big = Fmt("{A:,} points", presses * 125000)
@right out share = Fmt("{A:.2} each", presses / 4.0)
@right out both = Fmt("{A:,.2} coins", presses * 1234.5)

An option goes inside the slot, after a colon.

• {A:,} groups the thousands with commas: 1,234,567.
• {A:.2} prints exactly two digits after the point: 12.50. Any count up to 6 works.
• {A:,.2} does both: 1,234.50.

presses / 4.0 divides by a number with a point in it, so the result keeps its fraction: 3 presses give 0.75, not 0.

After three presses, what does each sign show?

Run

1. Compile the chip and paste it in-game. Place a Button and three bricks with a Text Decal.
2. Paste the counter chip from Interpolation. Wire the Button’s Held to its addRed and its red to presses. Wire big, share and both to the three Text Decals’ Text.
3. Press the button three times. The signs read 375,000 points, 0.75 each and 3,703.50 coins. Press once more: share shows 1.00, two decimals even when they are zero.

Under the Hood

Open the chip. Each Format String gate still has its option in its Format String ({A:,} points): the gate applies the option every time the value changes.

Write options on the lettered slots, as here. Whether they also work on the numbered form ({0:.2}) has not been checked, so the lettered form is the one to use. Options need Fmt: a ${} template has nowhere to put them.

Modify

1. Leading zeros. No option pads 7 to 07, so write a helper that does.

   mod pad2(n: int) -> string {
     let s = "0${n}"
     return s.Substring(s.Length() - 2, 2)
   }
   
   @left in presses: int
   @right out padded = pad2(presses)
   

   mod defines a helper with a name. n: int is its input, -> string says it gives back text, and return gives that text. Each use copies the helper’s gates into the chip (mod). The body puts a 0 in front, then keeps the last two characters: s.Length() counts the characters, and s.Substring(start, length) takes length of them from position start. So 7 becomes 07, and 42 becomes 042 and then 42. It only works below 100: 100 would come out as 00.

2. Minutes and seconds. A lap timer: the first press starts it, and every press after that shows the time since the first, as mm:ss.

   mod pad2(n: int) -> string {
     let s = "0${n}"
     return s.Substring(s.Length() - 2, 2)
   }
   
   @left in pressed: exec
   var started: int = 0
   var elapsed: int = 0
   @right out lap = "${pad2(elapsed.Value / 60)}:${pad2(elapsed.Value % 60)}"
   
   on pressed {
     let now = GetUnixTime()
     if started == 0 {
       started = now
     }
     elapsed = now - started
   }
   

   GetUnixTime() reads the server’s clock as a whole number of seconds (counted from 1 January 1970). if started == 0 { ... } runs its block only on the first press, while nothing is stored yet. Dividing one whole number by another gives a whole number, so elapsed / 60 is the full minutes. % gives the remainder: the seconds left over. Wire a Button’s Held to pressed and lap to a sign.

3. Dates. FormatDate turns a Unix time into text.

   @left in pressed: exec
   var stamp: int = 0
   @right out when = FormatDate(stamp.Value, "%Y-%m-%d %H:%M", useUTC = true).Output
   
   on pressed {
     stamp = GetUnixTime()
   }
   

   The sign shows when the button was last pressed. In the format, %Y is the year, %m the month, %d the day, %H the hour and %M the minute. useUTC = true gives the time in UTC, and false gives the server’s local time. The gate also has a Success output, .Success, which is false when it could not format the date.

Make

Make a sign for a parkour course: the first press of a start button stores the time, and a finish button shows the run’s time as mm:ss, plus the date and time of the run.

button1 Held -> chip start
button2 Held -> chip finish
chip text -> decal Text

Good to Know

• Store times from GetUnixTime(), not ServerUptime(). Uptime starts again from zero when the server restarts, but a var keeps its value, so a stored uptime can point into the future.

See String Formatting and Date / time for the reference.

Next: Word Forms.

Word Forms

Numbers need the right words around them: 1 apple but 2 apples, 1st but 2nd. A bool in a slot prints 1 when true, which is rarely what a sign should say. The Format String gate can pick these words itself, in the template.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

chip2 "Counter"
chip "Sign"
button Held -> chip2 addRed
chip2 red -> chip presses
switch Enabled -> chip isOpen
chip doorText -> decal1 Text
chip appleText -> decal2 Text
chip placeText -> decal3 Text

Code

@left in isOpen: bool
@left in presses: int
@right out doorText = Fmt("Door: {A:Open=Closed}", isOpen)
@right out appleText = Fmt("{A} {A}|plural(one=apple,other=apples)", presses)
@right out placeText = Fmt("You came {A}{A}|ordinal(one=st,two=nd,few=rd,other=th)", presses)

• {A:Open=Closed} is an option for a bool: the word before = when the value is true, the word after it when false.
• {A}|plural(...) is a word form. A slot followed by a bar and a form prints a word picked by the value, instead of the value itself. The form lists words by category: one is the word for a count of one, other the word for larger counts. That is why the template has {A} twice: the first prints the number, the second its word.
• {A}|ordinal(...) picks an ending for a place: one, two, few and other are the categories the gate sorts places into, giving 1st, 2nd, 3rd and 4th.

After one press, what do the signs say? After two?

Run

1. Compile the chip and paste it in-game. Place a Switch, a Button and three bricks with a Text Decal.
2. Paste the counter chip from Interpolation. Wire the Button’s Held to its addRed, its red to presses, and the Switch’s Enabled to isOpen. Wire the three outputs to the three Text Decals’ Text.
3. Flip the switch: Door: Open, Door: Closed. Press the button and watch the words change with the number.
4. Find out two things the lesson does not tell you. What does appleText say before the first press? What does placeText say at 11, 12 and 13?

Under the Hood

Open the chip: three Format String gates and nothing else. The words are inside each gate’s Format String, and the gate picks them as the value changes. No compare or select gates do the choosing.

By hand, the plural alone takes a compare and a select: let word = if presses == 1 then "apple" else "apples". The ordinal would take a chain of them.

These templates stay real gates even when every value is a constant: the compiler leaves options and word forms for the game to apply.

Modify

1. A form can insert the value itself. This prints one apple for 1 and 3 apples for 3:

   @left in presses: int
   @right out basket = Fmt("{A}|plural(one=one apple,other={A} apples) in the basket", presses)
   

   Here the number appears only inside the other form, so there is one {A} before the bar.

2. Two values with their own words. Add a second Button, counted on the counter’s blue, on coins: Fmt("{A} {A}|plural(one=player,other=players) found {B} {B}|plural(one=coin,other=coins)", presses, coins).

3. Mix an ordinal and a bool option. place <= 3 is a bool, so {B} can turn it into words:

   @left in place: int
   @right out result = Fmt("{A}{A}|ordinal(one=st,two=nd,few=rd,other=th) place. Medal: {B:Yes=No}", place, place <= 3)
   

Make

Make a door sign that reads The door is open. It has been opened 1 time., with the right word for open or closed and for time or times. Count the openings in a var that a handler adds to each time the switch turns on, as in Remembering Values.

switch Enabled -> chip isOpen
chip text -> decal Text

Good to Know

• A bool in a plain slot prints 1 when true. Use {A:Yes=No}, with your own words, to show it on a sign.

See String Formatting for the reference.

Next: Templates Chosen at Run Time.

Templates Chosen at Run Time

The format of an Fmt is an input like any other. It can come from a list, or be built while the circuit runs. This lesson uses that for message lists and lookup tables, and gives one rule for keeping them safe.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

zone "Zone Ref" -> chip room

Code

import { escape } from "sanitize"

const GREETINGS = [
  "Welcome, {A}!",
  "Good to see you, {A}.",
  "{A} is visitor number {B}.",
]

@left in room: zone
var visitors: int = 0

on ZoneEntered(zone = room) -> (character) {
  visitors += 1
  let template = GREETINGS[(visitors - 1) % 3]
  character.ShowChatMessage(Fmt(template, escape(character.GetDisplayName()), visitors))
}

[ ... ] is a list of values, an array. GREETINGS[i] reads the item at position i, counting from 0. % is the remainder after dividing, so (visitors - 1) % 3 goes 0, 1, 2, 0, 1, 2 as visitors arrive. The handler picks a template from the list, and Fmt fills it with the visitor’s name and number. The first two templates have no {B}, so they leave the number out.

escape makes the name safe to show, as in Reacting to the Game.

Which greeting does the fourth visitor get? The sixth?

Run

1. Compile the chip and paste it in-game. Give a brick an Attached Zone and wire its Zone Ref output to room.
2. Walk into the zone, out, and in again a few times. Each entry shows the next greeting in your chat. Only the player who walked in sees it.

Under the Hood

Open the chip. The list is one Array Var gate holding the three templates. In the handler, a Get Array Element step reads one of them, and its output is wired into the Format String gate’s Format String input. The format is no longer text set inside the gate: it changes from one run of the handler to the next.

Reading an item at a position that changes is a step in a handler. Outside a handler, GREETINGS[i] is an error (WS007).

Fmt as a lookup table

A format can also be built from a number, so that it picks one of the values:

@left in presses: int
let level = presses % 3
let hex = Fmt('{' .. level .. '}', 'ff4040', 'ffc040', '40ff40')
@right out sign = '<color="${hex}">Level ${level}'

'{' .. level .. '}' builds the format {0}, {1} or {2} while the circuit runs, and the gate prints that one input. One Format String gate is a table of up to seven values, picked by number, with no handler needed. Here it picks a color for a <color> tag (Rich Text Markup). Wire the red count of the counter chip from Interpolation to presses, a Button’s Held to the counter’s addRed, and sign to a Text Decal’s Text.

Build this format with .., not ${}. "{${level}}" would have its braces doubled, as in Interpolation, and they would never make a slot.

Player text goes in a slot

Only text you wrote belongs in a format string. Text a player chose, such as a display name or something typed, goes into a slot:

// Wrong: the name becomes part of the format.
character.ShowChatMessage(Fmt("Welcome, " .. name .. "!"))

// Right: the name is a value in slot A.
character.ShowChatMessage(Fmt("Welcome, {A}!", escape(name)))

In the wrong version, a player named {A} or {0} is read as a slot, and the gate prints something else in place of their name. In a slot, the name is only a value. ${} is safe in the same way: "Hello, ${escape(name)}" puts the name in a slot. Still escape it, because a < in a name starts a tag.

Modify

1. Add a fourth greeting, and make the handler follow the list’s length so you never have to change the 3: GREETINGS[(visitors - 1) % GREETINGS.length()].
2. Use a word form from Word Forms in a greeting: "{A} is our {B}{B}|ordinal(one=st,two=nd,few=rd,other=th) visitor.".
3. Give the lookup table a fourth color, and change level only every five presses: let level = clamp(presses / 5, 0, 3). clamp(x, low, high) keeps a value between two limits.

Make

Make a health sign. A pin hp: int from 0 to 100 picks a level with clamp(hp / 34, 0, 2). Use one lookup Fmt for the color and a second for the word (Healthy, Hurt, Danger), and show both in one template. Test it with the counter chip’s red count standing in for hp.

chip2 "Counter"
chip "Health"
button Held -> chip2 addRed
chip2 red -> chip hp
chip text -> decal Text

Good to Know

• Reading a list past its end gives the last value read, not the first item or an empty one. Keep the position in range, as % does here.
• A slot the gate cannot fill prints 0, so a mistake in a built format shows up as a 0 on the sign.

See String Formatting and const containers at runtime for the reference.

Next: Score Card.

Score Card

This project uses the whole Templates branch in one template, filled by one gate: a sign with a styled title, numbers with options, the right words for each count, and a status line.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

chip2 "Counter"
chip "Sign"
button1 Held -> chip2 addRed
button2 Held -> chip2 addBlue
chip2 red -> chip hits
chip2 blue -> chip misses
switch Enabled -> chip isOpen
chip card -> decal Text

Code

const CARD = '<size="32"><b><color="ffd040">TARGET RANGE</></></><br><color="ffffff">{A:,} {A}|plural(one=hit,other=hits), {B:,} {B}|plural(one=miss,other=misses)<br>Accuracy: {C:.1}%<br>{D:Open=Closed}'

@left in hits: int
@left in misses: int
@left in isOpen: bool
let accuracy = hits * 100.0 / (hits + misses)
@right out card = Fmt(CARD, hits, misses, accuracy, isOpen)

• The title line is rich text from Rich Text: a size, bold and a color, each closed with </>. The color tag before the body is never closed, so it lasts to the end.
• {A:,} and {C:.1} are number options from Number Options.
• {A}|plural(...) and {D:Open=Closed} are word forms from Word Forms.
• CARD is a const template filled by Fmt, as in Fmt.

Before anything is pressed, hits + misses is 0. What does the accuracy line say then?

Run

1. Compile the chip and paste it in-game. Place two Buttons, a Switch and a brick with a Text Decal.

2. Paste the counter chip from Interpolation. Wire the Buttons’ Held to its addRed and addBlue, its red to hits and its blue to misses, and the Switch’s Enabled to isOpen. Wire card to the Text Decal’s Text.

3. Press each button a few times and flip the switch. The card should read like this after three hits and one miss, with the switch on:

   TARGET RANGE
   3 hits, 1 miss
   Accuracy: 75.0%
   Open
   

Under the Hood

Open the chip. There is one add, one multiply and one divide for the accuracy, and one Format String gate for the whole card: four gates in all. Everything else (the title, the colors, the words, the options) is text inside the gate’s Format String.

The accuracy needs no check for zero shots. Dividing by zero gives 0, as in Numbers, so a fresh card reads Accuracy: 0.0%.

The template must stay in one Fmt. Built with .. instead, each piece would be its own gate, and the options and word forms would not work, because only the Format String gate reads them.

Modify

1. Add a best streak. Give the chip a third pin, streak, add <br>Best streak: {E} to the template, and pass streak as the fifth value.
2. Color the accuracy by how good it is. Pick the color with a lookup Fmt from Templates Chosen at Run Time, using clamp(hits * 3 / (hits + misses), 0, 2) as the position, and pass it into CARD as one more slot: <color="{F}">Accuracy: {C:.1}%. The position must be a whole number: hits * 3 / (hits + misses) divides two ints, which drops the fraction, while accuracy is a decimal and would build a format like {1.47} that picks nothing.
3. Give the card a place line: You are {G}{G}|ordinal(one=st,two=nd,few=rd,other=th), with G from a second counter chip’s red. A template holds at most seven values, A to G, so this one is now full.

Make

Make a shop sign for a vending machine. It shows the item name in a large colored title, the price with thousands grouped (1,250 coins), how many are left with the right word (1 can left, 3 cans left), and Sold out or In stock from a bool. Use one const template and one Fmt.

chip2 "Counter"
chip "Shop"
button Held -> chip2 addRed
chip2 red -> chip remaining
switch Enabled -> chip inStock
chip card -> decal Text

Good to Know

• A template holds seven values at most, {A} to {G}. A card that needs more must be split into two Fmts joined with ...
• A misspelled option is not an error. The compiler cannot check what is inside a template, so check the sign itself after every change.
• Text that comes from a player must never be part of the template itself: pass it in a slot, escaped, as in Safe Text.

Next: pick a lesson from the tree on the Learn page.

Exec Pins

So far a chip’s outputs have carried values. An output can also carry a pulse: a moment when something happened, which another part can react to. This lesson builds a doorbell that rings a real sound.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

button Held -> chip pressed
chip sign -> decal Text
chip ring -> speaker Play

Code

@left in pressed: exec
var rings: int = 0
@right out ring: exec
@right out sign = "Rings: ${rings.Value}"

on pressed {
  rings += 1
  emit ring
}

@right out ring: exec is an exec output, a pin that carries pulses instead of a value. emit ring sends a pulse out of it. It fires at the point the handler has reached, so here it fires after rings has gone up.

sign is an ordinary value output, the same as in earlier lessons.

ring has no value. What can a wire from it go into? What happens if you move emit ring above rings += 1?

Run

1. Compile the chip and paste it in-game. Place a Button, a brick with a Text Decal, and a One Shot Audio brick.
2. Open the One Shot Audio’s settings and pick a sound for it.
3. Wire the Button’s Held to pressed, sign to the Text Decal’s Text, and ring to the One Shot Audio’s Play.
4. Press the button. The sound plays once per press, and the sign counts the rings. Holding the button does not ring again.

Under the Hood

Open the chip. rings is a Var gate and sign comes from a Format String gate. The handler is a single Increment Variable gate: rings += 1 adds one in place. Its exec input is wired from pressed.

There is no gate for emit ring. The ring pin is wired straight from the Increment Variable’s exec output, so the pulse leaves the chip the moment the count has gone up. That is why the order of the lines matters. Move emit ring first and the pin is wired from pressed itself, beside the Increment Variable instead of after it.

emit can also set a value pin. This dice chip sets its number and then fires a pulse:

@left in roll: exec
@right out face: int
@right out rolled: exec

on roll {
  emit face = Random(1, 6)
  emit rolled
}

emit face = ... makes the Random gate drive face, and emit rolled fires after the roll. Whatever listens to rolled sees the new face. Set the value first, then fire the pulse.

A pin has one driver. An out with a value already drives its pin all the time, so a handler cannot also write it:

@left in pressed: exec
var rings: int = 0
@right out sign = "Rings: ${rings.Value}"

on pressed {
  rings += 1
  emit sign = "Ding!"
}

Error: [WS013] this `out sign = ...` drives `sign` continuously, and an `emit sign = ...` also writes it, so the two would fight over the output. Give this one a constant default (`out sign = 0`) and let the other write change it, or remove it

Drive each output one way, either with a value that is always computed or with writes from handlers.

Modify

1. Ring only on every other press. Wrap the emit: if rings % 2 == 0 { emit ring }.

2. Ring twice per press, half a second apart:

   @left in pressed: exec
   @right out ring: exec
   
   on pressed {
     emit ring
     await Sleep(_, delay = 0.5)
     emit ring
   }
   

   Open the chip. Two places fire ring, but a game input takes only one wire, so the compiler adds a Union gate that merges the two pulses into the pin.

3. Combine the dice and the doorbell: wire rolled to a One Shot Audio’s Play and face to a sign, so every roll makes a sound and shows its number.

Make

Make a doorbell that rings at most once every three seconds, however often the button is pressed. The sign should count every press, but only show “Ding!” when the bell really rang. A var can hold text too: var shown: string = "".

button Held -> chip pressed
chip sign -> decal Text
chip ring -> speaker Play

Good to Know

• An exec output carries no value. Wire it only into an input that takes a pulse, such as One Shot Audio Play. An exec input such as pressed takes a pulse or an on/off output like Held, and starts its handler when that output turns on.
• A One Shot Audio with no sound picked plays nothing when pulsed, and nothing tells you why.
• A game input takes one wire. When two places in your code fire the same exec pin, the compiler merges them with a Union. Wiring two exec outputs into one input by hand is not allowed.

See Exec outputs and emit in the reference.

Next: Custom Events.

Custom Events

Two chips can talk without a wire between them. One sends a named event, and every chip listening for that name runs a handler. This lesson splits the doorbell in two: a button chip by the door and a light chip anywhere else in your build.

Contents

• Code
• Run
• Under the Hood
• Constants do not travel
• Sending to one grid
• Global events
• Modify
• Make
• Good to Know

chip "Button chip"
button Held -> chip pressed

chip "Light chip"
chip light -> light Enabled
chip sign -> decal Text

Code

The button chip:

@left in pressed: exec
var presses: int = 0

on pressed {
  presses += 1
  SendCustomEvent("doorbell", presses)
}

The light chip:

var rings: int = 0
var lit: bool = false
@right out light = lit.Value
@right out sign = "Rings: ${rings.Value}"

on CustomEvent("doorbell") -> (count: int) {
  rings = count
  lit = !lit
}

SendCustomEvent("doorbell", presses) sends an event on the channel "doorbell", carrying one value. on CustomEvent("doorbell") runs whenever an event on that channel arrives, and -> (count: int) names the value it carried. A channel name is any text you choose. Both ends must spell it the same way.

Each event can carry up to eight values, in order. The receiver lists them in the same order, with the same types the sender sends: here one int.

The two chips share no wire. Paste a second copy of the light chip. What happens to it when you press the button?

Run

1. Compile both chips and paste them in-game. Place a Button by the first, and a Point Light and a brick with a Text Decal by the second.
2. Wire the Button’s Held to pressed. Wire light to the Point Light’s Enabled and sign to the Text Decal’s Text.
3. Press the button. The light toggles and the sign counts the presses.
4. Paste the light chip again, with its own light. Both lights now toggle on every press: every chip listening on "doorbell" hears it.

Under the Hood

Open the button chip. After the Increment Variable comes a Get Variable that reads presses, then a Send Personal Custom Event gate. The channel name is typed into the gate, and the count is wired into its Data In1.

Open the light chip. A Personal Custom Event gate, with doorbell typed in, starts the handler. Its Data Out1 is wired into the Set Variable for rings.

“Personal” means the event reaches only circuits pasted by the same player. A light chip someone else pasted does not hear your button.

The handler runs on the tick after the send, not in the same tick. An event is delivered on the next frame, so a reply to an event, and the reply to that, each cost a tick.

The light chip has no sender in its own code, so it cannot work out the type of count by itself. Leave the type off and the compiler warns:

var rings: int = 0
@right out sign = "Rings: ${rings.Value}"

on CustomEvent("doorbell") -> (count) {
  rings = count
}

WARN [WS042] custom event 'doorbell' data param 'count' (#1): no in-unit sender to infer its type from, so it defaults to float; annotate `count: <type>` to silence

The sender decides what each slot carries. The receiver’s types have to match it, and a mismatch is not always reported, so write the types out on every receiver.

Constants do not travel

Send a fixed number and the event arrives, but the number may not:

@left in pressed: exec

on pressed {
  SendCustomEvent("doorbell", 1)
}

This compiles with no warning. Open the chip: Data In1 has no wire. The 1 is typed into the gate’s box instead, and the receiver can read 0 there. Put the value in a variable (var door: int = 1) and send door. The chip then reads it with a Get Variable and wires it into Data In1.

Sending to one grid

Every listener hears an ordinary event. To answer just one chip, send to its grid. Here the button chip sends its own grid along with the count, and the light chip answers on a second channel:

@left in pressed: exec
var presses: int = 0
var heard: bool = false
@right out lamp = heard.Value

on pressed {
  presses += 1
  SendCustomEvent("doorbell", presses, ReadBrickGrid())
}

on CustomEvent("doorbell.heard", isObject = true) {
  heard = !heard
}

var rings: int = 0
@right out sign = "Rings: ${rings.Value}"

on CustomEvent("doorbell") -> (count: int, door: entity) {
  rings = count
  door.SendCustomEvent("doorbell.heard")
}

ReadBrickGrid() is the grid the chip sits on, as an entity. door.SendCustomEvent(...) sends to that grid only. A sent-to event is an object event, and only a receiver marked isObject = true hears one. Without it, on CustomEvent("doorbell.heard") never runs, and nothing reports why.

Chips placed straight on the ground all sit on the same grid, so a reply sent there reaches every isObject listener on the ground. Sending to a grid pays off when chips sit on separate grids, such as a vehicle or a copy the circuit spawned itself.

Global events

An ordinary custom event is personal: it reaches only circuits pasted by the player who pasted the sender. A global event reaches every listening circuit, whoever pasted it. Send one with SendGlobalCustomEvent and listen with on GlobalCustomEvent:

@left in pressed: exec
var presses: int = 0

on pressed {
  presses += 1
  SendGlobalCustomEvent("doorbell", presses)
}

var rings: int = 0
@right out sign = "Rings: ${rings.Value}"

on GlobalCustomEvent("doorbell") -> (count: int) {
  rings = count
}

How they differ from personal events:

• Who hears it. Every on GlobalCustomEvent with the channel’s name runs, in every player’s circuits.
• Separate channels. A global "doorbell" and a personal "doorbell" never meet: SendGlobalCustomEvent does not reach on CustomEvent, and SendCustomEvent does not reach on GlobalCustomEvent.
• Admin to send. Send Global Custom Event is an admin gate, so only an admin can load the button chip. Listening needs no admin: anyone’s chip can react to an admin’s global events.

The rest works the same way: up to 8 values, target with isObject = true for one grid, and the receiver runs on the tick after the send. Use personal events inside one player’s build, and global events when circuits pasted by different players must talk, such as a server’s round system that everyone’s chips follow.

Modify

1. Send a second value: add var door: int = 1 to the button chip and send SendCustomEvent("doorbell", presses, door). Receive it as -> (count: int, door: int) and show it on the sign. Paste a second button chip with door = 2, so the sign says which door rang.
2. Make the light chip’s sign show “Back door” or “Front door” instead of the number.
3. In the reply version, wire the button chip’s lamp to a small Point Light beside the button, so the person ringing sees that someone heard.

Make

Make a call board with three buttons in different rooms and one board in a fourth room. Each button chip sends its room number. The board shows the last room that called and lights a lamp for it until a reset button on the board is pressed.

chip "Board"
chip2 "Call"
button1 Held -> chip2 pressed
button2 Held -> chip reset
chip sign -> decal Text
chip lamp1 -> light1 Enabled
chip lamp2 -> light2 Enabled
chip lamp3 -> light3 Enabled

Good to Know

• Events reach only circuits pasted by the same player. A chip a friend pasted does not hear yours, unless the event is global.
• The receiver runs on the tick after the send.
• A constant argument is not wired, and the receiver can read 0 or an empty string. Send a var instead.
• A send to a grid needs isObject = true on the receiver, and a receiver marked that way hears only sends to its grid.
• One send gate fired many times in a single tick does not deliver every time. The game logs “Too many events at once!” for that channel. Separate send gates firing once each on the same channel all deliver.
• When several events arrive in one tick, their order is not fixed.

See Custom Events in the reference.

Next: Waiting.

Waiting

A handler so far ran from top to bottom in one go. await lets it stop partway, wait for something to happen, and carry on from there. This lesson builds a reaction timer, then a guessing game that waits for one of two buttons.

Contents

• Code
• Run
• Under the Hood
• Racing two waits
• Signals of your own
• Calling from outside a handler
• Modify
• Make
• Good to Know

button1 Held -> chip start
button2 Held -> chip hit
chip light -> light Enabled
chip sign -> decal Text

Code

@left in start: exec
@left in hit: exec
var lit: bool = false
var began: float = 0.0
var shown: string = "Press start"
@right out light = lit.Value
@right out sign = shown.Value

on start {
  shown = "Wait for the light..."
  await Sleep(_, delay = 2.0)
  lit = true
  began = ServerUptime()
  await hit
  lit = false
  shown = "${ServerUptime() - began} seconds"
}

The handler is one sequence with two waits in it. await Sleep(...) waits two seconds. await hit waits for the hit button to be pressed. ServerUptime() is the number of seconds the server has been running, so storing it when the light comes on and subtracting it after the press gives the reaction time.

What happens if you press hit while the sign still says “Wait for the light…”?

Run

1. Compile the chip and paste it in-game. Place two Buttons, a Point Light and a brick with a Text Decal.
2. Wire one Button’s Held to start and the other’s to hit. Wire light to the Point Light’s Enabled and sign to the Text Decal’s Text.
3. Press start. Two seconds later the light comes on. Press hit as fast as you can. The light goes off and the sign shows your time.
4. Press hit early, during the wait. Nothing happens, and the timer still waits for a press after the light comes on.

Under the Hood

Open the chip. Each await became the same handful of gates:

• a Var that holds the await’s armed flag,
• a Set Variable that turns the flag on when the chain reaches the await,
• a Get Variable and a Branch that let the waited-for pulse through only while the flag is on,
• a Set Variable that turns the flag off again.

That is about five gates per await. The Sleep adds one Buffer (Seconds). Its input is the armed flag (that is what _ stands for), and its output turns on two seconds after the flag does.

The flag is why an early press does nothing. hit is wired into the second await’s Get Variable all the time, but until the chain gets there, the flag is off and the Branch drops the pulse.

Racing two waits

Nobody pressing hit leaves the timer waiting forever. || between two waits resumes on whichever comes first:

@left in start: exec
@left in hit: bool
var shown: string = "Press start"
@right out sign = shown.Value

on start {
  shown = "Press hit within 3 seconds"
  await hit || Sleep(_, delay = 3.0)
  if hit {
    shown = "In time"
  } else {
    shown = "Too slow"
  }
}

The two sides go into an OR gate, and the await resumes when the OR turns on. The race does not say which side won. A press normally still holds hit on when the chain resumes, so if hit tells the two apart. That reads the pin’s value, so hit is a bool here, not an exec.

Signals of your own

let answer: exec makes a signal, an exec with a name, which any handler can fire with emit and any handler can wait for with await. It can carry a value along:

@left in ask: exec
@left in left: exec
@left in right: exec
var shown: string = "Press ask"
@right out sign = shown.Value

let answer: exec

on left {
  emit answer = 1
}

on right {
  emit answer = 2
}

on ask {
  let secret = Random(1, 2)
  shown = "Left or right?"
  let picked = await answer
  if picked == secret {
    shown = "Right guess!"
  } else {
    shown = "Wrong guess"
  }
}

emit answer = 1 fires the signal and stores 1 with it. let picked = await answer waits for the signal and reads the value that came with it. The value is kept in a hidden variable, so it is still there when the waiting handler picks it up.

Wire three Buttons to ask, left and right. Pressing left or right before ask does nothing, for the same reason the early hit did nothing.

Calling from outside a handler

Some calls are steps, like Random, and need a pulse to run. Inside a handler the pulse comes from the chain. Outside one, give it with exec =:

@left in roll: exec
let r = Random(1, 6, exec = roll)
@right out face = r

exec = roll wires roll into the Random gate’s exec input. There is no handler and no Set Variable, just one gate. The same works for array and map steps.

Modify

1. Make the wait before the light random: store Random(1, 4) in a var delay: float first, then await Sleep(_, delay = delay).
2. Give the reaction timer the race: wait for hit || Sleep(_, delay = 3.0) and show “Too slow” when the light was missed. The race reads hit as a value, so make it @left in hit: bool, as in the race above. Then catch a cheater: check hit right before the light comes on, and show “Too early!” if it is already held.
3. In the guessing game, add a third button and a third answer. Then add a timeout: a second on ask handler that waits five seconds and does emit answer = 0. Show “Out of time” when picked is 0. (A race with || cannot carry a value, so the timeout sends one of its own.)

Make

Make a “Simon says” for one button: the light blinks one to three times (chosen with Random), then the player presses the button that many times within four seconds. Use a signal that the button handler fires, and count the presses in a var.

button1 Held -> chip start
button2 Held -> chip press
chip light -> light Enabled

Good to Know

• A pulse that arrives before its await is reached is dropped, not saved for later.
• await waits for a pulse. With a Button’s Held wired to the pin, that is the moment Held turns on, so holding the button down while the await is reached does not count as a press.
• Sleep measures seconds and SleepTicks measures ticks. SleepTicks with delay = 0 resumes on the next tick, and delay = N after N + 1 ticks.
• A value stored with ServerUptime() is only good while the server keeps running. A restart sets the uptime back to zero.

See Await, Payload Ferrying and Explicit Exec Argument in the reference.

Next: Forking and Merging.

Forking and Merging

An exec chain does not have to be a single line. It can split one way or the other, split into two paths that both run, and join back together. This lesson builds a shop counter with an open sign and a bell, then takes its pulses apart and puts them back together.

Contents

• Code
• Run
• Under the Hood
• Merging with Union
• Forking with .exec
• Naming a handler
• Modify
• Make
• Good to Know

switch Enabled -> chip staffed
button Held -> chip bell
chip sign -> decal Text
chip chime -> speaker Play

Code

@left in staffed: bool
@left in bell: exec
var shown: string = "Closed"
@right out sign = shown.Value
@right out chime: exec

on staffed {
  shown = "Open"
}

on !staffed {
  shown = "Closed"
}

let door = Branch(staffed, bell)

on door.A {
  emit chime
}

on door.B {
  shown = "Closed. Back soon"
}

on !staffed runs when staffed turns off, the opposite edge to on staffed.

Branch(staffed, bell) is a gate that sends each bell pulse one of two ways: out of .A while staffed is on, out of .B while it is off. on door.A and on door.B are handlers on those two outputs.

The switch is off and someone rings. What does the sign say, and does the chime play? What happens when the switch is then flipped on and off again?

Run

1. Compile the chip and paste it in-game. Place a Switch behind the counter, a Button in front of it, a brick with a Text Decal and a One Shot Audio brick with a sound picked in its settings.
2. Wire the Switch’s Enabled to staffed and the Button’s Held to bell. Wire sign to the Text Decal’s Text and chime to the One Shot Audio’s Play.
3. Flip the switch on and the sign says “Open”. Ring, and the chime plays.
4. Flip the switch off and ring: no chime, and the sign asks customers to come back.

Under the Hood

Open the chip. on staffed is a Set Variable wired straight from staffed. on !staffed puts a NOT gate in front of its Set Variable, so the chain starts when the NOT turns on, which is when staffed turns off.

There is one Branch gate. staffed goes into its Cond input and bell into its Exec. Exec Out A is wired straight to the chime pin, and Exec Out B to the Set Variable for the “Back soon” sign.

An if inside a handler compiles to this same Branch gate. Branch(...) is the gate itself, for when there is no handler to put an if in.

door.A reads a field of a result, and on can trigger on a field like that, the same as on a pin.

Merging with Union

Two exec wires cannot go into one input. To run one handler from two pulses, merge them with a Union gate:

@left in front: exec
@left in back: exec
var rings: int = 0
@right out sign = "Rings: ${rings.Value}"

let rang = Union(front, back)

on rang {
  rings += 1
}

rang is a named exec, a Union of the two buttons. It fires when either does. You can also write the call straight into the trigger: on Union(front, back) { ... }.

|| is not a merge. It makes one value, true while either side is true, so on front || back misses a press of one button while the other is held. With an object on one side, it is true for as long as the object exists, and the compiler warns:

@left in front: bool
@left in rider: character
var rings: int = 0
@right out sign = "Rings: ${rings.Value}"

on front || rider {
  rings += 1
}

WARN [WS116] `||` here makes one value, it does not wait for either side: an object is true for as long as it exists, so this handler fires once, when the object appears, and never again. To fire on either, write `on Union(a, b)`

Forking with .exec

One exec output wired into two inputs runs both. That is how one pulse starts two things at once. A call normally joins the chain, so the next line waits until it has finished.

@left in bell: exec
var lit: bool = false
var rings: int = 0
@right out light = lit.Value
@right out sign = "Rings: ${rings.Value}"

chip Flash() {
  lit = true
  await Sleep(_, delay = 1.0)
  lit = false
}

on bell {
  let _ = Flash().exec
  rings += 1
}

chip Flash() { ... } names a block of steps that runs wherever Flash() is called, on a microchip brick of its own. Chips covers chips in full. Flash() lights the lamp for a second. .exec on the call names the pulse it sends when it has finished, and let _ = lets that pulse go unused. The call then runs beside the chain instead of in it, so the count goes up at once. Write plain Flash() instead and the sign changes a second late, because rings += 1 waits for the flash.

To run something after the flash, keep the result and trigger on its .exec:

let f = Flash(exec = bell)

on f.exec {
  flashes += 1
}

exec = bell starts the flash from bell with no handler around it, as Random(..., exec = ...) did in Waiting. on f.exec runs when it has finished.

Naming a handler

let ... = on gives a handler a name, and the name is a trigger that fires after the handler’s body has run:

@left in bell: exec
var rings: int = 0
@right out sign = "Rings: ${rings.Value}"
@right out chime: exec

let rang = on bell {
  rings += 1
}

on rang {
  emit chime
}

Without a body, let ... = on names the trigger itself. An on that uses the name runs as if the trigger, with its settings, were written there:

@left in room: zone
var visits: int = 0
@right out sign = "Visits: ${visits.Value}"

let entered = on ZoneEntered(zone = room)

on entered -> (character) {
  visits += 1
  character.ShowChatMessage("Welcome!")
}

Modify

1. A handler can declare an output of its own. Replace shown and sign in the shop with these two handlers:

   @left in staffed: bool
   
   on staffed {
     @right out sign: string = "Open"
   }
   
   on !staffed {
     out sign = "Closed"
   }
   

   Open the chip. The two writes share a hidden Var that drives the pin. It starts empty, so the sign is blank until the switch first moves.

2. Give the shop a back door: merge a second bell Button into the first with Union, and branch on staffed after the merge.

3. Make the chime flash a light too, without delaying the sign: fork a Flash() from on door.A.

Make

Make a stage light. A Switch turns the show on and off. While the show is on, a Button flashes a spotlight for one second and plays a sound at the same moment, and a sign counts the flashes after each one ends. While the show is off, pressing the Button shows “No show tonight” on the sign.

switch Enabled -> chip show
button Held -> chip flash
chip spot -> light Enabled
chip sound -> speaker Play
chip sign -> decal Text

Good to Know

• on x fires when x turns on and on !x when it turns off. Neither fires again while the switch stays where it is.
• A Branch decides by its Cond at the moment the pulse arrives. Changing the condition afterwards does not reroute a pulse already sent.
• Exec wires may split but not join. One output into many inputs is fine, but many outputs into one input is not. The compiler merges them with a Union when your code asks for it.

See Forking the Exec Chain, Exec-flow gates, Negated Triggers, Union Triggers, Handler-declared outputs and let on in the reference.

Next: pick a lesson from the tree on the Learn page.

Mods

A mod gives a piece of circuit a name, so you can write it once and use it in many places. Every place that uses it gets its own copy of the gates.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

zone1 Occupied -> chip busy1
zone2 Occupied -> chip busy2
chip sign1 -> decal1 Text
chip sign2 -> decal2 Text

Code

@left in busy1: bool
@left in busy2: bool

mod status(name: string, busy: bool) -> string {
  return if busy then "${name}: busy" else "${name}: free"
}

@right out sign1 = status("Workshop", busy1)
@right out sign2 = status("Storage", busy2)

• mod status(name: string, busy: bool) declares a mod with two inputs, like the pins of a small chip.
• -> string says it gives back one value, a piece of text.
• return names that value. Here it is one if ... then ... else expression: if busy then A else B is A while busy is true and B otherwise. Choices can chain: if a then X else if b then Y else Z.
• status("Workshop", busy1) is a call. It runs the mod’s body with name set to "Workshop" and busy set to busy1.

The mod is written once and called twice. How many gates does the chip hold? Which of them belongs to status?

Run

1. Compile the chip and paste it in-game. Build two small rooms. Give a brick in each an Attached Zone that fills the room, and place a Text Decal by each door.
2. Wire the first zone’s Occupied to busy1 and the second’s to busy2.
3. Wire sign1 and sign2 to the two Text Decals’ Text.
4. Walk into the workshop and its sign says Workshop: busy. Walk out and it says Workshop: free. The storage sign does not change.

Under the Hood

Open the chip. There are two Select gates and nothing named status.

Each call became its own Select. Click one. Its two text inputs are typed in, Workshop: free and Workshop: busy. The other Select holds the storage texts. The name was a constant, so the compiler worked out both texts ahead of time and typed them into that call’s copy.

The compiler pastes a mod’s body in at each call and fills in the inputs. One call is one Select, and ten calls would be ten. In a code editor, hover over status to see “inlined per call”, the compiler’s reminder of this.

A mod can also choose its value step by step, with if statements and an early return:

@left in busy1: bool

mod status(name: string, busy: bool) -> string {
  if busy { return "${name}: busy" }
  return "${name}: free"
}

@right out sign1 = status("Workshop", busy1)

Error: [WS007] `status` returns from inside a branch, so choosing between its returns needs an exec context: call it from a handler or a `mod` body, or pass `exec = ...`

if statements run one step after another, so they need a pulse to run on. An out pin has none. Write the choice as one expression, as in the first version, or call the mod inside an on handler, where there is a pulse.

Modify

1. Add a third room, an office. Add @left in busy3: bool and @right out sign3 = status("Office", busy3). Open the chip again and there is a third Select.

2. Give status two outputs by naming them. A light by each door shows whether the room is free:

   @left in busy1: bool
   @left in busy2: bool
   
   mod status(name: string, busy: bool) -> (text: string, lit: bool) {
     out text = if busy then "${name}: busy" else "${name}: free"
     out lit = !busy
   }
   
   let workshop = status("Workshop", busy1)
   let storage = status("Storage", busy2)
   @right out sign1 = workshop.text
   @right out sign2 = storage.text
   @right out free1 = workshop.lit
   @right out free2 = storage.lit
   

   With named outputs, a call gives back a record, and workshop.text and workshop.lit read its two values. Wire free1 and free2 to two Point Lights’ Enabled.

3. Count how many times each room has been used. A mod can change a variable it is given, if the input is marked with *:

   @left in busy1: bool
   @left in busy2: bool
   var visits1: int = 0
   var visits2: int = 0
   
   mod status(name: string, busy: bool) -> string {
     return if busy then "${name}: busy" else "${name}: free"
   }
   
   mod bump(count: *int, by: int = 1) {
     count += by
   }
   
   on busy1 { bump(visits1) }
   on busy2 { bump(visits2) }
   @right out sign1 = "${status("Workshop", busy1)}<br>${visits1.Value} visits"
   @right out sign2 = "${status("Storage", busy2)}<br>${visits2.Value} visits"
   

   count: *int means “a variable holding an int”, not a copy of its value, so bump(visits1) adds to visits1 itself. Ref Parameters covers * in full. by: int = 1 is a default, so a call that leaves by out uses 1. <br> in the sign’s text starts a new line. Change the storage room to count each visit twice, with bump(visits2, 2).

   on busy1 fires when the room goes from empty to occupied, so a second person walking in while the first is still there is not counted.

Make

Make a sign for a parking area with three bays, each with its own zone. Write a mod that takes a bay’s number and whether it is taken, and returns one line of text such as Bay 2: taken. Show all three lines on one sign, and add a fourth line that says Full when every bay is taken.

zone1 Occupied -> chip bay1
zone2 Occupied -> chip bay2
zone3 Occupied -> chip bay3
chip sign -> decal Text

Good to Know

• Every call is a full copy. A mod of 50 gates called from ten places is 500 gates, and nothing warns you. Counting the Cost shows how to check.
• A static var, a variable declared inside a mod that keeps its value between runs, is copied too, so each call has its own. Two calls never share a count.
• A zone’s Occupied stays on while anyone is inside, so the sign shows busy until the last person leaves.

See also: mod: Inline Chips, Default and Named Arguments and return.

Next: Chips.

Chips

A chip is a mod that gets a microchip brick of its own. Its gates sit on their own grid inside the brick, which you can open in-game. Chips keep a big circuit tidy, and a named chip can be placed many times, each with its own state.

Contents

• Code
• Run
• Under the Hood
• Modify
• Make
• Good to Know

button1 Held -> chip red
button2 Held -> chip blue
button3 Held -> chip reset
chip board -> decal Text

Code

@left in red: exec
@left in blue: exec
@left in reset: exec

chip Tally(press: exec, clear: exec) -> int {
  var n: int = 0
  on press { n += 1 }
  on clear { n = 0 }
  out _ = n.Value
}

let redScore = Tally(red, reset)
let blueScore = Tally(blue, reset)
@right out board = "Red ${redScore}  Blue ${blueScore}"

chip Tally(...) is written like a mod: inputs in brackets, -> int for the value it gives back. Inside, a chip can hold anything a file can, such as a variable, handlers, and out _ = ... to set the value it gives back (_ is the name of a single unnamed output).

Tally keeps a count in var n. Red and Blue both call it. When Red’s button is pressed, does Blue’s score go up too?

Run

1. Compile the chip and paste it in-game. Place three Buttons, for Red, Blue and Reset, and a Text Decal.
2. Wire each Button’s Held to red, blue and reset, and board to the Text Decal’s Text.
3. Press Red three times and Blue once, and the sign says Red 3 Blue 1. Press Reset and both go back to 0.

Under the Hood

Open the chip. Inside are two microchip bricks, both labeled Tally. Open one. It holds a Var gate n, an Increment Variable for on press, and a Set Variable for on clear.

Each call made a new chip with its own n, so Red and Blue keep separate scores. That is the same rule as a mod (every call is a copy), with a brick around each copy.

Look at the edge of an open Tally: three pins, press, clear and _. Each is a Microchip Input or Microchip Output gate. Every wire that crosses a chip’s wall goes through a pin. One pin serves every gate inside that reads the same thing, and a constant needs no pin at all, because it is typed into the gate that uses it. So a chip costs one pin for each different thing that crosses its wall.

The wall is only visual. A chip’s body can read and change a top-level var directly, and the wire crosses the wall through a pin. Nothing about the circuit’s behavior changes when gates move into a chip.

The @left and @right pins belong to the outermost chip, the one the whole file compiles to. A chip inside it cannot have side pins:

@left in red: bool
chip {
  @right out shown = red
}

Error: [WS023] side annotations only apply to top-level ports of the compiled file

Declare the pin at the top level instead, and set it from inside the chip.

Modify

1. Add a third team, Green: one more input, one more Tally(...) call, and one more microchip when you open the chip.

2. Give Tally a second output that pulses when a team reaches 5:

   @left in red: exec
   @left in blue: exec
   @left in reset: exec
   var winner: string = "nobody yet"
   
   chip Tally(press: exec, clear: exec) -> (score: int, won: exec) {
     var n: int = 0
     on press {
       n += 1
       if n == 5 { emit won }
     }
     on clear { n = 0 }
     out score = n.Value
   }
   
   let r = Tally(red, reset)
   let b = Tally(blue, reset)
   on r.won { winner = "Red" }
   on b.won { winner = "Blue" }
   on reset { winner = "nobody yet" }
   @right out board = "Red ${r.score}  Blue ${b.score}  Winner: ${winner.Value}"
   

   won: exec is a pulse output. emit won fires it, and on r.won runs when Red’s chip fires it.

3. Chips without names. This version keeps the scores at the top level and puts each piece of work in a chip of its own:

   @left in red: exec
   @left in blue: exec
   @left in reset: exec
   var redScore: int = 0
   var blueScore: int = 0
   
   chip on red { redScore += 1 }
   chip on blue { blueScore += 1 }
   
   @closed chip ClearScores() {
     redScore = 0
     blueScore = 0
   }
   on reset { ClearScores() }
   
   chip let board = "Red ${redScore.Value}  Blue ${blueScore.Value}"
   @right out text = board
   

   • chip on red { ... } is a handler in a chip of its own.
   • chip let board = ... puts one calculation in a chip.
   • ClearScores has steps but no handler. Called inside on reset, it runs as a step of that handler, and the handler carries on after it.
   • @closed makes a chip arrive shut. Chips arrive open by default.

   Open the chip. The board chip has two pins in, one for each score, and one out. ClearScores has four: a pulse in, a pulse out, and one for each variable it sets.