Wirescript Language Reference

Wirescript is a high-level language that compiles to Brickadia wire graphs. It replaces manual gate-by-gate wiring with a readable, imperative syntax while preserving the underlying execution model of Brickadia’s wire system.

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, the open modifier, 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 ReadBrickGrid() 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 behaviour 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 wire graph gates and wires. 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.

The key mental model: 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.

Understanding this distinction is fundamental to writing correct Wirescript. See Execution Context for details.

Syntax Reference

Contents

• Source Structure
• Imports
• Comments
• Statement Terminators
• Line Continuation
• Blocks
• Identifiers
• Keywords
• Literals
• Operators
• Top-Level Declarations

Source Structure

A Wirescript file (.ws) is a sequence of top-level declarations. There is no required entry point or wrapper – declarations appear at the top level of the file.

in trigger: exec
var count: int = 0

on trigger {
  count = count + 1
}

out total = count

Imports

Import declarations bring symbols from other .ws files into scope. The .ws extension is implicit.

import "lib"                            // import all exportable declarations
import { swap, clamp } from "lib"       // selective import
import { swap as mySwap } from "lib"    // aliased import
import * as utils from "lib"            // namespace import — utils.swap()

Importable: mod, chip, fn, let, const, type, and a module’s root-level var, array, map, buffer, in and out declarations. Imported state is shared, not copied – every importer reads and writes the same storage gate, so a library module can own state that several entry files drive.

A SELECTIVE import drops the module’s handlers. import "lib" and import * as lib from "lib" both carry a module’s top-level on handlers; import { helper } from "lib" does not, because it selects declarations BY NAME and a handler has none to select. No error, no warning: the receiver gate is never emitted, so the events it would have caught go nowhere.

The trap is the edit that narrows an import. Turning import "lib" into import { helper } from "lib" to quiet an unused-name warning drops every handler that module declared, and neither just check nor just compile says so. Narrowing to import * as lib from "lib" keeps them.

The robust arrangement is to keep on handlers in the entry file regardless: expose the logic from the library as a mod, and let each entry file declare the thin handler that calls it. That way no import form can silently remove them:

// lib.ws -- the logic, reachable by importers
mod onPing(v: int) { total = total + v }

// main.ws -- the handler must be declared HERE
import { onPing } from "lib"
on CustomEvent("ping") -> (v: int) { onPing(v) }

To confirm the receivers survived, count them in the lowered graph – this is the only check that sees the problem:

just ir main.ws | grep -c WireGraphPseudo_CustomEvent

Paths are resolved relative to the importing file. Circular imports are an error.

Comments

Line Comments

Line comments start with // and extend to the end of the line.

// This is a line comment
var x: int = 0  // inline comment

Block Comments

Block comments are delimited by /* and */. They may be nested.

/* This is a block comment */

/* Block comments
   can span
   multiple lines */

/* And they /* can be */ nested */

Doc Comments

Doc comments start with /// (three slashes) and are attached to the declaration that immediately follows them. They are preserved by the compiler for documentation generation.

/// The player's current score.
/// Resets to zero each round.
var score: int = 0

Multiple consecutive doc comment lines are joined together. A single space after /// is consumed automatically.

Statement Terminators

Statements are terminated by newlines or semicolons. Both are interchangeable – you can use whichever style you prefer.

// Newline-terminated (typical style)
var x: int = 0
var y: int = 1

// Semicolon-terminated (compact style)
var x: int = 0; var y: int = 1

// Mixed
var x: int = 0; var y: int = 1
var z: int = 2

Multiple consecutive newlines and semicolons are consumed as a single statement boundary.

Line Continuation

Expressions can span multiple lines when split at an operator. The parser skips newlines when it encounters an infix operator, allowing natural line wrapping:

let total = a +
  b +
  c

let check = condition1 &&
  condition2 &&
  condition3

Newlines are also allowed inside delimited groups — call arguments ( ... ), array literals [ ... ], and record literals { ... } — after the opener, around commas, and before the closer, with an optional trailing comma:

var names: string[] = [
  "alice",
  "bob",
]

let point = {
  x: 1,
  y: 2,
}

Blocks

Blocks are enclosed in curly braces { } and contain a sequence of statements. They are used for handler bodies, chip bodies, if/else branches, and named chip declarations.

on RoundStart() {
  count = count + 1
  score = 0
}

Newlines inside blocks are consumed freely – blank lines are fine.

Identifiers

Identifiers start with a letter or underscore and continue with letters, digits, or underscores.

valid_name
_private
counter2
myVar

Identifiers are case-sensitive. count and Count are different names.

Keywords

The following words are reserved and cannot be used as identifiers:

Using a reserved word as an identifier (eg. from) as a variable or parameter name produces a cascade of confusing WSP001 expected Ident, got '<word>' (Kw) parse errors that mask the real cause.

Literals

Integer Literals

Decimal, hexadecimal, binary, and octal integer literals are supported. Underscores may be used as digit separators.

42
1_000_000
0xff          // hexadecimal
0b1010        // binary
0o77          // octal
0xFF
0B1100_0011

Float Literals

Floating-point literals use decimal notation with an optional exponent.

3.14
0.5
1e10
2.5e-3
1_000.0

A float literal requires a digit after the decimal point – 1. alone is not a float literal (it would be parsed as integer 1 followed by a dot).

String Literals

String literals are delimited by double quotes " or single quotes '.

"hello world"
'hello world'

Escape Sequences

String Interpolation

Both single- and double-quoted strings support ${expr} interpolation. Any expression can be embedded:

"Hello, ${name}!"
"Score: ${score + bonus}"
'Position: ${pos.x}, ${pos.y}'

Interpolated expressions are converted to strings. Use \$ to include a literal dollar sign.

Boolean Literals

true
false

Operators

Operators are listed here for reference. See Expressions for full details on precedence and behavior.

Arithmetic

+, -, *, /, %, ** (power)

Comparison

==, !=, <, <=, >, >=

Logical

&&, ||, !

Bitwise

&, |, ^, ~, <<, >>

String

.. (concatenation)

Other

= (assignment), -> (return type / outputs), => (fat arrow, reserved)

Top-Level Declarations

The following forms are valid at the top level of a script:

• var name: type = expr – Mutable variable
• let name = expr – Immutable binding
• buffer name = expr – Buffered value
• array name: type[] – Array
• in name: type – Input port
• out name = expr – Output port
• chip name(params) -> outputs { body } – Named chip
• chip { body } – Anonymous chip
• chip let name = expr – Anonymous chip with let bindings
• chip on trigger { body } – Anonymous chip with handler
• mod name(params) { body } – Inline chip (macro-like)
• on trigger { body } – Event handler
• let name = on trigger { body } – Captured event with handler
• import "path" – Import all declarations from file
• import { names } from "path" – Selective import
• import * as ns from "path" – Namespace import
• if cond { body } – Conditional (in exec context)
• return – Early return from handler
• target = expr – Assignment (in exec context)
• expr – Expression statement

Types

Wirescript has a static type system that maps directly to Brickadia’s wire graph port types. The type checker validates that wires connect compatible ports and inserts coercion gates where needed.

Contents

• Primitive Types
• Compound Types
• Generics
• Type Annotations
• Field Access on Types

Primitive Types

exec Type

The exec type represents an execution trigger signal. It is not a data value – it represents “this event fired” or “this code path should execute.” Inputs of type exec are used as handler triggers:

in reset: exec

on reset {
  count = 0
}

Special Types

any Type

any is a wildcard annotation for a value that flows through a wire without the checker pinning down (or caring about) its concrete type: test & 1, test == "x", and every other operator overload still resolve against whatever operand type is on the other side, instead of erroring the way an actually-unknown type would. The tradeoff is spelled out by the name – an any value works anywhere, but its side effects are on you: the checker can’t warn you if the operator that ends up selected wasn’t the one you meant.

For a mod parameter that just passes a value through, prefer a generic type parameter (<T>) over any – it keeps the checker’s help instead of erasing the type. See any vs. a Generic Parameter.

any is valid wherever a value just passes through:

in test: any             // input port
let value = test & 1     // let binding
mod f(v: any) { ... }    // mod parameter
chip C(v: any) -> (r: any) { out r = v }  // chip parameter / output

It is not valid as a variable gate’s storage type, because a Variable gate needs one concrete wire variant to hold – any has none:

var foo: any = 0          // ERROR: 'any' cannot be stored
static var foo: any = 0   // ERROR: same
var foo: any[]          // ERROR: same
buffer foo: any = 0       // ERROR: same

An unannotated var or buffer is unaffected – its placeholder type is refined from the initializer (or left as the internal “unknown” fallback), never any, so it never trips this rejection.

Object references & assets

entity, character, controller are all object references – a wire carries a handle to a game object, not a copy of it. Asset references ($AssetType/AssetName, e.g. $BrickAudioDescriptor/BA_MUS_…) are object references too: each lowers to its own reference gate (an AudioReference brick, and so on) whose output is wired wherever you use it.

Because they share the same underlying object wire variant, an entity[] array (or an object-typed var) can hold any of them – including asset references:

var songs: entity[]

on load {
  songs.push($BrickAudioDescriptor/BA_MUS_Component_Basil_CoffeeShop)
}

References can’t be inlined into an initializer. A constant var initializer (= [...]) only bakes value literals (int / float / bool / string / vector / …) into the gate. An object reference must be wired in from its own brick, so it can’t sit in a constant initializer – build the array with .push(...) inside an exec handler instead. Writing var songs: entity[] = [$Asset/…] silently drops the elements, and the compiler warns (WS024).

zone & teleport references

These are reference-only types, exactly like a variable ref (ref T): a wire carries a handle to a component, not a value. They can be passed as in ports, mod/chip parameters, and rerouted anywhere – but, like a var ref, they can not be:

• stored in a var / buffer (WS025) – a storage gate needs a concrete wire variant;
• selected with an if-then-else (WS031) – the Select gate routes a value, not a reference;
• operated on (arithmetic, comparison, string-format).

in z: zone
in e: entity
in p: teleport

on ZoneEntered(zone = z) -> (character) {   // wire the zone into the event
  e.Teleport(p)                         // teleport `e` to the teleport point `p`
}

To teleport an entity to a raw position (a vector), use SetLocation – the Teleport gates require a teleport point, not a coordinate.

The null literal

null is a polymorphic literal that adopts its target type and produces that type’s zero value: an unset object for entity/character/controller, 0 for a number, false for bool, "" for string, the zero vector / rotation / color. It needs a known target type – a var/out annotation, an assignment, a call argument, or a record field:

var target: entity = null      // an unset object reference
var score: int = null          // 0
in go: exec
on go { target = null }        // clear the reference

type Slot = { owner: entity, count: int }
var slot: Slot = { owner: null, count: null }

null is only valid for a value type. A container, record, or reference-only type (int[], Map<K, V>, a record, *T, zone) has no null value and reports WS051 – use its own empty form ([], {}) instead. A bare let x = null with no target types as any.

Compound Types

Reference Types (ref T)

A ref T is a reference to a mutable variable of type T. Variables declared with var have type ref T internally – this is how the wire graph tracks that they are mutable storage rather than pure signal values.

var count: int = 0  // count has type ref int internally

You can write ref T explicitly in type annotations, particularly for chip parameters that need to mutate a caller’s variable:

chip Counter(n: ref int, step: int) {
  on trigger {
    n = n + step
  }
}

The * prefix is an alternative syntax for ref:

// These are equivalent:
mod slide(a: ref int, b: ref int) { ... }
mod slide(a: *int, b: *int) { ... }

Ref<V> is an alias spelling of *V / ref V (Ref<int> == *int == ref int).

A ref to a record, tuple, or enum refs its parts

A record has no single wire to point at: stored, it becomes one backing gate per field. So *T on a record distributes over the fields – *{ a: float, b: float } means { a: *float, b: *float }. This is what lets a chip or mod write through to the caller’s record:

type Player = { score: int, lives: int }

chip AwardPoint(p: *Player) {
  on trigger {
    p.score = p.score + 1
  }
}

The caller passes the record variable itself, and each field is wired as its own reference, so the write lands on the caller’s storage.

Tuples and enums work the same way, because they are stored the same way: *(A, B) refs each element, and *SomeEnum refs the enum’s discriminant and payload slots, so a chip can reassign the caller’s enum outright.

A field that is already a reference stays as it is rather than becoming a double reference. Note that a record whose fields are references still cannot be stored in a variable, array, or map (WS049): storage needs a real value per field.

Array Types (T[])

Arrays hold multiple values of the same element type. Declare them with a var whose type ends in []:

var scores: int[]

Array<V> is an alias spelling of V[] (Array<int> == int[]).

Array access uses bracket syntax and returns the element type directly:

let result = scores[i]  // result: int
if result > 100 { }     // works directly, no .value needed

Assignment also works directly: scores[i] = 42.

Map Types (Map<K, V>)

A Map<K, V> is a keyed collection, backed by a MapVar gate. Like an array, it is stored in a var and starts empty — build it at runtime from an exec handler:

var scores: Map<string, int>

The key type K must be int, string, or an object reference (entity / character / controller) — a map is keyed by a hashed slot, and only those types have a slot representation. Any other key type is a WS039 error. The value type V may be any storable variant.

Maps are read and written through their methods (get, set, has, remove, clear, copyFrom, length, keys, values), which run in exec context — see the map-method table in builtins.md and the Maps statement section.

Tuple Types ((A, B, C))

Tuples are fixed-size ordered collections of potentially different types:

// A chip returning multiple outputs produces a record/tuple
chip Split(v: vector) -> (x: float, y: float, z: float) {
  out x = v.x
  out y = v.y
  out z = v.z
}

Access tuple elements with .0, .1, .2 etc:

let pair = someTuple
let first = pair.0
let second = pair.1

Record Types

Record types are named structural types with labeled fields. Define them with the type keyword:

type Point = { x: int, y: int }
type State = { counter: *int, label: string }

A record value – a let binding, a record literal, a chip’s multi-output result – is a compile-time abstraction: it generates no gates, and each field resolves directly to its underlying binding (variable reference, local value, array, etc.). A record used as storage (a var, array, or map) is the exception – see Records as storage below.

Interior mutability with *T fields: A record field of type *int (or ref int) holds a reference to a mutable variable. Writing through the field mutates the original variable:

type State = { val: *int }
var n: int = 0
let s: State = { val: n }
on RoundStart() { s.val = 42 }  // writes to n

Nested records work as expected – field access chains resolve through each level:

type Inner = { x: *int }
type Outer = { inner: Inner }
var x: int = 0
let i: Inner = { x }
let o: Outer = { inner: i }
on RoundStart() { o.inner.x = 42 }  // writes to x

Records as storage

A record can back a var, an array, or a map. It decomposes into one storage gate per field (recursing through nested records), and every operation fans out across those per-field gates. This is what lets a record be mutated, indexed, and kept across ticks – a plain record value cannot.

type Point = { x: int, y: int }

on RoundStart() {
  // A record VARIABLE: one Variable gate per field.
  var p: Point = { x: 1, y: 2 }
  p.x = 10                  // writes the x gate only, y untouched
  p = { x: 7, y: 8 }        // whole-record assignment writes every field

  var q: Point = { x: 0, y: 0 }
  q = p                     // copies each field into q's own gates, not an alias
  p.x = 99                  // ...so this does not change q.x

  // A record ARRAY: parallel arrays, one per field.
  var pts: Point[]
  pts.push({ x: 3, y: 4 })  // pushes x into pts' x-array, y into its y-array
  let first = pts[0].x      // reads the x-array at index 0
  pts[0] = { x: 9, y: 9 }   // writes every field's array at index 0
  let n = pts.length()      // the fields share a length; length reads the first

  // A record MAP: parallel maps, one per field (same key type).
  var m: Map<int, Point>
  m.set(0, { x: 5, y: 6 })
  let v = m.get(0).x        // reads the x-map at key 0
}

A constant initializer bakes per field, so a record array or map can be constructed up front:

type Point = { x: int, y: int }
var pts: Point[] = [{ x: 1, y: 2 }, { x: 3, y: 4 }]   // x-array [1,3], y-array [2,4]
var grid: Map<int, Point> = { 0 => { x: 5, y: 6 } }   // x-map {0:5}, y-map {0:6}

Struct-of-arrays access. Because a record array is stored as one array per field, that field’s array is directly reachable as pts.field – a real T[] you can index (pts.x[i]), read (pts.x.length(), pts.x.sum(), pts.x.min(), pts.x.find(v)), or pass on. Sorting is special-cased so it stays safe: pts.field.sort(descending?) sorts the WHOLE record BY that field, reordering every sibling column to match, so rows stay intact (wide records sort in groups against a copy of the key, so there is no field-count limit). Everything else on a column acts on that column alone, which is powerful but sharp: mutating one field’s array by itself (pts.x.push(1) without a matching pts.y.push(...)) breaks the row correspondence the whole-array ops rely on. Prefer the whole-record ops (push/pop/pts[i]) unless you specifically want a single column.

Choosing between two records. A record has no single wire, so an if expression or a match expression over records makes the choice per leaf field: one Select per leaf, all reading the one lowered condition (or, for a match, the one __disc read). It reads like an ordinary conditional value:

type Point = { x: int, y: int }
enum Pick { First, Second }

var a: Point = { x: 1, y: 2 }
var b: Point = { x: 3, y: 4 }
var chosen: Point = { x: 0, y: 0 }
var which: Pick = Pick.First
in go: exec

on go {
  chosen = if which is Pick.First then a else b   // 2 Selects, one per field
  chosen = match which { First => a, Second => b }
  let alias = match which { First => a, Second => b }
  chosen.x = alias.y
}

The same holds for an enum value, whose leaves are its discriminant and payload slots, so match outer { A => Shape.Circle(r), B => Shape.Empty } chooses the tag and each slot alongside it.

An arm that is itself a call splits the same way. A record-returning mod contributes its record’s fields, and a multi-output gate contributes one leaf per output port – so let c = if hit then m.get(a) else m.get(b) gives c a real Value and a real Found, each chosen by its own Select.

Which fields are allowed. Every leaf field must be a value the wire graph can store – a number, bool, string, vector/rotator/color, an entity type, or a nested record/array/map. A reference-only field (*T, zone, teleport, a prefab reference) or an exec field cannot be stored, and a record with one is rejected with WS049. (A record value may still carry a *T field for interior mutability, as above; only storage is restricted.)

Container operations. A record array supports push, pop, insert, remove, fill, resize, swap, reverse, clear, length, and element access (pts[i], pts[i].field, pts[i] = rec, p = pts[i]). A nested-record field is reachable to any depth, since the storage decomposes to leaf columns: pts[i].inner.a reads or writes one leaf, and pts[i].inner reads or writes the whole sub-record at that index. Operations that reorder elements by value (sort, shuffle), fold over whole records (sum/min/max/average), or need a matching second container (append/copyFrom/slice) have no per-field meaning and are rejected with WS050 – index a scalar field instead. A record map supports set, get, has, remove, clear, length, keys, and m[k] access, with the same depth of nested-field access (m[k].inner.a, m[k].inner). A map key cannot be a record (WS039); keys must be a single wire value.

Tuple Types ((A, B, C))

Tuples are fixed-size ordered collections of potentially different types:

// A chip returning multiple outputs produces a record/tuple
chip Split(v: vector) -> (x: float, y: float, z: float) {
  out x = v.x
  out y = v.y
  out z = v.z
}

Access tuple elements with .0, .1, .2 etc:

let pair = someTuple
let first = pair.0
let second = pair.1

Both Type::Record and Type::Tuple exist in the type system. Records use named fields ({ x: int, y: int }), while tuples use positional access ((int, float)).

Union Types (A | B)

Union types represent a value that can be one of several types. Write one directly in a type annotation:

let x: int | float = 42

Union syntax is also how a generic bound names an ad hoc set of types (<T: int | vector>).

Note that an if-then-else expression does not produce a union of its branch types – it widens them to a single common type instead (see Widening Inference and the if-expression note). if condition then 42 else 3.14 has type float, not int | float.

Enum Types

An enum is a nominal type with a fixed set of named variants – unlike Type::Union above (which is structural: any value of a matching type qualifies), two enums stay distinct types even if their variants look the same. A variant can be a bare unit or carry a payload, which makes enum how Wirescript expresses a tagged union:

enum Shape { Empty, Circle(float), Rect(float, float) }

An enum value is represented at compile time as a record: a hidden discriminant field plus one slot per payload field, so it follows the same Records as storage rules when it backs a var. match, if let, and let ... else are how you branch on a value’s variant and pull its payload back out. See Enums for the full reference: declaration, construction, .Discriminant, match, if let / let else, generic enums, and the built-in Option/Result.

Generics

mod and chip declarations can take type parameters – one implementation that specializes per call site instead of one copy per concrete type. A generic mod inlines and monomorphizes at each call: the compiler infers the concrete type(s) from the arguments and emits concrete gates for that type, same as a hand-written non-generic mod would.

Generic chips work too: a generic chip is monomorphized per distinct type instantiation into its own microchip template (Box<int> and Box<vector> become two separate grids; two Box<int> calls share one), so the wire-level behavior mirrors a hand-written non-generic chip at each type.

mod pick<T>(c: bool, a: T, b: T) -> T {
  return if c then a else b
}

in go: exec
in i: int
on go {
  let x = pick(true, i, i)   // T = int, inferred from the arguments
}

Multiple type parameters are declared as <T, U, ...>, each inferred independently from its own arguments:

mod first<T, U>(a: T, b: U) -> T {
  return a
}

See examples/generics.ws for a complete, just check-clean file exercising every form on this page.

Constraint Classes (Bounds)

A type parameter can be bounded to a named class of types with <T: Class>. There are three built-in classes, and unbounded <T> means <T: Variant>:

Scalar ⊆ Numeric ⊆ Variant. Note bool is only a member of Variant – Scalar and Numeric are strictly numeric-math types, and a bounded call with a bool argument is rejected:

mod addOne<T: Scalar>(v: T) -> T {
  return v + 1
}

in flag: bool
let bad = addOne(flag)   // ERROR WS033: 'T' = bool, which isn't allowed by its bound

An anonymous union bound (<T: A | B>) restricts T to exactly that set of types instead of a named class:

mod pickAxis<T: int | vector>(v: T) -> T {
  return v
}

Widening Inference

T is inferred as the join (least upper bound) of all the arguments’ types, over a widening-only lattice – there’s no narrowing:

• Numeric types widen toward the wider type: int widens to float, so pick(flag, 1, 2.0) infers T = float (the int argument casts up).
• Object types widen toward entity: character and controller both widen to entity, so pick(flag, aCharacter, aController) infers T = entity.
• Incompatible operands – e.g. int and vector – have no common widening and are a compile error (WS033):

in n: int
in v: vector
let bad = pick(true, n, v)
// ERROR WS033: cannot infer 'T': it's int from one argument but vector
// from another -- all 'T' arguments must be the same type

The same join is used by the built-in blend-family gates (Blend, lerp, Easing) and by if-then-else expressions – see the widening note there.

Body Checking Is Per-Mask-Member

A generic mod’s body is type-checked against every type in its bound’s mask – not just the types it happens to be called with – so the body must be valid for the whole bound, not only your call sites. This is the most common gotcha: <T: Numeric> includes rotator, and an operator that isn’t defined between rotator and a bare int literal fails the definition itself, even if you never call the mod with a rotator:

mod addOne<T: Numeric>(v: T) -> T {
  return v + 1
}
// ERROR WS004: no overload for '+' on Rotator, Int -- rejected at the
// DEFINITION, because `Numeric` includes `rotator` and `rotator + int`
// has no overload, even though every actual call site below uses `int`.

Narrow the bound to Scalar when the body only needs int/float semantics – v + 1 is valid for every Scalar member, so this is clean:

mod addOne<T: Scalar>(v: T) -> T {
  return v + 1     // OK -- valid for both int and float
}

An operation that genuinely is valid across the whole Numeric family (a same-type operator, for instance) is fine to write against Numeric directly:

mod square<T: Numeric>(v: T) -> T {
  return v * v     // OK -- same-type multiply is defined for the whole family
}

Ref Parameters

A *T (or ref T) parameter infers T through the reference:

mod swap<T>(a: *T, b: *T) {
  let tmp = a
  a = b
  b = tmp
}

The same per-mask-member body checking applies – a ref-param body that only assigns is fine unbounded (valid for every Variant member), but one that does arithmetic on the referenced value needs a Scalar bound for the same reason addOne does above:

mod inc<T: Scalar>(v: *T) {
  v = v + 1
}

any vs. a Generic Parameter

any erases the type entirely – the checker can’t validate operators against it and can’t tell you when you’ve made a mistake. A generic parameter keeps the type information and validates the body against the bound, so prefer a generic mod (<T> or <T: Bound>) over any for a value that flows through unchanged. Reach for any only when you genuinely don’t care what flows through and don’t need the checker’s help.

Generic type aliases

A type alias can take type parameters and is instantiated by substitution:

type Pair<T> = { a: T, b: T }
let p: Pair<int> = { a: 1, b: 2 }   // resolves to { a: int, b: int }

An alias must be fully applied (Pair alone, or Pair<int, float> on a one-parameter alias, is a WS002 error) and non-recursive (type L<T> = { tail: L<T> } is rejected, not hung).

Explicit type arguments

T is normally inferred from the arguments, but you can pin it explicitly with a <...> type-argument list at the call site:

let x = pick<int>(flag, a, b)   // same as the inferred pick(flag, a, b)
let z = zero<vector>()          // REQUIRED: T appears only in the return

Explicit type arguments are the only way to call a mod whose type parameter can’t be inferred from its arguments – e.g. a T that appears only in the return type (mod zero<T>() -> T). They are checked like inferred ones: the count must match the type parameters, and each must satisfy its bound (zero<string>() on a <T: Numeric> is a WS033 error); type arguments on a non-generic function are an error too, and on a builtin they are ignored with a WS037 warning (a builtin’s result type is derived from its arguments).

Parsing note: f<int>(...) is read as a type-argument list only when the <...> is a valid list of types immediately followed by ( – a plain a < b comparison (or a < b > c) is never mistaken for it.

Wirescript automatically inserts coercion gates when types don’t match exactly but are compatible. The coercion rules mirror Brickadia’s PortsAreCompatible behavior.

Numeric Coercion (Bidirectional)

All numeric types (bool, int, float) coerce to each other freely:

var x: float = 1      // int -> float: OK
var y: int = true      // bool -> int: OK (true=1, false=0)
var z: float = false   // bool -> float: OK

Because bool coerces to int automatically, you do not need if x then 1 else 0 – just use the bool directly where an int is expected. The if/then/else form is only needed when you want specific non-0/1 scalar values:

let count = a + b + c            // bools coerce to 0/1 automatically
let weight = if heavy then 10 else 1  // need if/then for non-0/1 values

Rotation Coercion (Bidirectional)

Both carry their components as float fields — .pitch .yaw .roll on a rotator, .x .y .z .w on a quat — read through the split gates described in Field Access.

A rotator (euler) and a quat (quaternion) are interchangeable rotation values at the wire level, so they coerce to each other freely. This is how a rotation converts to a quaternion: feed an entity’s GetRotation() rotator straight into a quaternion gate, or call quaternion methods on a Rotation(...) result.

let r = Rotation(0.0, 90.0, 0.0)   // rotator (Make Rotation from euler degrees)
let back = r.Invert()              // rotator coerces to quat for the gate → quat
let spun = aim.Rotate(r.Invert())  // rotate a vector by the inverse rotation

String Coercion (One-Way)

All primitive types can be coerced to string via an implicit format gate:

var label: string = 42         // int -> string: "42"
var pos: string = someVector   // vector -> string: formatted

The following types format to string: bool, int, float, string, vector, rotator, color, entity, character, controller.

String Coercion to Bool – empty is false

A string coerces to bool wherever a bool is expected – a condition, a bool-typed let/var, a bool-typed port or chip/mod param. The semantics are exactly s != "", and the compiler inserts a real CompareNotEqual(s, "") gate at every such coercion point:

in name: string

if name {
  // taken whenever `name` is non-empty — compiles as `if name != ""`
}

let hasName: bool = name   // also `name != ""`

String literals in bool positions (var v: bool = "0", array flags: bool[] = ["x", ""], Select("0", a, b)) are converted at compile time by the same != "" law – the baked value is already a bool, so "0" bakes as true.

The rule is deliberately simple: only the empty string is false. This differs from the game’s native bool-port behavior, which is content-aware – a string wired manually into a bool port (e.g. via an any-typed value, whose erased type skips the coercion, or through the logical operators’ native string overloads) is read by the gate itself, where "", "0", and "false" are all falsy. That native law is certified per build against the in-game gate-semantics table – the same certification that drives constant folding of conditions, see folding.md. If you want the content-aware behavior, wire it manually; if you write if someString, you get the deterministic != "".

This direction is one-way – bool to string still goes through the format gate above and renders "true"/"false" text, not the other way around.

Pulsing Coercion to Exec

Value types that “pulse” (change over time) can trigger exec inputs. This means bool, int, float, vector, entity, character, and controller values can be connected to exec inputs – the exec fires whenever the value changes:

// A bool value can trigger a handler
chip let moved = position != position.prev

on moved {
  // Fires whenever 'moved' transitions
}

Reference Invariance

Reference types (ref T) do not coerce. A ref int cannot be passed where a ref float is expected, even though int and float coerce freely. This prevents accidentally wiring incompatible variable storage:

var x: int = 0
var y: float = 0.0

// This would be an error -- ref int != ref float
// someChip(x, y)  // if both params expect ref int

Coercion Summary Table

Type Annotations

Type annotations appear after a colon in declarations:

var x: int = 0
in trigger: exec
var data: float[]

Type annotations are optional on var when an initializer is present (the type is inferred), but they are required on in declarations, and on an array or map var that has no initializer to infer its element/key-value types from.

Field Access on Types

Certain types have built-in fields accessible with dot notation:

Vector Fields

let v = Vec(1.0, 2.0, 3.0)
v.x   // or v.X -> float
v.y   // or v.Y -> float
v.z   // or v.Z -> float

Color Fields

let c = Color(1.0, 0.5, 0.0, 1.0)
c.r   // or c.R -> float
c.g   // or c.G -> float
c.b   // or c.B -> float
c.a   // or c.A -> float

Rotator Fields

let r = someRotator
r.pitch  // -> float
r.yaw    // -> float
r.roll   // -> float

Variable Fields

Variables (type ref T) have special fields:

var count: int = 0

count.Value  // Current value (type T) -- delayed read, usable in pure context
count.prev   // Previous tick's value (type T) -- useful for change detection

See Execution Context for when to use .Value vs direct access.

Enums

An enum is a named type with a fixed set of variants. Each variant can be a bare unit (like a C enum member), or it can carry a payload – turning the type into a tagged union. A value of an enum type always knows which variant it currently is; match, if let, and let ... else are how you branch on that and pull the payload back out.

Unlike type aliases, which are structural, enum is nominal: two enums with identically-shaped variants are still different types.

Contents

• Declaration
• Construction
• .Discriminant
• is
• Enum and int conversion
• match
• if let / let else
• Changing a payload
• Payloads cannot hold containers
• unsafe: unchecked payload access
• Generic enums
• Built-in Option and Result
• Built-in game enums

Declaration

Discriminants (the integer tag backing each variant) auto-number from 0. An explicit = N resets the counter – the next unannotated variant continues from N + 1. Two variants that resolve to the same value are a WS064 error.

enum Color { Red, Green, Blue }              // 0, 1, 2
enum Status { Idle = 0, Running = 5, Done }  // 0, 5, 6

enum Shape {
  Empty,                          // unit variant
  Circle(float),                  // positional payload
  Rect(float, float),
  Box { w: float, h: float },     // named payload
}

A single enum can freely mix unit, positional, and named variants. Whichever shape a variant is declared with is the shape it must be constructed and matched with – see Construction below.

Construction

Construct a variant with its qualified Enum.Variant path: a unit variant is the bare path, a positional-payload variant takes (...), and a named-payload variant takes { ... } (the shorthand { x, y } works in a value position too, same as a record literal):

enum Shape { Empty, Circle(float), Box { w: float, h: float } }

let c = Shape.Empty
let s = Shape.Circle(5.0)
let b = Shape.Box { w: 1.0, h: 2.0 }

Using the wrong bracket form for a variant’s declared shape – Shape.Circle { } for a positional variant, or Shape.Box(1.0, 2.0) for a named one – is a WS065 error, so a variant’s shape stays unambiguous for exhaustiveness checking and the LSP’s fill action.

The prelude variants

Some, None, Ok, and Err (the built-in Option/Result variants) are available bare – no Option. / Result. qualifier needed:

let o = Some(42)                     // T inferred = int
let n: Option<int> = None            // annotation fixes T when payload can't

None and Err carry no payload to infer their type parameters from, so a bare let n = None has nothing to pin T. Give the binding a type annotation (let n: Option<int> = None) or that’s a WS063 error.

.Discriminant

.Discriminant yields the variant’s tag as an int. On a variant path (Enum.Variant.Discriminant) it’s a compile-time constant that costs no gates; on a value it reads the tag currently stored in that value:

enum Shape { Empty, Circle(float), Rect(float, float) }

out d = Shape.Circle.Discriminant             // compile-time int, = 1

enum Shape { Empty, Circle(float), Rect(float, float) }

static var s: Shape = Shape.Circle(5.0)
out matches = s.Discriminant == Shape.Rect.Discriminant   // runtime read vs const

.Discriminant (and match) on a value that isn’t an enum is a WS066 error.

is

value is Enum.Variant asks whether the value currently holds that variant and yields a bool. It is the discriminant comparison above, spelled the way it reads:

enum Shape { Empty, Circle(float), Rect(float, float) }

static var s: Shape = Shape.Circle(5.0)
in ready: bool

out round = s is Shape.Circle                  // same gates as the compare above
out other = !(s is Shape.Circle)               // negate with `!`
out go = s is Shape.Rect && ready              // binds like `==`

The test compares tags, so a payload variant answers on its tag alone and binds nothing; match and if let are how a payload comes back out. The right side must name a variant of the same enum: s is v (two values) and s is Other.Empty (a different enum) are errors.

A test whose two sides are both compile-time constants folds away, so testing a const value costs no gates.

Enum and int conversion

Two spellings move between an enum value and its integer tag.

value.ToInt() is an exact alias for .Discriminant: it yields the tag as an int, on both a value and a variant path, and folds to the same compile-time constant when the receiver is a variant path.

Enum.FromInt(n) goes the other way. It builds a value of Enum whose tag is the int n, with every payload slot defaulted to its zero value. Here n may be a runtime int, not just a constant. It sets only the tag, so it is meaningful mainly for unit-only enums (C-like enums and the built-in game enums). For a payload-carrying variant the payload reads back as zero. An n that matches no variant’s discriminant leaves a value that no match arm covers except a wildcard _.

enum Shape { Empty, Circle(float), Rect(float, float) }

in tag: int

static var s: Shape = Shape.Rect(1.0, 2.0)

// ToInt is Discriminant by another name.
out same = s.ToInt() == s.Discriminant        // always true
out circle = Shape.Circle.ToInt()             // compile-time int, = 1

// FromInt rebuilds a value from a (possibly runtime) tag.
let rebuilt = Shape.FromInt(tag)
out kind = match rebuilt {
  Empty => 0,
  Circle(r) => 1,
  Rect(w, h) => 2,
}

EnumToInt(value) and IntToEnum(value, wrap?) are the gate-backed twins of .ToInt() and Enum.FromInt(n), for routing through the game’s “Enum to Integer” / “Integer to Enum” gates.

EnumToInt(value) requires an enum argument (an int or any non-enum is a type error) and yields an int. When value is a compile-time-known enum (a variant literal, or a const value) it folds to the discriminant literal and emits no gate; a runtime enum value instead routes through the real EnumToInt gate, fed by the value’s tag. For Wirescript’s record enums the runtime gate is just reading the tag, but it is emitted so game/native enums go through the real gate.

IntToEnum(value) is the reverse. Its result is an enum whose concrete type comes from the use site (the annotated target or output type), exactly like FromInt and null; with no enum-typed context it can’t tell which enum the integer names, which is an error. A constant value folds to the enum record directly; a runtime value routes through the real IntToEnum gate. The optional wrap clamps an out-of-range tag into range.

enum Shape { Empty, Circle(float), Rect(float, float) }

in tag: int
static var s: Shape = Shape.Rect(1.0, 2.0)

// EnumToInt is the gate-backed twin of ToInt / Discriminant.
out folded = EnumToInt(Shape.Circle(1.0)) // compile-time: folds to 1, no gate
out live = EnumToInt(s)                    // runtime: routes through the gate

// IntToEnum is the gate-backed twin of FromInt; the result's enum type
// comes from the annotated target.
let back: Shape = IntToEnum(tag)           // runtime int -> Shape via the gate
out kind = match back {
  Empty => 0,
  Circle(r) => 1,
  Rect(w, h) => 2,
}

match

match branches on an enum value’s variant, binding any payload as it goes. It works both as an expression (arms are values, comma-separated, and it compiles to a Select tree) and as a statement (arms are blocks, and it compiles to a Branch/Union tree). Arm patterns use bare variant names – the scrutinee’s enum type is already known, so there’s no Enum. qualifier.

Expression form

enum Shape { Empty, Circle(float), Rect(float, float), Box { w: float, h: float } }

static var s: Shape = Shape.Circle(5.0)

out area = match s {
  Circle(r)    => 3.14159 * r * r,
  Rect(w, h)   => w * h,
  Box { w, h } => w * h,
  Empty        => 0.0,
}

The arms’ result types follow the same widening join as an if-then-else expression.

Statement form

Statement arms are blocks (no commas between them) and require exec context:

enum Shape { Empty, Circle(float) }

static var s: Shape = Shape.Circle(5.0)
var lastArea: float = 0.0

on ReadBrickGrid() {
  match s {
    Circle(r) => { lastArea = r * r }
    Empty     => { lastArea = 0.0 }
  }
}

Exhaustiveness

A match must cover every variant of the scrutinee’s enum, or be capped with a _ wildcard arm. An uncovered variant is a WS054 error that names the missing pattern(s) in its message; an arm that can never run because an earlier arm already covers everything it would match is a WS061 warning.

enum Shape { Empty, Circle(float), Rect(float, float) }

static var s: Shape = Shape.Circle(5.0)

out area = match s {
  Circle(r) => 3.14159 * r * r,
  _         => 0.0,
}

Nested patterns

A pattern can nest into a variant’s payload, including into another enum, and exhaustiveness checking follows it down:

enum Opt { Some(int), None }
enum Tree { Leaf(int), Node(Opt) }

static var t: Tree = Tree.Leaf(0)

out val = match t {
  Node(Some(x)) => x,
  Node(None)    => 0,
  Leaf(n)       => n,
}

A named-payload pattern can ignore the fields it doesn’t need with ..: Box { w, .. } binds only w and drops h.

Scrutinee must be a value, not a port

The scrutinee of a match (and of if let / let else, below) has to be a var, let, static var, mod/chip parameter, or const – something the compiler can see as a compile-time record of the tag plus its payload slots. A top-level enum-typed in input port does not decompose that way (it lowers to a single scalar wire, not a record), so matching on one directly emits an unwired placeholder instead of a real Select/Branch tree. If an enum value needs to arrive from outside the unit, copy it into a var first and match on that:

enum Shape { Empty, Circle(float), Rect(float, float) }

var s: Shape = Shape.Empty
in setCircle: exec
in radius: float

on setCircle {
  s = Shape.Circle(radius)
}

out area = match s {
  Circle(r)  => r * r,
  Rect(w, h) => w * h,
  Empty      => 0.0,
}

(The same gap applies in the other direction: an enum value can’t yet drive a top-level out port directly either – expose a derived scalar, such as .Discriminant or a match result, instead.)

A let that ALIASES an enum in storage decomposes too, so an array element, a map value, and a record field all match directly (match arr[i] { .. }, or let e = h.shape first). The one spelling that does not is m.get(k): that method returns a {Value, Found} result record rather than the value, which is the WS066 “requires an enum scrutinee” error naming that shape. Subscript it (m[k]) or read the member (m.get(k).Value).

if let / let else

These are single-variant refutable binds – shorthand for a match with one real arm.

if let PATTERN = scrutinee { ... } runs the then block (with the pattern’s bindings in scope) only when the scrutinee is that variant; the else is optional:

enum Opt { Some(int), None }

static var o: Opt = Opt.Some(5)
var result: int = 0

on ReadBrickGrid() {
  if let Some(x) = o {
    result = x
  } else {
    result = -1
  }
}

let PATTERN = scrutinee else { ... } binds into the surrounding scope instead of a nested block, which is why its else is required to diverge – it must end in return / emit, or be an if/match whose arms all diverge. That’s what guarantees the binding is always available after the statement. A non-diverging else is a WS062 error.

enum Opt { Some(int), None }

mod unwrapOr(v: Opt, fallback: int) -> int {
  let Some(x) = v else { return fallback }
  return x
}

static var o: Opt = Opt.Some(5)
var result: int = 0

on ReadBrickGrid() {
  result = unwrapOr(o, -1)
}

Changing a payload

A payload field has no direct write. s.field = v on an enum value is a WS007 error, because an enum value is stored as its tag plus one slot per variant field, and the surface field name names no slot.

There are two ways to change one, and which you want depends on whether the value is already the variant you are writing.

Destructure and assign the capture. A match arm, an if let, or a let ... else binds each capture directly to the matched value’s payload slot, so writing the capture writes the payload in place. The other fields, and the tag, are left alone:

type Track = { origin: vector, direction: vector }

enum Nav {
  Idle,
  Moving { track: Track, label: string, active: bool },
}

var nav: Nav = Nav.Moving {
  track: { origin: Vec(4.0, 4.0, 4.0), direction: Vec(0.707, 0.707, 0.0) },
  label: "start",
  active: false,
}

in go: exec

on go {
  if let Moving { track, label, active } = nav {
    track = { origin: Vec(69.0, 69.0, 69.0), direction: Vec(1.0, 0.0, 0.0) }
    label = "moved"
    active = true
  }
}

The write costs one Var_Set per scalar field, and one per leaf for a record-typed field, so track above costs two, one for origin and one for direction. That is the same price as writing a record var. Because the assignment sits inside the arm, it only runs when the value really is that variant, which is what makes an in-place payload write safe.

The scrutinee has to be writable storage for this: a var, a static var, a *T parameter, or a var-backed record field. Captures off a let, a const, or a by-value parameter stay read-only, since there is no storage gate behind their slots for a write to land on.

A container element is not storage. arr[i], m[k], and any field reached through one (hs[0].e) read the element out by value, so a capture off them is read-only too and writing it is a WS007 error. To change an element’s payload, copy it into a var, mutate that, and store it back:

enum Slot { Empty, Full { label: string, ready: bool } }

var slots: Slot[]
var cur: Slot = Slot.Empty
in go3: exec

on go3 {
  slots.push(Slot.Full { label: "start", ready: false })
  cur = slots[0]
  if let Full { label, ready } = cur {
    label = "moved"
    ready = true
  }
  slots[0] = cur
}

Rebuild the whole variant. Assigning the enum itself sets the tag and every slot of the new variant at once, and is the only option when the value is changing variant:

enum Nav2 { Idle, Moving { label: string, active: bool } }

var nav2: Nav2 = Nav2.Idle
in go2: exec

on go2 {
  nav2 = Nav2.Moving { label: "moved", active: true }
}

Reading works the same way round: pull a payload field out through a match or if let capture, not through value.field.

Payloads cannot hold containers

A payload field cannot be an array or a map, and neither can a record used as one. The declaration is a WS069 error:

enum Loadout {
  Empty,
  Carrying { items: int[] },   // WS069
}

A payload slot is a single storage gate, and it is filled by constructing the variant. There is no way to construct a container into one: a declaration initializer bakes an initial value, and an array has none, while a runtime Loadout.Carrying { items: [1, 2, 3] } has no gate that assigns a whole array. The slot would still be allocated, so a captured items.push(...) compiled to a real gate writing storage that nothing ever filled, and the value read back empty. Rejecting the declaration stops that at the source.

The same applies to a generic enum instantiated with a container, when the parameter is one a variant actually stores, so Option<int[]> is a WS069 at the annotation. A parameter no variant stores is unaffected.

Keep the container in its own var and put something scalar in the payload that refers to it, such as an index, a key, or a length:

var items: int[]

enum Loadout {
  Empty,
  Carrying { first: int, count: int },
}

var loadout: Loadout = Loadout.Empty
in pickUp: exec

on pickUp {
  items.push(7)
  loadout = Loadout.Carrying { first: 0, count: items.length() }
}

unsafe: unchecked payload access

unsafe <value>.<Variant>.<field> reads or writes one payload slot without proving the value is that variant. It costs no gate: the access resolves straight to the slot.

enum Job { Idle, Running { label: string, ticks: int } }

var job: Job = Job.Running { label: "start", ticks: 0 }
var seen: string = ""
in tick: exec

on tick {
  unsafe job.Running.ticks = unsafe job.Running.ticks + 1
  seen = unsafe job.Running.label
}

The variant is required and is what selects the slot, so a field two variants share is never ambiguous. A record-typed payload keeps projecting (unsafe job.Running.spec.width). An unknown variant is a WS060, an unknown field a WS010, a missing segment a WS070.

The tag is asserted, never tested and never written:

• Reading a variant the value is not returns that slot’s stale contents, with no error and no default.
• Writing sets the slot only. If job is Idle, unsafe job.Running.ticks = 5 fills Running’s slot while job stays Idle, and a later match still takes the Idle arm.

Prefer a destructure, which tests the tag first; reach for unsafe when you have already established the variant.

unsafe is contextual, so a variable, parameter, or mod named unsafe keeps working. (The tree-sitter grammar cannot express that and treats the word as a keyword, so an editor using it flags such a name even though it compiles.)

Generic enums

An enum can take type parameters, instantiated per use exactly like a generic type alias:

enum Box<T> { Value(T), Empty }

static var b: Box<int> = Box.Value(42)

out val = match b {
  Value(x) => x,
  Empty    => 0,
}

Built-in Option and Result

Wirescript ships Option<T> and Result<T, E> as prelude enums – no declaration needed, and their variants are usable bare (Some/None/Ok/Err, see Construction above). They’re built in as if declared:

enum Option<T> { Some(T), None }
enum Result<T, E> { Ok(T), Err(E) }

Don’t redeclare them yourself – the prelude already registers both names, so an enum Option<T> { ... } of your own is a WS013 duplicate-declaration error.

static var maybe: Option<int> = Some(7)
static var missing: Option<int> = None

out found = match maybe { Some(x) => x, None => -1 }

static var r: Result<int, string> = Ok(200)

out status = match r {
  Ok(code) => code,
  Err(msg) => -1,
}

Built-in game enums

A handful of enum types are built into the compiler with no enum declaration at all. EasingFunction, Direction, ColorSpace, DisplayTextJustification, TextTypeface, DisplayTextEasing, and EasingDirection are the ones shipping today. They are not hand-maintained: the compiler discovers them from the game’s own config enums (the same ones that back a gate’s settings-menu fields), so the exact set and its variants track whatever build the compiler was generated against.

A built-in game enum behaves like an ordinary unit-only enum (see Declaration above): construct a variant with its qualified path, store it in a var or static var, and read .Discriminant:

static var mode: EasingFunction = EasingFunction.Bounce

out disc = mode.Discriminant

The enum value is the default representation; .Discriminant gives back the integer the game’s own schema assigns that member. That is the one place a built-in game enum differs from a user-declared one: a user enum’s discriminants auto-number from 0, but a built-in game enum’s discriminant is the real schema value, since it round-trips through saved component data and a renumbered tag would write the wrong value to the game.

A built-in enum value also passes directly as the matching gate config argument:

in t: float

let eased = Easing(0.0, 1.0, t, function = EasingFunction.Bounce, direction = EasingDirection.InOut)
out result = eased

The older bare-name form (an unqualified member name) still works side by side with the enum-qualified form, and both set the same config field:

in t: float

let eased = Easing(0.0, 1.0, t, function = Bounce, direction = InOut)
out result = eased

Expressions

Expressions compute values. In Wirescript, expressions map to wire graph gates – each operator or function call becomes one or more gates with their ports wired together.

Contents

• Operator Precedence
• Arithmetic Operators
• Comparison Operators
• Logical Operators
• Bitwise Operators
• String Concatenation
• String Interpolation
• Conditional Expressions (if-then-else)
• Atom Literals
• Record Literals
• Tuple Literals
• Field Access
• Index Access
• Tuple Pick
• Function Calls
• Ref and Deref
• Parenthesized Expressions
• Gotchas
• Asset References
• Prefab References

Operator Precedence

Operators are listed from lowest (loosest binding) to highest (tightest binding):

Parentheses ( ) override precedence as usual.

// ** is right-associative:
let x = 2 ** 3 ** 2   // = 2 ** (3 ** 2) = 2 ** 9 = 512

// Standard math precedence:
let y = 1 + 2 * 3     // = 1 + (2 * 3) = 7

// String concat at same level as +/-:
let s = "x=" .. x + 1  // = "x=" .. (x + 1) -- careful!

Arithmetic Operators

Mixed int/float arithmetic promotes the result to float. bool values are treated as 0/1 when mixed with int.

+ - * / % also operate component-wise on two vector operands, lowering to the same math gates (whose inputs accept the vector, f64 and i64 wire variants). Mixing a vector with a scalar broadcasts the scalar across the components (v * 2.0, 10.0 * v, v / 4); the result is a vector. The Scale helper still works for explicit vector–scalar scaling.

Colors work the same way — the math gate’s variant set also covers color (LinearColor), so + - * / % operate RGBA channel-wise on two color operands, and mixing a color with a number broadcasts that number across the channels: add one to lighten (c + 0.1), multiply to scale (tint * 0.5 dims every channel including alpha), either direction (0.1 + c, 2 * c). The result is a color.

The same gates also accept the rotation family (quat / rotator), so q1 * q2 composes two rotations. Same-type operands keep their type; a quat/rotator mix yields a quat (freely coercible back to a rotator — see types).

An object operand (a controller/character/entity — e.g. a player) no longer coerces directly to an int on a math gate, so it is routed through (obj || false) first: 1 + player lowers to add(1, or(player, false)). The || gate coerces the object to a value the math gate accepts. This is automatic — just write the arithmetic.

let a = 10 + 3       // 13: int
let b = 10.0 + 3     // 13.0: float
let c = 2 ** 10      // 1024: int
let d = -42           // -42: int (negative literal folded at parse time)
let p = Vec(1.0, 2.0, 3.0) + Vec(4.0, 5.0, 6.0)  // (5, 7, 9): vector
let q = Vec(1.0, 2.0, 3.0) * 2.0                 // (2, 4, 6): vector × scalar
let blend = c1 * 0.5 + c2 * 0.5                  // RGBA channel-wise color blend: color
let lighter = tint + 0.1                          // add a number to every channel: color
let dimmer = tint * 0.5                           // multiply every channel: color
let spin = a1.ToRotation() * a2.ToRotation()     // compose two rotations: quat
let n = 1 + player                                // object → (player || false)

Comparison Operators

All comparison operators return bool.

Comparison accepts all wire variant types (int, float, bool, string, entity, controller, character) in any combination.

value is Enum.Variant tests which variant an enum value holds and also returns bool; see enums.

let isZero = count == 0
let isPositive = score > 0
let sameTeam = teamA == teamB

Logical Operators

Wire variant types are: bool, int, float, exec, string, entity, controller, character. The engine coerces all of these to bool on bool ports (truthy/falsy). This means exec values (true for one frame) work directly in logical expressions:

in reset: bool
in start: exec
on reset || start { ... }

let canMove = isAlive && !isFrozen
let either = a ^^ b

!(a && b) and !(a || b) are automatically fused into single NAND/NOR gates by the compiler.

Bitwise Operators

All bitwise operators produce int results. Operands are int; a float or bool operand coerces to int first (1.5 & 2 truncates 1.5 to 1), so only a non-numeric operand (string, vector, …) is a WS011 error.

~(a & b) and ~(a | b) are automatically fused into single NAND/NOR gates.

let mask = 0xFF
let high = (value >> 8) & mask
let combined = a | b
let flipped = ~flags
let shifted = 1 << bitIndex

String Concatenation

The .. operator concatenates strings. It automatically converts numeric types to their string representation.

let greeting = "Hello, " .. name
let label = "Score: " .. score
let coords = x .. ", " .. y .. ", " .. z

String Interpolation

Strings (both "double" and 'single' quoted) support ${expr} interpolation. The embedded expression is evaluated and converted to a string.

let msg = "Player ${name} scored ${points} points"
let debug = 'pos=(${pos.x}, ${pos.y}, ${pos.z})'
let nested = "result: ${a + b * c}"

Interpolated expressions can be arbitrarily complex:

let status = "Health: ${if hp > 50 then "OK" else "LOW"}"

Use \$ to include a literal $:

let price = "Cost: \$${amount}"

Both arms evaluate. An if expression compiles to a Select fed by both results, so the arm that is not chosen is computed and discarded. The branch picks which value is used, it does not skip work. Two consequences: an expensive expression in the untaken arm still costs its gates every tick, and an arm that would fail on bad input (an out-of-range slice, a divide by zero) still runs – gates yield a default rather than faulting, which is why this is safe, but it means an arm cannot be used to guard another.

Conditional Expressions (if-then-else)

The if-then-else expression evaluates to one of two values based on a condition. It is a pure expression that compiles to a Select gate.

let abs = if x < 0 then -x else x
let label = if count == 1 then "item" else "items"
let clamped = if v > max then max else if v < min then min else v

Syntax: if <condition> then <true-expr> else <false-expr>

then and else may also start their own continuation lines:

let intel = if playerCount <= 6
  then "You have a teammate"
  else "You are alone"

Block Expressions

Branches can be block expressions { stmts...; value } with locally-scoped let bindings:

let result = if x > 0 then {
  let doubled = x * 2
  let offset = doubled + 1
  offset
} else {
  0
}

let bindings inside a block expression are scoped to that block — they are not accessible outside. The block’s value is its last expression.

Block expressions stay pure (Select gate) as long as they only contain let bindings. They can be used anywhere an expression is expected:

let norm = { let len = sqrt(x*x + y*y); len }

The result type is the widening join of both branches – the same rule that infers a generic type parameter from its call-site arguments: numeric branches widen to a common numeric type (int widens to float), and object branches widen toward entity. The branches are not required to already match:

let value = if flag then 42 else 3.14  // type: float (int widens to float)

If the branches have no common widening (e.g. int and vector), it’s a compile error:

in v: vector
let bad = if flag then 1 else v
// ERROR WS003: if-then-else branch type mismatch: then is int, else is
// vector (no common widening)

Conditional expressions can be nested and used anywhere an expression is valid:

let score = baseScore + (if hasBonus then 100 else 0)
chip let emptyCount = (if c0 == 0 then 1 else 0) + (if c1 == 0 then 1 else 0)

Atom Literals

An atom literal :name is a compile-time int constant – the deterministic xxHash64 (seed 0) hash of name. It’s a readable stand-in for a hand-picked magic number: a key for an int-keyed map, or an enum-like tag.

var scores: Map<int, int> = { :red => 10, :blue => 20 }
if team == :red { ... }

The name may contain letters, digits, _, and - (the first character must be a letter or _ – a leading digit or - doesn’t lex as an atom start). :my-text is a single atom, not :my followed by a subtraction – write :a - b, with spaces, when you mean :a minus b. Atoms only lex where a value is expected (after =, an operator, (, ,, [, =>, …); a : immediately after something that already reads as a value – a type annotation (x: int), a record field ({ x: 1 }), or a map’s string/atom key separator ("red": 1, :red: 1) – stays a plain colon instead.

There’s no runtime string-to-hash gate: an atom’s value is always resolved at compile time, so :name can only appear as a literal, never built from a runtime string.

Record Literals

Record literals construct values of a named record type. Fields are specified as name: expr pairs inside braces:

type Point = { x: int, y: int }
let p: Point = { x: 1, y: 2 }

Shorthand syntax: when a field name matches a variable in scope, you can omit the value:

var x: int = 0
var y: int = 0
let p: Point = { x, y }  // equivalent to { x: x, y: y }

Spread operator: copy all fields from an existing record, then override specific fields:

let a: Point = { x: 1, y: 2 }
let b: Point = { ...a, y: 99 }  // b.x == 1, b.y == 99

Later fields override spread fields. Multiple spreads are allowed.

A record value is a compile-time abstraction – it produces no wire graph gates, and each field resolves directly to the underlying binding of its value expression. A record used as storage (a var, array, or map) is the exception: it decomposes into one gate per field. See Records as storage.

Tuple Literals

Tuple literals construct tuple values with positional elements:

let pair = (1, 2)
let triple = (true, 3.14, "hello")

Access elements with .0, .1, .2, etc.

Field Access

Use dot notation to access fields on values:

let x = position.x       // vector field
let r = myColor.r         // color field
let p = myRotator.pitch   // rotator field

Vector / color / rotation components

Every component-typed value can be read one component at a time:

The names are also accepted upper-case. They work on any expression of that type — a Vec(...) literal, an input, a stored variable, or a let binding — and lower to the matching Split gate (SplitVector, SplitColor, SplitRotation, SplitQuaternion), which outputs the single float component:

in a: vector
in b: vector
let sum = a + b          // vector
let height = sum.z       // float — the z component

in tint: color
let red = tint.r         // float

in facing: rotator
let turn = facing.yaw    // float — degrees

let spin = a.ToRotation() // quat
let scalar = spin.w       // float

Reading several components of the same value costs one gate, not one per component: the split gates are identical and merge.

A component name belongs to exactly one type, so borrowing one (v.w, facing.x, tint.z) is a WS010 error rather than a silent misread.

Variable Fields

Variables have special .Value and .prev fields:

var count: int = 0

// .Value -- reads the current value (delayed read, works in pure context)
out currentCount = count.Value

// .prev -- reads the previous tick's value (change detection)
chip let changed = count != count.prev

In exec context, a bare variable name auto-dereferences to its value when used in expressions (arithmetic, comparisons, etc.). When passed to a *T parameter, the variable stays as a reference. In pure context, the bare name refers to the ref T (the variable reference itself). Use .Value to read the value in pure context.

Record Fields

Functions and chips that return records allow field access on the result:

let input = InputReader(char)
let fwd = input.Forward    // float
let rgt = input.Right      // float
let jmp = input.Jump       // bool

Exec Field (.exec)

.exec names the exec output of an exec-returning call. Use it whenever you need to reference that completion signal — to sequence on it (await), handle it (on), or wire it into another gate’s exec =.

Three cases resolve through .exec:

• A call that returns a bare exec. Some builtins produce an exec whose underlying port has a gate-specific name (e.g. a Change detector’s exec port is OnChanged). .exec denotes that exec directly:

  let ch = Change(score)     // exec — fires when `score` changes
  on ch.exec {               // handle it
    ctrl.DisplayText("score changed")
  }
  

• A chip or mod called with exec =. An exec chip/mod call returns its completion exec as an .exec field on the result record, so callers can sequence on the body having finished:

  let t = InitTables(exec = reset)
  on start {
    emit reset
    await t.exec             // resumes after InitTables ran
  }
  

• An event that also carries data. A data-carrying event expression (a custom event with data outputs) is a record whose exec output comes first, so .exec names that trigger explicitly and lets the event compose with other exec signals:

  in reset: exec
  on Union(reset, CustomEvent("ping").exec) {   // fires on reset OR the event
    ctrl.DisplayText("announced")
  }
  

Union also takes an exec receiver, so a.Union(b) is Union(a, b) and a wide fan-in reads as a left-associative chain instead of nested Union(Union(...)):

in reset: exec
on reset.Union(CustomEvent("ping").exec).Union(Change(score)) {
  ctrl.DisplayText("announced")
}

See Explicit Exec Argument and Exec Chips.

Index Access

Use bracket notation to index into arrays:

let item = myArray[i]
// item.value -- the element value
// item.bOutOfBounds -- bool, true if index was out of range

Tuple Pick

Use .N (dot followed by an integer) to pick an element from a tuple:

let pair = someTupleExpr
let first = pair.0
let second = pair.1

Function Calls

Call functions and chips by name with parenthesized arguments:

// Positional arguments
let dist = Distance(posA, posB)
let s = sin(angle)

// Named arguments (kwargs)
DisplayText(ctrl, "Hello",
  positionX = 0.0,
  positionY = -100.0,
  fontSize = 24
)

Named arguments use name = value syntax. They can be mixed with positional arguments, but positional arguments must come first (matching the parameter order).

Running an exec gate with exec = <trigger>. Any exec-gate call — a builtin like Random, an array/map method, or a user-defined exec chip/mod — accepts a reserved exec = <trigger> named argument that drives its exec input. This lets an exec gate run outside a handler: it fires each time the trigger’s value changes rather than riding the surrounding exec chain, so the call becomes a leaf that is legal in a pure binding.

// Pure output binding — the get fires whenever `i` changes (i + 1 is never 0):
out c: color = lut.get(i, exec = i + 1).Value

// Outside any handler — provide the trigger explicitly:
let r = Random(0, 10, exec = someTrigger)

Pair it with .exec to sequence on the result. See Explicit Exec Argument.

// First positional args, then named
let v = Vec(1.0, 2.0, 3.0)

// All named
DisplayText(target = ctrl, text = msg, fontSize = 30)

Ref and Deref

The ref keyword creates a reference to a value. The * prefix operator dereferences a reference.

// ref creates a reference
let r = ref someVar

// * dereferences
let val = *r

In practice, ref and * are primarily used in chip parameter passing. When a chip parameter has type ref T (or *T), you pass a variable and the chip can read/write it:

mod increment(counter: *int) {
  counter = counter + 1
}

var n: int = 0
on tick {
  increment(n)  // passes ref to n; n is mutated
}

*var — Explicit Deref in Exec Context

Inside exec context, prefixing a variable with * explicitly reads its current-tick value via a Var_Get gate. This is identical to the implicit auto-deref that happens with a bare variable name in exec context — it exists for clarity or to disambiguate:

var x: int = 0
on tick {
  let a = x    // implicit deref (Var_Get)
  let b = *x   // explicit deref (same Var_Get, same result)
}

*var is not allowed in pure context — it produces error WS006 (“use .Value for pure reads”). In pure context, use x.Value instead.

Variable Read Modes Summary

Parenthesized Expressions

Parentheses group expressions to override precedence:

let result = (a + b) * c
let check = !(x && y)

Gotchas

Bitwise & is lower precedence than ==/!=

This matches C. x >> 31 & 1 != 0 parses as x >> 31 & (1 != 0). Always parenthesize:

let bit = ((x >> 31) & 1) != 0  // correct
let bad = x >> 31 & 1 != 0      // wrong — compares 1 != 0 first

Chips encapsulate state

Chip internal var/array are not accessible from outside. Only declared -> outputs are visible. For shared mutable state, use top-level declarations and mod macros.

The reverse works, though: a chip body can reference top-level vars, arrays, and buffers freely — wire refs cross chip boundaries.

Asset References

$AssetType/AssetName references an external asset the world embeds by name — weapons, pickups, projectiles, and audio/font descriptors:

let weapon = $BRItemBase/Weapon_Pistol
let beep = $BrickOneShotAudioDescriptor/BOSA_Buttons_Button_1_Press

The editor completes asset references: typing $ offers the asset types, and $Type/ offers that type’s asset names (from the embedded asset catalog). An asset reference is meant to be passed to a gate that takes an asset (e.g. an inventory or audio gate).

Prefab References

A $ reference whose path begins with . or / is a prefab file reference — it points at a .brz prefab archive rather than a named catalog asset:

• $./file.brz — relative to the current source file’s directory.
• $/abs/path/file.brz — a filesystem-absolute path.

A reference ending in .ws is a source prefab: the file is compiled at reference time and the result embedded, so a prefab can be kept as readable source next to the program that spawns it. Its own $./… references resolve relative to that .ws file. Source prefabs may nest 8 deep.

Pass either form to SpawnPrefab:

on spawn {
  SpawnPrefab(prefab = $./turret.brz, offset = Vec(0.0, 0.0, 50.0))
  SpawnPrefab(prefab = $./minion.ws, offset = Vec(0.0, 0.0, 50.0))
}

A prefab can also be written inline, as a $ followed by a triple-backtick block of Wirescript compiled as a nested prefab. The spawned chip’s source sits at the spawn site, and it closes over nothing — it communicates by targeted custom events like any other prefab. Inline blocks may nest 8 deep.

var subject: character

on CharacterSpawned() -> (who) {
  let e = SpawnPrefab(prefab = $```
    var owner: character
    on CustomEvent("init") -> (p: character) {
      owner = p
      on ServerUptime() {
        if owner.GetUserId() == "" { ReadBrickGrid().DestroySpawnedPrefab() }
      }
    }
  ```, lifetime = 0.0, limit = 64)
  subject = who               // a var: a constant argument emits no wire
  e.SendCustomEvent("init", subject)
}

Why this form exists. A loop advances one iteration per tick, so a central chip sweeping N entities every tick costs N ticks per pass. Spawning one chip per entity moves that work into parallel gate instances, and the per-tick cost stops depending on N. Note that the nested on ServerUptime() above is not registered by the init handler — the wire graph is static, so its trigger is live from the moment the prefab spawns, before init lands, which is why real code guards it on an init-set value. See per-entity fan-out and Loops.

At compile the referenced .brz is read and embedded into the output bundle (content-addressed at Prefabs/Uploads/<hash>.brz), and the gate’s Prefab property is set to that embedded path — so the compiled program is self-contained. Typing $./ completes available .brz files (the editor scans the project directory; the web playground has a Prefabs panel where you upload or drag in .brz files).

Statements

Statements are the building blocks of Wirescript programs. They declare data, define behavior, and control execution flow.

Contents

• var – Mutable Variable
• let – Immutable Binding
• const – Compile-Time Binding
• buffer – Buffered Value
• Arrays – var name: elementType[]
• Maps – var name: Map<K, V>
• in – Input Port
• out – Output Port
• @left / @right / @top / @bottom – Outer Rerouter Pins
• if – Conditional Statement
• match – Branch on an Enum Variant
• if let / let else – Refutable Enum Binds
• on – Event Handler
• let on – Event Declaration
• emit – Emit Signal
• await – Suspend Exec Chain
• Assignment
• Expression Statement
• Built-in Events
• return

var – Mutable Variable

Declares a mutable variable backed by a wire graph variable gate. In exec context (inside handlers or mods), the variable is reset to its initial value each time the code path executes.

var name: type = initializer
var name: type              // default-initialized
var name = initializer      // type inferred from annotation or usage

The type annotation and initializer are both optional (but at least one should be provided for the typechecker to determine the type).

var count: int = 0       // resets to 0 each handler invocation
var score: float = 0.0
var alive: bool = true
var label: string = "hi" // strings persist in vars too
var dir: vector = Vec(0.0, 0.0, 1.0)

A variable is backed by a wire-graph Variable gate, whose value is a wire variant, so a var can hold any variant member type: int, float, bool, string, vector, and object types (entity, controller, character).

static var – Persistent Variable

A static var keeps its value across handler/mod invocations. The initial value is set once when the save loads. Use this for accumulators, counters, or state that must survive across calls.

static var total: int = 0     // persists across calls
static var highScore: int = 0

on RoundStart() {
  total = total + 1           // accumulates over time
}

Top-level (module-scope) var declarations are always persistent — static is only meaningful inside handlers and mods, so static var at top/root level is a no-op (just use var).

Variable Identity

Internally, a var x: T has type ref T. This means:

• In exec context (inside on handlers): x auto-dereferences to type T when used in expressions. When passed to a *T parameter, it remains a reference.
• In pure context (outside handlers): x refers to the variable reference itself (ref T). Use x.Value or x.prev to read the value.

var count: int = 0

// Pure context -- use .Value for the current value
out currentCount = count.Value

// Exec context -- direct access auto-derefs
on RoundStart() {
  count = count + 1    // reads and writes the int value directly
}

See Execution Context for full details.

let – Immutable Binding

Binds a name to a computed value. Unlike var, a let binding is not mutable storage – it is a pure wire connection to an expression’s output.

let name = expression
let name: type = expression

let doubled = count * 2
let isAlive = hp > 0
let greeting = "Hello, " .. playerName

An optional type annotation can follow the name. The annotation does not change the binding’s type – it is a checked assertion. If the expression’s inferred type does not match, the compiler emits a WS016 warning.

let x: int = 42           // ok — types match
let y: float = 42         // ok — int coerces to float
let z: string = 42        // WS016 warning — int does not match string

let bindings can appear at the top level, inside blocks, and inside chip bodies. They are evaluated in pure context.

// Top-level let
let maxScore = 100

// Let inside a handler (evaluated in the exec context of the handler)
on RoundStart() {
  let r = Random(0, 15)
  if r == 0 { count = count + 1 }
}

Record Destructuring

Destructure a record into individual bindings with let { field1, field2 } = record:

type Point = { x: int, y: int }
let p: Point = { x: 10, y: 20 }
let { x, y } = p
let sum = x + y  // 30

Each destructured name becomes an independent let binding that resolves to the same underlying value as the original record field.

Tuple Destructuring

Destructure a tuple into named bindings:

let (first, second) = someTuple

A rest pattern captures remaining elements:

let (head, ...rest) = longTuple

Spread in Call Arguments

Spread a tuple or record into a function’s positional arguments:

let args = (1, 2, 3)
foo(...args)  // equivalent to foo(1, 2, 3)

const – Compile-Time Binding

const binds a name to a value, exactly like let:

const name = expression
const name: type = expression

const width = 8
const area = width * width          // 64
const greeting = "Score: " .. "0"   // string concatenation folds too

const vs let

let folds its initializer opportunistically: when the value happens to be computable at compile time it becomes a literal, and when it isn’t, let falls back to an ordinary runtime wire. Either way the program compiles. const makes the opposite promise: the initializer must evaluate at compile time, and one that can’t is a compile error (WS046) instead of a silent runtime wire.

in live: int

let n = live + 1     // fine -- falls back to a runtime wire

in live: int

const n = live + 1   // WS046 -- 'live' is a runtime value, not a compile-time constant

Reach for const when a value’s shape drives something that has to be known at compile time: a gate config field, a custom-event channel name, or the contents of a baked array. A typo that turns it into a runtime read is caught immediately instead of shipping a build where that position silently went empty or default.

Where const is allowed

Anywhere let is allowed: at the top level, inside a block, and inside any mod/chip body, at any nesting depth.

const TOTAL_SLOTS = 4    // top level

mod f() -> int {
  const doubled = TOTAL_SLOTS * 2  // inside a mod body
  return doubled
}

One scope limit is worth knowing, and it is reported, never silent. A NAMED chip’s body constants reach that chip’s own code, including its handlers, its outs and its constant-only config slots. A chip declared inside it is built against a constant scope of its own, so a name it would inherit from the outer body does not resolve there. Rather than drop the value, that reports WS028; pass the value in as a const parameter instead.

chip Outer(t: exec) {
  const ch = "evt"
  chip Inner(u: exec) { on u { send(ch) } }                // WS028 -- ch does not reach Inner
  chip Ok(u: exec, c: const string) { on u { send(c) } }   // pass it in instead
  let q = Ok(t, ch)
}

What’s const-evaluable

• Literals, and any other const/named constant.

• Arithmetic, bitwise, shift, comparison, logical, and .. string concatenation over constant operands, with the same semantics as the gates they would otherwise have compiled to: 64-bit wrapping integers, divide-by-zero as 0, and a non-finite float as 0.

• String interpolation ("a${1 + 1}b") and the certified string/math builtin methods (.ToUpper(), .Trim(), .Length(), sin, sqrt, …), when every operand is constant.

• abs, min, max, clamp fold on FLOAT constants but not INT ones. min(3.0, 7.0) folds; min(3, 7) emits a gate. This is a coverage gap, not a language rule: the certified fold pass only folds a gate on an input shape the in-game probe actually recorded, and these four were only ever probed with float inputs (unlike +/-/*, which were probed with ints and fold). Until the probe is rerun with int inputs, either use a float literal (max(n, 0.0)) where a float result is fine, or write the constant directly. A single non-folding op strands everything downstream of it.

• The Vec/Rotation/Color constructors.

• Array and map literals, indexing (arr[i], m[k]), and .length().

• Record literals and field access (.field), including nested records.

• A call to a const mod (see const Parameters and const mod), including one nested inside an operator, a unary operator, or a Vec/Rotation/Color constructor argument (positional or named):

  const mod double(n: int) -> int { return n * 2 }
  
  const seven = double(3) + 1                 // 7 -- nested in an operator
  const negSix = -double(3)                   // -6 -- nested in a unary operator
  const v = Vec(double(1), y = 2.0, z = 3.0)  // nested in a named constructor argument
  

  A call nested one level deeper than that, as an argument to a call whose own callee is not itself a const mod, still is not evaluated, because that callee has no compile-time form of its own to descend through:

  const mod double(n: int) -> int { return n * 2 }
  mod scaleUp(n: int) -> int { return n }
  
  const total = scaleUp(double(3))   // WS046 -- scaleUp is not itself a `const mod`
  

  Bind the call first, then pass the result: const d = double(3), then scaleUp(d).

An out-of-range array index, and a missing map key or record field, are refused outright rather than falling back to a stale or default value – unlike a runtime out-of-range array read, which keeps the gate’s previous value, there is no previous value to fall back on at compile time.

A const value reaches every position that requires a literal, not just another const binding: gate config fields, a custom event’s channel name on both the sending and the receiving side, and the contents of a baked array or map:

const CHANNEL = "evt_" .. "died"

in go: exec
var n: int = 0

on go { SendCustomEvent(CHANNEL, n) }
on CustomEvent(CHANNEL) -> (v: int) { n = v }

A const array built at the top level can be indexed there too, in both a baked initializer and a runtime wire operand:

const t = [10, 20]
const z = t[1]        // 20

var counts: int[] = [z, 12345]   // baked into the array's initial contents

var rv: int = 0
in go: exec
on go {
  if z == rv { BroadcastChatMessage("match") }   // baked as a literal operand
}

const containers at runtime

A const array or map is a compile-time value and a runtime container. It folds wherever the answer is known at compile time (t[1] above costs nothing), and the first runtime read builds a real container gate with the constant contents baked into its initial value:

const t = [10, 20, 30]
const m = { "a": 1, "b": 2 }

mod pick(ys: int[], at: int) -> int { return ys[at] }

var i: int = 1
var k: string = "b"
in go: exec

on go {
  BroadcastChatMessage(t[i])        // 20, read at a runtime index
  BroadcastChatMessage(t.length())  // 3
  BroadcastChatMessage(pick(t, i))  // 20, passed as a `T[]` argument
  BroadcastChatMessage(m[k])        // 2, read at a runtime key
}

The container is built only where something needs it, and only once, so a const table used purely at compile time costs no gates and many runtime reads of one table share a single gate.

Outside a const mod body a const container is immutable: t.push(4), t.clear() and t[0] = 4 are all rejected, so the compile-time value and the runtime contents can never disagree. Declare it var to make it mutable.

Compile-time mutation

Inside a const mod body, a const array or map can be mutated in place using push/set/clear/append on an array and set/remove/clear on a map, so a collection can be assembled conditionally and still bake with zero gates:

const mod rooms(n: int) -> int[] {
  const t = [10]
  if n >= 2 { t.push(20) }
  if n >= 3 { t.push(30) }
  return t
}

const layout = rooms(2)   // [10, 20], computed entirely at compile time

See const Parameters and const mod for calling const mods, const parameters, and how a const-evaluable if condition drops its untaken branch.

Diagnostics

buffer – Buffered Value

Declares a value that is delayed by one tick. Buffers are useful for creating feedback loops where a value depends on its own previous state without creating a circular dependency.

buffer name = expression
buffer name: type = expression

buffer prevScore = score
buffer delayed: int = count

The optional type annotation is useful when the expression type needs clarification (e.g., for self-referential buffers).

Arrays – var name: elementType[]

An array holds multiple values of the same element type. Declare one as a var whose type ends in [] (there is no separate array keyword):

var name: elementType[]

var scores: int[]
var positions: vector[]
var names: string[]
var flags: bool[]

The type annotation must end with [] to indicate it is an array type. The element type selects the backing array variant (int -> Int64 array, float -> double array, bool, string, vector, and object types each map to their matching array kind), so elements keep their declared type rather than all being stored as doubles.

An array can be given constant initial contents with an = [ ... ] initializer. At the top level (outside an exec handler) the contents are baked straight into the array gate, so every element must be a compile-time constant. The array loads pre-populated with no runtime setup:

var scores: int[] = [100, 50, -10]
var names: string[] = ["alice", "bob"]

A constant is a literal (numbers — including negatives — strings, and bools), or any expression built from literals and top-level let constants. So a table can name its constants instead of restating their values:

let C_FROZEN = 3
let WIDTH = 8

var masks: int[] = [1 << C_FROZEN, 1 << C_FROZEN | 1]
var cells: int[] = [WIDTH * WIDTH, WIDTH - 1]

Constants resolve through chains (let B = A + 1) and in any declaration order. Arithmetic, bitwise, shift, comparison, logical and .. string concatenation all fold, using the same semantics as the gates they would otherwise have compiled to — 64-bit wrapping integers, divide-by-zero as 0, and a non-finite float as 0.

Initializers may span multiple lines — newlines are allowed after [, around commas, and before ], with an optional trailing comma:

var names: string[] = [
  "alice",
  "bob",
]

An element that is not a compile-time constant — a runtime value such as an in port, a call, or a ...spread — is an error at the top level, because there is no exec context in which to populate it. Build the array from runtime values inside a handler instead (see below).

Inferred element type

The element type is taken from the annotation, or inferred from the literal when there’s no annotation:

var queue: int[] = [1, 2, 3]   // annotated
var queue = [1, 2, 3]          // element type inferred -> int[]

Building an array at runtime (assignment + spread)

Inside an exec handler you can assign an array literal to an array variable. It desugars to clear -> push each item -> append each spread, so the elements may be any runtime value, and a ...spread splices another array’s contents in place:

var base: int[] = [3, 4]
var work: int[]

on tick {
  let n = score + 1
  work = [n, 1, ...base, 5]   // clear, push n, push 1, append base, push 5
                              // -> [n, 1, 3, 4, 5]
}

The assignment always clears first, so it replaces (not appends to) the previous contents. Spreads are only valid here, not in a top-level initializer.

Access elements with bracket notation:

let item = scores[i]
// item.value: int (the element)
// item.bOutOfBounds: bool (bounds check)

Maps – var name: Map<K, V>

A map is a keyed collection backed by a MapVar gate. Declare one as a var whose type is Map<K, V> (there is no separate map keyword):

var scores: Map<string, int>
var owners: Map<int, entity>

The key type K must be int, string, or an object reference (entity / character / controller) — a map is keyed by a hashed slot, and only those types have a slot representation. Any other key type is a WS039 error. The value type V may be any storable variant.

Like an array, a map starts empty and is built at runtime from an exec handler — read/write access goes through its methods, which are exec-only:

in tick: exec

on tick {
  scores.set("alice", 10)      // insert / overwrite
  let r = scores.get("alice")  // r.Value + r.Found (auto-unwraps to Value)
  if scores.has("bob") { }
}

A map literal can seed a map at declaration or in an assignment (scores = { "a": 1, "b": 2 }); a map literal used anywhere else is a WS026 error, and assigning a whole map from another map (m = m2) is unsupported — use m.copyFrom(src) (WS027). See Builtin Functions for the full map-method table (get, set, has, remove, clear, copyFrom, length, keys, values).

in – Input Port

Declares an input port for the current scope. At the top level, in creates an external input that other wire graphs can connect to. Inside a chip, in creates a chip input port.

in name: type

in trigger: exec
in player: character
in speed: float
in enabled: bool

Input values are read-only within the script. They are provided by the external wire graph environment.

out – Output Port

Declares an output port that exposes a value externally.

Value outputs

The value form is a pure expression – continuously computed from its inputs.

out name = expression

out score = count
out isAlive = hp > 0
out doubled = value * 2
out greeting = "Score: ${count}"

Typed value outputs

An output port can have both a type annotation and a value expression. The annotation is a checked assertion (like on let):

out name: type = expression

out score: int = count.Value     // type asserted + value
out ratio: float = hits / total
out ref: *int = myVar            // ref output — exposes the variable reference

This form is required when you want to expose a variable reference (*T) rather than its computed value, or to disambiguate the type when the compiler would otherwise warn.

Exec outputs

The typed form without a value declares an exec output port. Use emit inside a handler to connect the current exec chain to it.

out done: exec

on RoundStart() {
  count = count + 1
  emit done  // fires the 'done' output after incrementing
}

This is useful for chips that need to signal completion:

chip Counter(bump: exec) -> (value: int, done: exec) {
  var n: int = 0
  on bump {
    n = n + 1
    emit done
  }
  out value = n.Value
}

Value output bindings are evaluated in pure context. Exec outputs are wired via emit in exec context.

WS017 – Ambiguous variable output type

When out foo = someVar is used and someVar has no explicit type annotation, the compiler emits WS017 because it cannot determine whether you want the variable’s value or a reference to it:

warning WS017: output type inferred from untyped variable
  suggest: `out foo: T = var` for value or `out foo: *T = var` for ref

Fix by adding a type annotation:

out foo: int = myVar      // exposes the value (uses .Value)
out foo: *int = myVar     // exposes the variable reference

@left / @right / @top / @bottom – Outer Rerouter Pins

Annotating a top-level in or out with a side places a physical Rerouter brick on the outside of the compiled microchip, pre-wired to that port. Placed chips can then be wired up like an IC: wire into an input pin’s rerouter, and from an output pin’s rerouter.

@left in go: exec          // same line
@left
out done: exec             // or on the line directly above
@right out score = 1
@top in players: int

Rules:

• Valid sides are exactly left, right, top, bottom; one annotation per declaration.
• Only top-level in/out of the compiled file may be annotated. Inside chip {} or mod bodies the annotation is an error (WS023).
• Unannotated ports get no rerouter — the feature is fully opt-in.

Placement:

• Rerouters sit flush against the chosen side of the chip brick, bottom-aligned with it, spaced 2 grid units apart and starting from the top corner (left/right sides) or left corner (top/bottom sides) of the edge.
• Ports on the same side appear in declaration order, with in and out freely interleaved. Left/right sides run top to bottom; top/bottom sides run left to right.
• Each rerouter is coloured by its port’s value type and carries a floating label with the port’s name; a side’s input and output labels read opposite ways so the two are easy to tell apart.

                @top ports (left to right)
                ┌──[d]────────────┐
   @left ports  │                 │  @right ports
(top to bottom) │                 │  (top to bottom)
        [a] ────┤    microchip    ├──── [c]
        [b] ────┤                 │
                └─────────────────┘
                @bottom ports (left to right)

@label – Port Display Label

@label("text") overrides the floating display label on a port’s gate (and its rerouter pin label, if the port also has a side annotation). The port’s wiring-UI name always stays the declared identifier – @label only changes what’s shown floating in the world.

Unlike @left/@right/@top/@bottom, which are top-level only, @label works on in/out declarations at any nesting level, and it stacks with a side annotation in either order:

@left @label("Fire!") in trigger: exec
@label("Fire!") @left in trigger: exec   // order doesn't matter

Expression labels (@label(<expr>))

The argument may be an expression, not just a string literal. A compile-time constant expression is folded and its value baked as the label text (a float renders the same 3-decimal way FormatText shows one):

let title = "Score"
@label(title) out v: int = 0      // baked "Score"
@label(1 + 2) out w: int = 0      // baked "3"

@label also applies to a var, overriding the name it would otherwise show. On a top-level var the expression may be a runtime value — this is a dynamic label: the value is coerced to text and wired live into the variable’s floating label, so the label updates as the value changes. The common form is a variable labelling itself with its own value:

@label(score) var score: int = 0     // the label shows score's live value
@label(hp * 2) var shown: int = 0    // any runtime expression works

A runtime expression is only dynamic on a top-level var (the one element that carries a wireable text component). A runtime @label on a port (in/out), a chip, or a nested var has nowhere to host the wire and is a compile error — use a constant there.

Module-level @label (the root microchip)

A @label(<expr>) at the top of the file, separated from the first declaration by a blank line, labels the root microchip itself rather than any declaration — the same blank-line placement rule as @invisible/@nofold. A constant bakes the chip’s title text; a runtime value labels the chip dynamically (wired into the root shell’s label). The expression may forward-reference declarations below it, so a chip can label itself with one of its own variables:

@label(status)          // labels the whole chip with `status`'s live value

var status: string = "idle"
on tick { status = "running" }

Without the blank line, @label(status) would instead attach to the status declaration directly (a variable self-label, above).

@nofold – Suppress Constant Folding

• @nofold — suppress constant folding/elision for everything lowered from this declaration (let/out/var/chip/on, including captured events let e = on trigger { … } and await bindings); legal at any nesting depth. Placed at the very top of the file (after any module doc comment) and separated from the first declaration by a blank line, it applies to the whole module — the same blank-line rule as module doc comments. Sites where it can have no effect (anonymous chips, in declarations) emit a warning. Used by semantics-verification circuits that need real gates for known values.
• Two module-level gotchas: leave a blank line between a module doc block and a module-level @nofold (a directly-adjacent pair registers as neither), and a module-level @nofold applies only to the file compiled as the entry — an imported library’s own module-level @nofold does not carry into the importer (annotate the individual declarations instead).
• A module-level @nofold disables the entire constant-fold pass for that compile — the same effect as --no-fold on the CLI.
• @nofold also preserves literal-condition if branches. Normally an if whose condition is a literal true/false has its dead side stripped during lowering as a shortcut, ahead of the fold pass proper — but under @nofold (including a module-level one) that shortcut is suppressed too, so both branches stay real gates. See Constant Folding for the full pass.

@fold – Constant Folding (on by default)

• Constant folding runs on every compile by default, so @fold is now redundant — it is still accepted for backward compatibility but enables nothing that isn’t already on. To turn folding off, use @nofold (above) or --no-fold.
• Placement, if you do write it: @fold at the very top of the entry file (after any module doc comment), separated from the first declaration by a blank line — the same module-level, blank-line rule as @nofold, and module-level only (there’s no decl-scoped @fold). A directly-adjacent module-doc / @fold pair registers as neither and produces a module-level-only error.
• If both a module-level @fold and @nofold are present, @nofold wins and the parser warns that the two conflict.
• --fold on the CLI likewise just re-affirms the default; --no-fold disables folding. See Constant Folding for the full enable/disable story.

@layout("code") – Source-Shaped Gate Layout

• By default, gates are placed with a flat topological layout: nodes are ordered by dependency depth into columns, with no relationship to where they appear in the source. @layout("code") at the very top of the entry file (after any module doc comment), separated from the first declaration by a blank line, switches the whole compile to a source-shaped layout instead: each occupied source line becomes a row (earlier lines sit higher), and a node’s horizontal position follows its source column, so indentation is visible in the placed gates. Same blank-line rule as module-level @fold/@nofold, and it participates in the same top-of-file annotation run – @fold and @layout("code") can appear together.
• Entry-file-only, same as module-level @fold/@nofold: an @layout("code") at the top of an imported file does not carry into the importer and has no effect.
• Nodes with no real position in the entry file (values from an imported file, or synthetic nodes the compiler generates without a source range) adopt the row of whichever node consumes or produces them; a node with no such neighbor lands on an overflow row below the last source line.
• Three wrapping tiers keep large modules inside their placement budgets: a line wider than the line-width budget soft-wraps into an indented continuation row; lines stack into vertical bands capped at a height budget; a band that would push a page past its width budget starts a new page, stacked above the previous one. Each page is centered and flipped independently, so it reads top-down on its own.
• Nested chips inherit the mode from their parent, so a chip’s interior also renders source-shaped when the entry file has @layout("code").
• Values that many rows read run down a gutter bus rather than fanning out as one long diagonal wire per reader. Such a value – a variable, an input port, a value handed into or read back out of a chip – gets a lane: a column of rerouter bricks standing in the gutter between the input pins and the code body, chained downward from beside the value’s own producer. At every row that reads the value the lane branches off sideways and runs straight across into that row’s gates, so a read reads as a right angle instead of a diagonal. Lanes are packed so a value only holds a column for as long as it is read, and the longest-lived, most-read values take the outermost columns. A value read on a single row keeps its direct wire unless it is stored state, a port, or crosses a chip wall. An exec chain running from one statement to the next stays a direct wire either way – it belongs on the spine of its own rows, not out in the gutter.
• Own-line // comments render into the plane as floating text, on a row of their own between the surrounding code rows and left-aligned at the comment’s own indentation – so the notes read where they sit in the source. A comment lands on exactly one plane: the innermost chip whose own rows bracket its line, or the outermost plane for a comment no chip’s rows bracket (a file’s leading or closing notes). Only entry-file comments render, and only on planes whose own rows come from the entry file – an imported chip’s interior numbers its rows against its own file, so it carries no comments and takes its indentation from its nodes’ columns. Trailing comments – code and then // on the same line – are not rendered; the code already occupies that row. Doc comments (///) are unaffected: they keep rendering on the plane header of what they document.
• There is no CLI-flag equivalent (unlike @fold/--fold) – @layout is a source annotation only.
• "code" and "cube" are the accepted arguments; an unknown name (@layout("grid")) or a missing/malformed argument (@layout, @layout(5)) is a compile error. Naming a layout twice warns and the last one wins.
• @layout("cube") emits no per-gate labels. A cube packs gates shoulder to shoulder, so the floating name on a var, an I/O gate, a var tag, or a chip brick cannot be read there, and each one costs a text component. Dropping them typically removes most of the components in the save. The shell label and every plane header stay, so the block is still identifiable and a chip still shows its title when opened, as does a runtime @label(expr), whose text is a value the program computes rather than decoration.

@layout("code")

var total: int = 0
in tick: exec

// This note gets a row of its own in the plane.
on tick {
  total = total + 1 // ...but this one is not rendered.
}

@layout("cube") – Compact 3D Packing

@layout("cube") packs gates into a cube – rows of bricks, stacked into layers along the plane’s depth axis – without analysing the wire graph at all. The compiler already falls back to this arrangement on modules too large for the default layout to place economically; the annotation asks for it at any size.

It is the opposite trade from @layout("code"): wires are ignored entirely, so nothing about the picture tells you how signals flow, but the brick mass is as small as it can be and placement cost does not grow with the number of wires. Reach for it when a module is too big to read anyway and you want it to occupy as little space as possible.

Same placement rules as the other module annotations: at the very top of the entry file, separated from the first declaration by a blank line, and inert in an imported file. It applies to nested chip interiors too.

@layout("cube")

var total: int = 0
in tick: exec

on tick {
  total = total + 1
}

@flat – Inline Every Chip

@flat compiles the program onto a single grid. Every gate that would have lived inside a chip is placed alongside the rest, and every wire that would have crossed a chip wall becomes an ordinary same-grid wire. The result has no microchip bricks and no nested planes to open.

This is a placement decision, not a semantic one. Chips have never been a scoping boundary – wire references cross them freely either way – so a flattened program computes exactly what the nested one computed. What changes is that you get one plane to look at instead of a tree of them, and the per-boundary rerouter pins a crossing would otherwise need are gone.

It is independent of @layout(...) and composes with it. @flat with @layout("cube") is the natural pairing: one plane, packed as tightly as the gates allow. @flat on its own, or with @layout("code"), works too.

Because the chip bricks no longer exist, @label and @closed on a chip have nothing to apply to under @flat. They are not an error – they simply have no effect.

Same placement rules as the other module annotations: at the very top of the entry file, separated from the first declaration by a blank line, and inert in an imported file.

@flat
@layout("cube")

chip Step(a: int) -> (r: int) {
  return a * 2
}

var total: int = 0
in tick: exec

on tick {
  total = Step(total)
}

if – Conditional Statement

The if statement executes a block conditionally. It requires exec context – you can only use if statements inside on handlers or after handlers in the exec chain.

if condition {
  // then branch
}

if condition {
  // then branch
} else {
  // else branch
}

on RoundStart() {
  if score > highScore {
    highScore = score
  }

  if lives == 0 {
    gameOver = true
  } else {
    lives = lives - 1
  }
}

For pure conditional values, use the if-then-else expression instead:

// Expression (pure, no exec needed)
let clamped = if x > max then max else x

// Statement (exec required)
on trigger {
  if x > max { x = max }
}

match – Branch on an Enum Variant

match branches on an enum value’s variant, with each arm’s pattern binding the variant’s payload (if any). It works as an expression (comma-separated value arms, compiles to a Select tree) or as a statement (block arms, compiles to Branch/Union, exec context required):

enum Shape { Empty, Circle(float), Rect(float, float) }

static var s: Shape = Shape.Circle(5.0)

out area = match s {
  Circle(r)  => 3.14159 * r * r,
  Rect(w, h) => w * h,
  Empty      => 0.0,
}

enum Shape { Empty, Circle(float) }

static var s: Shape = Shape.Circle(5.0)
var lastArea: float = 0.0

on ReadBrickGrid() {
  match s {
    Circle(r) => { lastArea = r * r }
    Empty     => { lastArea = 0.0 }
  }
}

A match must cover every variant, or end in a _ wildcard arm – an uncovered variant is a WS054 error. See Enums for exhaustiveness, nested patterns, and the scrutinee limitation (a match target must be a var/let/param/const, not an enum in port).

if let / let else – Refutable Enum Binds

Single-variant shorthand for a one-armed match. if let PATTERN = scrutinee { ... } else { ... } runs the block only when the scrutinee is that variant, with the pattern’s bindings in scope; the else is optional:

enum Opt { Some(int), None }

static var o: Opt = Opt.Some(5)
var result: int = 0

on ReadBrickGrid() {
  if let Some(x) = o {
    result = x
  } else {
    result = -1
  }
}

let PATTERN = scrutinee else { ... } binds into the surrounding scope instead of a nested block, so its else must diverge (return/emit, or an if/match whose arms all diverge) – a non-diverging else is a WS062 error:

enum Opt { Some(int), None }

mod unwrapOr(v: Opt, fallback: int) -> int {
  let Some(x) = v else { return fallback }
  return x
}

See Enums for the full reference.

on – Event Handler

Handlers run code in response to events or triggers. The handler body executes in exec context.

on trigger {
  // body (exec context)
}

Triggering on Built-in Events

on RoundStart() {
  score = 0
}

on CharacterDied() -> (character) {
  lives = lives - 1
}

Event data is bound with a trailing -> (…) tuple capture (or -> { field: local } record capture) after the call — see Binding Event Data below for the full capture model. The number and types of values available are determined by the event (see Built-in Events below).

Some events also accept config args that configure the event gate itself, written inside the call parens. String literals (and Name = value named args) set the gate’s config fields — the parens hold config/inputs only, never event data. ChatCommand uses this for its command name and help text:

on ChatCommand("greet", "Greets the player") -> (player, args) {
  // "greet" -> command name, "Greets the player" -> help text
  // player -> controller output, args -> arguments output
  player.DisplayText("Hello ${args}")
}

// the help text can also be named, and bindings are optional:
on ChatCommand("wave", Description = "Wave at everyone") { }

The zone events — ZoneEntered, ZoneLeft, EntityZoneEntered, EntityZoneLeft, ProjectileZoneEntered, ProjectileZoneLeft, BrickChanged, BrickRemoved — accept a zone = <value> named arg that wires its value into the gate’s Zone input port (rather than setting a static config field). Pass an in port bound to a zone brick so one wire selects the zone the gate watches — and the same port can drive several of these gates:

in room: entity                             // wire to a Zone brick in-game
on ZoneEntered(zone = room) -> (character) { }  // room feeds the gate's Zone input
on ZoneLeft(zone = room) -> (character) { }

Frozen entities still fire entity zone events — SetFrozen(true) does not suppress EntityZoneEntered. But an entry only fires on a boundary crossing: SetLocation-ing an entity to a zone it is already inside does not re-fire the event. To force a fresh entry, move it out of the zone and back in.

Binding Event Data

on <call>(config…) -> <pattern> { } is the general capture form: the call’s parens hold config/inputs only, and a trailing -> binds whatever data the call produces. It works the same way whether <call> is a built-in event, a custom event, or an ordinary mod/chip call.

Tuple capture — -> (a, b) — binds outputs positionally under local names of your choosing. It works for any call that produces data, built-in or custom, and is the cleanest form when you don’t need to rename or skip fields:

on CharacterSpawned() -> (who) {
  who.ShowStatusMessage("Welcome!")
}

When you’re binding a single, untyped output, the parens are optional — -> who is shorthand for -> (who):

on CharacterSpawned() -> who {
  who.ShowStatusMessage("Welcome!")
}

(Annotating the slot still needs the parenthesized form, -> (who: character).)

Record capture — -> { field: local } — binds outputs by field name instead of position, for events with named data. Rename a field with field: local, or write the bare name (field) to keep it as-is; list only the fields you need — it’s fine to bind a subset:

on CharacterDied() -> { character: victim, killer } {
  victim.ShowStatusMessage("You were killed")
  killer.ShowStatusMessage("You got a kill!")
}

Record capture only works for events whose data outputs are named fields (built-in events); a call with positional-only data (e.g. a custom event or a plain chip/mod) requires tuple capture.

Binding inside the call parens is an error. The old on Event(a, b) { } form — where identifiers inside the parens bound data — no longer parses; the parser points you at -> instead. Parens are reserved for config and wired inputs: a literal/named config arg ("greet", Description = "..."), or a name = value wired input (zone = room, interval = secs).

Custom events write their data types in the tuple capture:

on CustomEvent("dmg") -> (amount: int, source: character) {
  // ...
}

A slot’s type can be omitted and is then inferred from a matching in-unit SendCustomEvent/SendGlobalCustomEvent on the same channel; when no sender supplies a type either, the slot defaults to float and emits WS042. See Custom Events for the full send/receive contract.

General triggers extend the same -> <pattern> capture to any exec-producing call — not just built-in/custom events. on auto-extracts the call’s exec output, so this works for a mod/chip call outside an exec context, driven by an explicit exec = ... input (the same convention as Random(0, 10, exec = trigger)):

var log: string[]

chip Note(msg: string) -> (count: int) {
  log.push(msg)
  out count = log.length()
}

in go: exec
var last: int = 0

on Note("hello", exec = go) -> (count) {
  last = count
}

If the callee has no exec-typed output for on to auto-extract — a plain value-only call with no exec = ... — that’s WS043. See Exec Chips for how exec = ... and the resulting .exec field work on user-defined chips/mods.

Triggering on Input Ports

in trigger: exec

on trigger {
  count = count + 1
}

Triggering on Boolean/Pulsing Values

Any bool, int, float, or vector value can trigger a handler when its value changes:

chip let moved = position != position.prev

on moved {
  // Fires whenever the 'moved' signal transitions
}

Triggering on Arbitrary Expressions

The trigger can be any expression, not just a bare name — a comparison, a method or index result, or a builtin call. It desugars to a hidden let bound to the expression, and the handler fires when that value changes:

on health <= 0 { respawn() }            // comparison
on a.Dot(b) > 0.0 { faceTarget() }      // method call inside the expression
on arr[i] > 0 { ... }                   // index result
on ServerUptime() > 5.0 { ... }         // builtin call in an expression

A builtin call that returns an exec (on ServerUptime(), on Change(v)) fires the handler on that exec — distinct from an event with config args (on Clock(...)), whose name resolves as an event and keeps its config form.

Triggering on Let Bindings and Buffers

let signal = someExpression

on signal {
  // Fires when signal changes
}

Triggering on Chip Result Execs

A chip call result’s exec fields work as triggers — including the exec completion field returned by a call with an exec = ... trigger (see Exec Chips):

let r = InitTables(exec = reset)

on r.exec {
  // Fires after the chip body ran
}

Negated Triggers

Prefix a trigger with ! to trigger on the negation (falling edge for booleans):

on !running {
  // Fires when 'running' becomes false
}

Union Triggers

To fire a handler on any of several execs, prefer the Union(...) builtin — it reads as an ordinary call in the unified on <expr> model and composes with -> output capture and exec = inputs:

on Union(eventA, eventB) {
  // Fires on either exec
}

The older | trigger-union syntax still parses but is discouraged in favor of Union(...):

on eventA | eventB {   // deprecated — use `on Union(eventA, eventB)`
  // Fires on either event
}

Field Triggers

Trigger on a field of an object using dot notation:

on obj.field {
  // Fires when obj.field changes
}

let on – Event Declaration

Event declarations create named triggers using let ... = on .... The event keyword is also accepted as a legacy alias.

Event Alias

Creates a new name for an existing event or trigger:

let died = on CharacterDied()

The alias can then be used as a trigger:

on died(character) {
  // ...
}

Captured Event

Wraps a trigger with a handler body that defines the event’s behavior:

let bumped = on Bumped {
  // This body executes when Bumped fires
  // 'bumped' becomes a trigger in its own right
}

emit – Emit Signal

Fires an exec signal to an output port or local exec signal. Bare emit requires exec context; emit target = expr also works in pure context.

emit eventName              // bare exec signal (exec context only)
emit sig = value            // fire a signal carrying a value (payload for `await`)

out scored: exec

on CharacterDied() -> (c) {
  score = score + 1
  emit scored
}

on scored {
  DisplayText(ctrl, "Score!", fontSize = 24)
}

Setting an output value

To set a data output’s value, use out name = value (in a handler or a chip/mod body) or return value (a single-output mod). emit is for exec signals, not data — don’t use it to assign a plain output.

out result: int

on trigger {
  out result = computed_value    // set the output's value
}

The emit name = value form is reserved for carrying a payload alongside an exec signal — a local signal you later await (see below): it fires the signal and ferries the value, so use it only when you actually want the exec to route.

Local Exec Signals

let name: exec declares a local synchronization point that can be targeted by emit and used with await or on:

let ready: exec

on compute { emit ready }      // fires the signal
on start { await ready }        // continues when ready fires

Buffered Emit

buffer emit sig routes the emit’s exec through a Buffer gate, delaying delivery by one tick. This is the tick-crossing barrier that makes emit/await loops legal: a back-edge emit after an await closes a wire-graph cycle, and every cycle must cross a Buffer or the compile errors (WS005).

buffer emit loop            // 1 tick (default)
buffer(3) emit loop         // 3 ticks (BufferTicks)
buffer(0.5s) emit loop      // 0.5 seconds (BufferSeconds)
buffer(d) emit loop         // variable delay — wired into TicksToWait
buffer(0, 1s) emit sig      // delay 0, hold output 1s after the input drops

• The first duration is the delay (TicksToWait / SecondsToWait); the optional second is the hold (ZeroTicksToWait / ZeroSecondsToWait — how long the output stays up after the input drops; omitted = -1 = same as delay).
• An s suffix selects the seconds gate; unadorned durations are ticks.
• Constant durations bake into the gate; variables/expressions wire into the duration port.

Payload Ferrying

emit sig = value on a local exec signal ferries the value with the signal: each emitted value is written into a hidden per-signal store var on the emit chain, and await sig reads it back on the resumed chain — so the value survives the buffered tick crossing.

let loop: exec

emit loop = 0                        // scalar payload
let index = await loop               // read it back

emit loop = { sum: 0, index: 0 }     // record payload: one store per field
let { sum, index } = await loop      // destructure the fields

Loops

emit/await on a local signal plus a buffered back-edge forms a loop that advances one iteration per buffer period. Loop state can live in vars (they persist across iterations; non-static vars reset on the entry chain, once per call):

mod sumItems(arr: int[]) -> int {
  var sum = 0
  var index = 0
  let loop: exec
  emit loop
  await loop
  if index < arr.length() {
    sum += arr[index]
    index += 1
    buffer emit loop        // back-edge: crosses 1 tick, re-arms the await
  } else {
    return sum
  }
}

or ride the signal as a ferried payload (no mutable vars):

mod sumItems(arr: int[]) -> int {
  let loop: exec
  emit loop = { sum: 0, index: 0 }
  let { sum, index } = await loop
  if index < arr.length() {
    buffer(1) emit loop = { sum: sum + arr[index], index: index + 1 }
  } else {
    return sum
  }
}

Semantics worth knowing:

• An emit on the same exec chain as an unconditional await of that signal is sequenced through a Var_Set(armed = true) before entering the signal’s union — so the awaiting Var_Get can never race the arm, and a loop back-edge re-arms the await every iteration.

• Emits from other handlers enter the signal directly and are guarded by the armed flag: the continuation only runs if the awaiting chain has reached the await.

• An await inside an if branch keeps pure flag semantics (its arm only fires when the branch is taken).

• A back-edge loop whose await sits inside an if runs exactly ONE iteration. This follows from the rule above and is the single easiest way to write a loop that looks fine and is not. The first pass consumes the arm; the buffered back-edge arrives on the next tick, finds the branch untaken and the await unarmed, and the continuation never runs. There is no error, no warning, and no hang - the program carries on with one iteration’s worth of work done, so a loop meant to fill 25 entries leaves 1.

  Measured, same loop body both ways: 5 of 5 iterations with the await at its handler’s top level, 1 of 5 with it inside a branch.

  This bites hardest when a loop lives in a mod called from a step machine, because the mod inlines into the caller and inherits its branch:

  // BROKEN - the call site puts the await inside an `if`
  on tick {
    if step == 4 { fill() }        // fill()'s await inlines into this branch
  }
  
  // WORKS - the await is at its own handler's top level
  let fillSig: exec
  on fillSig {
    idx = 0
    let loop: exec
    emit loop
    await loop
    if idx < 25 { dest.push(idx) idx += 1 buffer emit loop }
  }
  on tick {
    if step == 4 { emit fillSig }  // pulse it instead of calling it
  }
  

  The if guarding the loop’s own continuation (if idx < 25) is fine and required - it is the exit test. What must not be branched is the await itself.

• Loop state must outlive the tick. A back-edge buffer crosses a tick, and a tick is a new call of whatever handler the loop sits in - so a non-static var declared inside the loop’s own scope is reset before the next iteration reads it. A counter declared there sticks at its initial value forever, and the loop rewrites element 0 on every pass while looking like it is running. Put the counter (and any accumulator) at module level, or make it static, and reset it upstream of the emit:

  var idx: int = 0          // module level: survives the tick boundary
  
  mod fill(dest: int[]) {
    idx = 0                 // reset BEFORE the emit, not inside the loop body
    let loop: exec
    emit loop
    await loop
    if idx < 25 {
      dest.push(idx)
      idx += 1
      buffer emit loop
    }
  }
  

  The failure is silent: the program runs, the loop terminates, and the collection simply holds one element.

• A loop advances one iteration per tick. The back-edge is a buffer, and a buffer crosses a tick, so walking N elements takes N ticks. That is fine for work that runs once (a reset sweep, a one-off rebuild) and wrong for work that has to happen every tick for every element: a per-tick sweep over a roster of N costs N ticks per pass and degrades as the roster grows. When you need per-tick work per entity, give each entity its own chip instance instead of looping a central one – see per-entity fan-out.

Gate Cost

await – Suspend Exec Chain

Suspends the current exec chain and resumes from the awaited expression’s exec output. Everything after the await runs when that exec fires. Only valid in exec context.

await signal                         // resume when signal fires
let val = await signal               // capture the signal's ferried payload
let { a, b } = await signal          // destructure a record payload
let val = await value on trigger     // capture value when trigger fires
let n: int = await CustomEvent("c")  // wait for an event, capture its data
await a || b                         // race -- first signal wins
await Sleep(_, delay = 1.0)          // sleep 1 second using _ armed flag
await SleepTicks(_, delay = 5)       // sleep 5 ticks

Each await creates an armed flag (static var bool) that guards the continuation. The continuation only fires once per arming, preventing repeated triggers.

Awaiting a Custom Event

await CustomEvent("chan") (or GlobalCustomEvent) suspends until a matching SendCustomEvent fires, and a binding captures its data:

in go: exec
var last: int = 0
on go {
  let amount: int = await CustomEvent("dmg")   // resume + capture DataOut1
  last = amount
}

Annotate the binding’s type (let amount: int = ...): the event’s data ports are untyped in-game, so the annotation is what makes the wire carry the right variant. Without it the value defaults to a float and mis-delivers non-float data (WS055). A tuple let (p, t) = await CustomEvent("c") captures the data outputs positionally (p = DataOut1, t = DataOut2) but has no place to annotate them, so prefer one typed binding per value, or the handler form on CustomEvent("c") -> (p: int, t: float) { ... } when you want several typed at once. A bare await CustomEvent("c") with no binding just waits for the event.

The _ Placeholder

Inside an await expression, _ refers to the await’s armed flag – a bool that becomes true when the exec chain reaches the await point. Use _ with Sleep/SleepTicks to wire the armed flag as the buffer gate’s input:

on start {
  doSetup()
  await SleepTicks(_, delay = 60)  // _ = armed flag, delayed 60 ticks (~1s)
  doAfterDelay()                    // runs after the delay
}

Sleep / SleepTicks

Sleep(input, delay, hold) and SleepTicks(input, delay, hold) are buffer gates that delay a value passing through.

• input – the value to delay (use _ for the await armed flag)
• delay – how long to wait before the output follows the input (optional)
• hold – how long to hold the output after the input drops to zero (optional, set to -1 to use delay instead)

Examples

in start: exec
in done: exec
var count: int = 0

on start {
  count = 1
  await done          // exec chain pauses here
  count = 2           // runs when 'done' fires
}

// Capture a value when a signal fires
on start {
  let val = await score on done
  use(val)
}

// Sleep for 2 seconds
on start {
  await Sleep(_, delay = 2.0)
  count = 99
}

Assignment

Assigns a new value to a mutable variable. Requires exec context.

target = expression

on RoundStart() {
  count = count + 1
  score = 0
  name = "Player " .. playerId
}

Only var declarations are valid assignment targets. Attempting to assign to a let binding, parameter, or other non-variable produces a type error.

Indexed assignment works for arrays:

on trigger {
  scores[i] = newScore
}

Compound Assignment

Compound assignment operators combine an operation with assignment:

+= compiles to the dedicated IncVar gate (one gate instead of three). All others desugar to x = x OP expr (Var_Get + operation + Var_Set).

on tick {
  counter += 1       // IncVar gate
  health -= damage   // Var_Get + Sub + Var_Set
  mask &= 0xFF       // Var_Get -> BitAnd -> Var_Set
  bits <<= 1         // Var_Get -> Shift -> Var_Set
}

Expression Statement

Any expression can be used as a statement. This is primarily useful for calling exec functions that have side effects:

on RoundStart() {
  DisplayText(ctrl, "Round Started!", fontSize = 30)
  SetLocation(entity, newPos)
}

Built-in Events

These events are available as handler triggers. Parameters listed can be bound using the on Event() -> (param) tuple capture (or -> { field: local } record capture) — see Binding Event Data.

return

The return statement terminates the current exec chain early. It can be used inside:

• on handlers
• chip on handlers
• if blocks within handlers
• mod bodies (when called from exec context)

on RoundStart() {
  if score > 100 {
    return  // skip the rest of this handler
  }
  score = score + 1
}

chip on CharacterDied() -> (character) {
  lives = lives - 1
  if lives <= 0 {
    return  // don't process further
  }
  health = 100
}

mod process(v: *int) {
  if v < 0 { return }  // early exit from mod
  v = v * 2
}

return expr – Return with Value

For mods with a single output (declared with -> (name: type)), return expr sets the output value and exits:

mod clamp(v: int, lo: int, hi: int) -> (result: int) {
  if v < lo { return lo }
  if v > hi { return hi }
  return v
}

let clamped = clamp(x, 0, 255)  // clamped is directly an int

Single-output chips and mods auto-unwrap: let f = Foo(5) gives f the output type directly (e.g. int), no .result field access needed.

How Multiple Returns Compile

A single return expr wires the value directly to the output port (pure, zero-tick).

When a mod has multiple return expr statements, the compiler inserts a variable to hold the return value. Each return expr becomes a Var_Set before jumping to the return union, and a Var_Get after the union reads the result. This means multi-return mods have a one-tick latency on the return value (the var write is visible on the next tick for pure reads, but available immediately for subsequent exec-chain reads via Var_Get).

return is not allowed in pure context (outside exec chains).

Chips

Chips are Wirescript’s primary mechanism for organizing and reusing wire graph logic. They map to physical microchip bricks in Brickadia – a separate grid of gates contained within a single brick. (A module-level @flat compiles the same program onto one grid instead, with no microchip bricks at all.)

Contents

• Anonymous Chips
• Named Chips
• const Parameters and const mod
• Open and Closed Chips
• Compiling Without Microchips (@flat)
• Chip Labels and Headers
• mod – Inline Chips
• Boundary Pins
• Nested Chips
• Inline mod with Mixed Parameters
• Complete Example: Named Chip with Handlers

Anonymous Chips

An anonymous chip creates a physical microchip for visual organization while sharing the parent scope. Variables, buffers, and arrays declared inside an anonymous chip are accessible from outside it (and vice versa).

Basic Anonymous Chip

chip {
  var x: int = 0
  var y: int = 0

  on trigger {
    x = x + 1
  }
}

// x and y are accessible here because anon chips share parent scope
out xValue = x.Value

Anonymous chips are purely organizational – they group related gates into a microchip brick without creating an isolated scope.

open Modifier

Chips compile open by default now (see Open and Closed Chips below), so the open keyword is a redundant no-op kept for backward compatibility:

open chip {
  var state: int = 0
  // ...
}

chip let – Compact Let Bindings

chip let is shorthand for an anonymous chip containing one or more let bindings, separated by commas:

chip let score = c0 + c1 + c2 + c3
chip let doubled = score * 2, halved = score / 2

// Equivalent to:
chip {
  let score = c0 + c1 + c2 + c3
}
chip {
  let doubled = score * 2
  let halved = score / 2
}

This is commonly used to wrap pure computations in their own microchip for layout clarity.

// From the 2048 example -- each chip let gets its own microchip
chip let moved = c0 != c0.prev || c1 != c1.prev || c2 != c2.prev
chip let score = c0 + c1 + c2 + c3 + c4 + c5
chip let emptyCount = (if c0 == 0 then 1 else 0) + (if c1 == 0 then 1 else 0)

chip on – Compact Handler

chip on is shorthand for an anonymous chip containing a single handler:

chip on trigger {
  count = count + 1
}

// Equivalent to:
chip {
  on trigger {
    count = count + 1
  }
}

This is the most common pattern for associating a handler with its own microchip:

chip on goLeft {
  slide(c0, c1, c2, c3)
  slide(c4, c5, c6, c7)
}

chip on goRight {
  slide(c3, c2, c1, c0)
  slide(c7, c6, c5, c4)
}

Negated and Combined Triggers in chip on

All trigger forms work with chip on:

// Negated trigger
chip on !running {
  DisplayText(ctrl, "Game Over", fontSize = 48)
}

// Regular trigger
chip on moved {
  // ...
}

Named Chips

Named chips define reusable components with explicit inputs and outputs. They create an isolated scope – the chip body cannot see the parent scope’s variables (except what is passed through parameters).

chip Name(params) -> outputs {
  // body
}

Basic Named Chip

chip Counter(bump: exec, reset: exec) -> (value: int, overflow: bool) {
  var n: int = 0

  on bump {
    n = n + 1
  }

  on reset {
    n = 0
  }

  out value = n.Value
  out overflow = n > 255
}

Parameters

Parameters are declared as name: type pairs in parentheses:

chip Adder(a: int, b: int) -> (sum: int) {
  out sum = a + b
}

Destructured Parameters

Parameters can destructure record or tuple values directly in the signature, using the same { field, ... }: Type syntax as let destructuring. This is most useful for mod declarations that work with record types:

// Destructured parameters — fields are directly in scope in the body
mod distance({ x, y }: Point) -> int { return x + y }
mod process({ data, ...opts }: Config) { ... }

Each destructured name is bound directly, just as if written let { x, y } = param at the start of the body. The synthetic parameter name (_p0, _p1, …) is generated by the compiler and is not accessible in the body.

Tuple destructuring is also supported:

mod sum((a, b): (int, int)) -> int { return a + b }

Outputs

Outputs are declared after ->. A single output can omit the parentheses — it defaults to the name _:

// Single output (defaults to name "_")
chip Double(x: int) -> int {
  out _ = x * 2
}

// As a mod with return
mod Double(x: int) -> int {
  return x * 2
}

// Single-output chips auto-unwrap: f is directly an int
let f = Double(21)    // f == 42, no .result needed

// Multiple named outputs (still use record access)
chip MinMax(a: int, b: int) -> (min: int, max: int) {
  out min = if a < b then a else b
  out max = if a > b then a else b
}
let mm = MinMax(3, 7)  // mm.min == 3, mm.max == 7

Exec Outputs

Chips can have exec-typed outputs for signaling completion. Use out name: exec in the signature and emit name inside a handler:

chip Counter(bump: exec) -> (value: int, done: exec) {
  var n: int = 0
  on bump {
    n = n + 1
    emit done
  }
  out value = n.Value
}

Using Named Chips

Call named chips like functions. Each call creates a new physical microchip instance with independent internal state:

chip Double(x: int) -> int {
  out _ = x * 2
}

let result = Double(21)  // result = 42

// Multi-output chips return a record — access fields by name
chip MinMax(a: int, b: int) -> (min: int, max: int) {
  out min = if a < b then a else b
  out max = if a > b then a else b
}

let mm = MinMax(3, 7)
let lo = mm.min  // 3
let hi = mm.max  // 7

// Multiple calls create separate instances
let mm1 = MinMax(1, 10)
let mm2 = MinMax(5, 20)  // independent from mm1

Note: The -> (...) outputs declare the chip’s public interface. Use out name = expr in the body to wire values to those outputs. Do not redeclare the same name in both the signature and the body — this produces a warning.

Exec Chips

A chip whose body contains statement-level exec calls (array methods, DisplayText, emit signal, …) is an exec chip — the body runs as one exec chain. How it gets its trigger depends on the call site:

• Called inside a handler, the body joins the caller’s exec chain automatically and execution continues after it.
• Called outside an exec context (e.g. a top-level let), pass the trigger as an exec = ... named argument — the same convention as builtin exec calls like Random(0, 10, exec = trigger).

in reset: exec

var vals: int[]

chip InitTables() -> (count: int) {
  vals.clear()
  vals.push(1)
  out count = 1
}

let t = InitTables(exec = reset)  // body runs whenever reset fires

A call with exec = also returns the chip’s completion exec as an exec field on the result record (unless the chip declares its own exec output), so callers can sequence on the body having run:

on start {
  emit reset
  await t.exec       // resumes after InitTables finished
}

on t.exec { }        // or treat it as an event

To bind body work to a specific exec parameter instead, declare the param and use an on handler — the param does not implicitly invoke the body:

chip Counter(bump: exec) -> (value: int) {
  var n: int = 0
  on bump { n = n + 1 }
  out value = n.Value
}

Note: chip bodies reference top-level vars, arrays, buffers, and record bindings freely — wire refs cross chip boundaries, so the body’s gates connect to the outer nodes directly (vals above).

Reference Parameters (ref T / *T)

When a chip parameter has type ref T (or equivalently *T), the caller passes a variable by reference. The chip can both read and write the variable.

chip Increment(counter: ref int, amount: int) {
  on trigger {
    counter = counter + amount
  }
}

When a chip has ref parameters, its body is automatically placed in exec context (because ref access implies mutable state operations).

The *T syntax is an alternative shorthand:

// These declarations are equivalent:
chip Swap(a: ref int, b: ref int) { ... }
chip Swap(a: *int, b: *int) { ... }

At call sites, pass variables directly – the compiler handles the reference wiring:

var x: int = 10
var y: int = 20
Swap(x, y)  // x and y are passed by reference

const Parameters and const mod

A mod or chip parameter can be marked const, requiring the caller’s argument to be a compile-time constant. Inside the body the parameter reads as one – usable anywhere a const binding is (see const – Compile-Time Binding):

mod ping(channel: const string, v: int) {
  SendCustomEvent(channel, v)
}

in go: exec
var hp: int = 0
on go { ping("died", hp) }   // "died" bakes as the event's channel name

A non-constant argument in a const slot is WS046:

in name: string
mod ping(channel: const string) { SendCustomEvent(channel) }
on go { ping(name) }   // WS046 -- 'name' is a runtime value

v above stays an ordinary wired parameter – a mod/chip can freely mix const and non-const parameters. A const parameter costs no pin: it never becomes a MicrochipInput, so it doesn’t shift the pin index of any parameter that follows it. For a chip (not a mod), each distinct constant value passed to a const parameter gets its own compiled instance – two call sites passing the same constant share one instance, since the body is cached by a template key that includes the const value.

const mod

const mod marks every parameter of an inlined chip const in one step – equivalent to writing const on each parameter individually:

const mod double(n: int) -> int { return n * 2 }

A call to a const mod is itself const-evaluable (see What’s const-evaluable), so it can be used to build a const value out of one or more calls – including calls to other const mods and reads of module-level constants.

const chip is a parse error – a chip compiles to one shared physical microchip template reused across call sites, so “every parameter is const” isn’t a property the declaration can have the way it is for an inlined mod. Mark the parameters you need constant individually instead:

const chip C(v: int) -> (r: int) { out r = v }   // error -- use a mod, or const params

chip C(name: const string, v: int) -> (r: int) { out r = v }   // fine

A const BINDING inside a named chip’s body is compile-time throughout that chip – its handlers, its outs, and its constant-only config slots – the same as inside a mod. Two places it is not: the body of an anonymous chip { }, and a chip declared inside another chip, which does not inherit the enclosing chip’s body constants (pass them in as const parameters). Both are reported rather than silently dropped; see Where const is allowed.

A const mod may declare multiple outputs, and its result destructures exactly as an ordinary multi-output mod’s does. One rule is const-specific: the wire graph keeps whichever assignment to an output comes FIRST in source order, so a valued return placed after an out to the same output would disagree with it, so it is rejected (WS046) rather than shipping a mismatch.

const mod pick(n: const int) -> (r: int) {
  out r = 111
  if n > 0 { return 222 }   // WS046 -- disagrees with the wire graph
}

The mixed-parameter macro pattern

Because const and ordinary parameters mix freely, a mod can behave like a small macro that both configures a gate at compile time and wires a runtime value through it in the same call:

mod tagged(label: const string, amount: int) {
  SendCustomEvent("evt_" .. label, amount)
}

in go: exec
var score: int = 0
on go {
  tagged("score", score)   // "evt_score" bakes; score stays a live wire
}

const if and tree-shaking

An if whose condition is const-evaluable is resolved at compile time: the taken branch is checked and lowered normally, and the untaken branch is dropped before type-checking ever looks at it.

const MODE = 1
var x: int = 0
in go: exec

on go {
  if MODE == 1 {
    x = 1
  } else {
    x = someModeTwoOnlyFunction()   // never type-checked -- MODE is always 1
  }
}

This is what lets one mod/chip serve call sites that share no common API: a branch that wouldn’t even compile for a given constant value is simply never checked for it. The editor’s hover on a dropped block explains why it was dropped (e.g. `MODE == 1` is true here).

This does not work for a const parameter. A mod/chip body is type-checked exactly once, before any call site exists – there is no real argument yet to decide the branch with. A const parameter is seeded with a type-shaped placeholder during that one-time check, and the placeholder is deliberately never allowed to decide a branch: letting it choose would ship a branch the placeholder happened to select while the OTHER branch – the one a real call actually takes – goes unchecked. So both branches of an if on a const parameter (or a const derived from one) are type-checked, and each must be independently valid code, even though only one of them lowers per call site:

var x: int = 0

mod f(mode: const int) {
  if mode == 1 {
    x = 1
  } else {
    x = someOtherModesFunction()   // IS type-checked, even if every call site passes mode = 1
  }
}

Both arms must compile for every possible constant value, not just the ones any call site actually passes. A top-level const – or one read from inside a mod body that is not itself a parameter – does not have this restriction; only the parameter itself, and anything derived from it, carries the placeholder.

Open and Closed Chips

Non-root chips compile open by default: each chip’s inner grid renders as an upright plane facing the same side of the chip as its @bottom rerouter pins, stacked in a wall above the placed microchip brick. The root module’s plane sits at the bottom, its bottom edge just above the brick; directly-nested chips occupy a row above it; deeper nesting stacks higher still. Rows are centred and packed side by side, ordered first by parent position, then by source order within a parent. Within a plane the dataflow axis runs bottom-to-top: input gates sit at the bottom edge, outputs at the top.

Annotate a chip with @closed to collapse it instead. A closed chip still reserves its slot in the wall, so opening it later in-game reveals it in place:

@closed chip Counter(bump: exec) -> (value: int) {
  var n: int = 0
  on bump { n = n + 1 }
  out value = n.Value
}

@closed chip {
  var scratch: int = 0
}

@closed works on every chip form – chip Name(...), chip { ... }, chip on, and chip let. open chip { ... } still parses, but is now a redundant no-op; combining @closed with open on the same chip is an error.

Compiling Without Microchips (@flat)

A module-level @flat at the top of the entry file inlines every chip body into the module that instantiates it. The program then emits no microchip bricks and no nested grids – every gate lands on one grid, and a wire that would have crossed a chip wall becomes an ordinary same-grid wire instead of a pair of wires through a boundary pin.

Nothing about the program’s behavior changes. A chip is not a scoping or timing boundary, so a flattened program computes exactly what the nested one did; what goes away is the tree of planes to open and the per-crossing pin.

Because the microchip brick and its plane no longer exist, @closed and @label have nothing to describe under @flat. They are inert rather than an error, so a file can be compiled both ways without editing its chips.

See Statements for @flat’s placement rules and how it composes with @layout(...).

Chip Labels and Headers

@label("text") overrides the display text on a chip’s shell-brick label and its plane header:

@label("Score Tracker") chip {
  var score: int = 0
}

@label also applies to in/out declarations at any nesting level, and stacks with a @left/@right/@top/@bottom side annotation in either order – see Outer Rerouter Pins. There it overrides the port’s floating display label (and its rerouter pin label); the port’s wiring-UI name is unaffected either way.

The @label argument may also be an expression: a constant folds to baked text, and on a top-level var a runtime expression becomes a dynamic label that shows the value live – see Expression labels. A chip label must be a constant (its shell brick has no wired text component).

Each opened plane with a title or doc comment gets a header at its top edge: the title rendered as <size="96">...</>, with the chip’s /// doc comment on the line below. The title is the chip’s @label text if present, otherwise its name (the root chip’s title is the module name); an anonymous, undocumented chip gets no header at all. Header text is passed through raw, so rich-text tags inside a name or doc comment render as rich text:

/// Counts ticks forever.
chip Counter(bump: exec) -> (value: int) {
  var n: int = 0
  on bump { n = n + 1 }
  out value = n.Value
}

mod declarations always inline into their callers and never become a physical chip, so any annotation – @closed, @label, or a side pin – on a mod is an error.

mod – Inline Chips

The mod keyword declares a chip that is always inlined at call sites. Instead of creating a separate microchip brick, the mod’s gates are expanded directly into the caller’s grid.

mod Name(params) {
  // body -- no output
}

mod Name(params) -> (result: type) {
  // body -- single output, use `return expr` to set it
}

Mod Outputs and return value

Mods can declare a single output with -> (name: type). Use return expr to set the output and exit:

mod clamp(v: int, lo: int, hi: int) -> (result: int) {
  if v < lo { return lo }
  if v > hi { return hi }
  return v
}

let clamped = clamp(x, 0, 255)  // clamped is directly an int

Note: A single return expr wires the value directly (pure, zero-tick). Multiple return expr statements cause the compiler to insert a hidden variable — each branch does a Var_Set, and a Var_Get after the return union reads the result. This adds exec gates but is correct within the same tick’s exec chain.

When to Use mod

Use mod when:

• You want to reuse logic without the overhead of a physical microchip
• The logic is small and called many times
• You need the expanded gates visible in the parent grid

mod slide(a: *int, b: *int, c: *int, d: *int) {
  if a == 0 { a = b; b = c; c = d; d = 0 }
  if b == 0 { b = c; c = d; d = 0 }
  if c == 0 { c = d; d = 0 }
  if a == b { a = a + b; b = 0 }
  if b == c { b = b + c; c = 0 }
  if c == d { c = c + d; d = 0 }
}

Variadic Parameters (...rest)

A mod (only a mod, never a chip) can end its parameter list with a ...rest variadic that captures every argument past the fixed parameters. Because a mod is inlined at each call site, rest is a compile-time tuple of the actual extra arguments – there is no runtime variadic. A ...rest in the body then splats that tuple onward into another call, one element per positional slot:

mod broadcast(name: const string, ...rest) {
  SendGlobalCustomEvent(name, ...rest)
}

in amount: int
in kind: float
in go: exec
on go {
  broadcast("hit", amount, kind)   // -> SendGlobalCustomEvent("hit", amount, kind)
}

The fixed parameters are still required (passing fewer is an arity error); only the trailing count is open. The same ...tuple splat works on any call – spread a bound tuple, a tuple literal, or a multi-output result into consecutive arguments:

mod add3(a: int, b: int, c: int) -> (r: int) { return a + b + c }

in n: int
let pair = (2, 3)
out total = add3(n, ...pair)         // -> add3(n, 2, 3)

Because the body is type-checked once (at the declaration, where the captured arity isn’t known yet), a ...rest forward is not statically arity-checked against a fixed-arity target – it is validated when the mod inlines at each call. Forwarding into SendCustomEvent/SendGlobalCustomEvent (whose data slots accept any type) is the common case and always sound.

mod vs chip

mod declarations do not support output declarations with ->. Instead, their effect is through mutating ref parameters.

Boundary Pins

Every wire that crosses a chip wall – a value, an exec trigger, or a variable reference alike – routes through a labeled MicrochipInput or MicrochipOutput rerouter at that wall, one pin per external source, even if the source isn’t a declared parameter. Multiple consumers inside the chip fan out from the same pin rather than each getting their own. A constant argument is the one exception – it’s inlined directly into the gate that uses it rather than wired in, so it never costs a pin.

Nested Chips

Chips can be nested inside handler bodies and other chip bodies:

on trigger {
  chip {
    // This anonymous chip is inside the handler
    let localCalc = a + b
    // ...
  }

  chip {
    // Another chip in the same handler
    if condition { x = localCalc }
  }
}

Nested anonymous chips still share their enclosing scope. Named chip declarations inside blocks create locally-scoped chip types.

// From the 2048 example -- deeply nested chips
if running && moved {
  chip {
    chip {
      let b0 = 0
      let b1 = b0 + if c0 == 0 then 1 else 0
      // ...
    }
    let r = Random(0, emptyCount - 1)
    chip {
      let p0 = c0 == 0 && r == b0
      // ...
    }
    chip {
      if p0 { c0 = 2 }
      // ...
    }
  }
}

Inline mod with Mixed Parameters

A mod can take both reference and value parameters. Value parameters are pure inputs; reference parameters allow mutation:

mod renderCell(c: *int, tid: *int, p: bool, px: float, py: float) {
  let t = if p || c == 0 || c == c.prev then 0.0 else 0.15
  let bucket = if c <= 4 then 0
    else if c <= 16 then 1
    else if c <= 64 then 2
    else 3
  let col = Fmt('{' .. bucket .. '}', 'eee4da', 'f2b179', 'f65e3b', 'edcf72')
  let txt = '<color="${col}">${c}</>'
  DisplayText(ctrl, txt, positionX = px, positionY = py, fontSize = 40, transition = t, textId = tid)
}

Complete Example: Named Chip with Handlers

chip Timer(tick: exec, reset: exec, limit: int) -> (value: int, expired: bool) {
  var elapsed: int = 0

  on tick {
    if elapsed < limit {
      elapsed = elapsed + 1
    }
  }

  on reset {
    elapsed = 0
  }

  out value = elapsed.Value
  out expired = elapsed >= limit
}

Built-in Functions

Wirescript provides built-in functions that map directly to Brickadia wire graph gates. Each function is either pure (returns a value, no exec context needed) or exec (requires exec context and chains into the current execution flow).

Contents

• Notation
• Math / Trigonometry (Pure)
• Bitwise (Pure)
• Vector (Pure)
• Rotation / Quaternion (Pure)
• Color (Pure)
• Stateful Exec Values
• Select / Swap (Pure)
• Edge / Change Detectors
• Logical XOR (^^)
• String Operations (Pure)
• String Formatting (Pure)
• Array Methods (Exec)
• Player Input (Exec)
• Controller / Character Conversions (Exec)
• Camera / Aim (Exec)
• Display (Exec)
• Entity Getters (Exec)
• Entity Manipulation (Exec)
• Gamemode (Exec)
• Character (Exec)
• Controller (Exec)
• Broadcast Messaging (Exec)
• Audio (Exec)
• Entity Tags (Exec)
• Misc (Pure / Exec)
• Gate config properties
• Clock (Event)
• ChatCommand (Event)
• Custom Events
• Prefab Spawning (Exec)
• Raycasting (Exec)
• Random (Exec)
• Sleep / Delay (Pure)
• Exec Override
• Newer builtins
• Generic type syntax
• Maps (var m: Map<K, V>)
• Exec-flow gates (Union / Branch)
• Callable gate builtins

Notation

• Pure functions are expressions – they produce a value and can be used anywhere.
• Exec functions require an active exec context (inside an on handler). They are called as statements or in exec expressions.
• Parameters marked with ? are optional.

Receiver Method Syntax

Many functions support receiver method syntax, where the first parameter is written before the dot instead of as a positional argument. Both forms are equivalent:

// Receiver form (preferred)
entity.SetLocation(pos)

// Traditional form
SetLocation(entity, pos)

Functions that support receiver syntax show both forms in the documentation below.

Math / Trigonometry (Pure)

All trig functions take and return float. Angles are in radians unless converted.

let angle = atan2(dy, dx)
let clamped = clamp(value, 0.0, 1.0)
let dist = sqrt(dx * dx + dy * dy)
let radians = Deg2Rad(90.0)

Bitwise (Pure)

Note: ~(a & b) and ~(a | b) are automatically fused into single NAND/NOR gates by the compiler.

let bits = BitCount(flags)

Vector (Pure)

Vector Receiver Methods

DistanceSq, MagnitudeSq, and RotToDir support receiver syntax on vector:

// Receiver form
let dsq = a.DistanceSq(b)
let msq = v.MagnitudeSq()
let dir = rot.RotToDir()

// Traditional form
let dsq = DistanceSq(a, b)
let msq = MagnitudeSq(v)
let dir = RotToDir(rot)

let pos = Vec(1.0, 2.0, 3.0)
let dir = Normalize(target - origin)
let dist = Distance(posA, posB)
let scaled = ScaleVec(velocity, 0.5)

Rotation / Quaternion (Pure)

Two rotation types: rotator is euler (pitch/yaw/roll, used by entity rotation), quat is a quaternion produced by the conversion gates. Methods use the concise receiver form.

let q = forward.ToRotation()
let spun = velocity.Rotate(q)
let mid = a.Slerp(b, 0.5)
let r = Rotation(0.0, 90.0, 0.0)   // euler rotator
let yaw = r.ToEuler().Yaw

Color (Pure)

SplitColor, ToSRGB, ToHex, and ColorBlend support receiver syntax on color.

Blend is a different gate – the math blend (an alias for lerp), which takes colours as one of its variants but has no colour-space selection.

let red = Color(1.0, 0.0, 0.0)
let orange = ColorSRGB(255, 128, 0, 255)
let hex = orange.ToHex()
let parts = red.SplitColor()  // parts.r = 1.0, parts.g = 0.0, ...
let mixed = red.ColorBlend(orange, 0.5)

Stateful Exec Values

Select / Swap (Pure)

let bigger = Select(x > y, y, x)
let result = Swap(shouldSwap, left, right)
// result auto-unwraps to Output; result.Output and result.OutputB
// are swapped if shouldSwap is true

Edge / Change Detectors

Edge and Changed are pure: they produce a one-tick bool pulse (Rising on false→true, Falling on true→false; Changed on any change). EdgeExec and Change are their exec-flavored siblings — EdgeExec’s outputs fire exec chains directly (use with on/await, like Timer(...).Expired), and Change pulses the new value through whenever the input changes.

let edges = Edge(button)
on edges.Rising { count = count + 1 }

let health = EdgeExec(hp)
on health.Falling { ctrl.ShowStatusMessage("taking damage!") }

Logical XOR (^^)

The ^^ operator is boolean XOR — returns true if exactly one operand is true.

let either = a ^^ b  // true if a or b but not both

Note: !(a && b) and !(a || b) are automatically fused into single NAND/NOR gates.

String Operations (Pure)

let name = "Hello World"
let len = name.Length()              // 11
let has = name.Contains("World")     // true
let low = name.ToLower()             // "hello world"
let sub = name.Substring(6, 5)      // "World"
let parts = name.Split(" ")         // parts.Left = "Hello", parts.Right = "World"

String Formatting (Pure)

The Fmt function wraps the FormatText gate. The format string uses {0} through {6} placeholders corresponding to inputs a through g.

let label = Fmt("{0}: {1}", "Score", score)
let coords = Fmt("({0}, {1}, {2})", x, y, z)

// Also works for palette selection:
let col = Fmt('{' .. bucket .. '}', 'eee4da', 'f2b179', 'f65e3b')

Array Methods (Exec)

Methods on an array variable. All run in exec context (they lower to ArrayVar exec gates), so call them inside on handlers / mods. Declare arrays with var name: T[] (see statements).

The element type can be a record (var pts: Point[]): the array is stored as one parallel array per field and each method fans out. sort/shuffle, the aggregates, and the dual-array ops have no per-field meaning there and are rejected with WS050. See Records as storage.

Element access uses bracket syntax: arr[i] reads (with .value / .bOutOfBounds), arr[i] = x writes.

exec =. Any exec-gate call — an array method, a builtin, or a mod/chip call — accepts an exec = <trigger> argument that drives its exec input, firing the gate each time the trigger’s value changes. A per-index, always-nonzero trigger like index + 1 turns an array into a single-gate lookup table read straight from a pure binding:

var lut: color[] = [ /* ...constant entries... */ ]
out c: color = lut.get(i, exec = i + 1).Value

var scores: int[]
on RoundEnd() {
  scores.push(currentScore)
  scores.sort(true)          // descending
  let best = scores.max()
  let count = scores.length()
}

sortMultiple sorts the receiver and drags parallel arrays along, which is how you sort records by one field and keep the others attached:

var scores: Map<string, int>
var names: string[]
var points: int[]

in show: exec
on show {
  scores.keys(names)     // string[]
  scores.values(points)  // int[]
  points.sortMultiple(names)
  // points is sorted ascending and names[k] still owns points[k]
}

Sorting a copy and searching back with find is the alternative, and it ties duplicate values to whichever entry matched first.

Player Input (Exec)

InputReader

character.InputReader() -> { Forward, Right, Up, Pitch, Yaw, Roll, MouseWheel, PressedC, PressedE, PressedQ, PressedLeftMouse, PressedRightMouse }
InputReader(character: character) -> { ...same fields... }

Read player input axes and pressed keys. Receiver on character.

Returns a record with fields:

• Forward: float – forward/backward movement axis (-1 to 1)
• Right: float – left/right movement axis (-1 to 1)
• Up: float – up/down movement axis (-1 to 1)
• Pitch: float / Yaw: float / Roll: float – look axes
• MouseWheel: float – mouse wheel delta
• PressedC / PressedE / PressedQ / PressedLeftMouse / PressedRightMouse: bool – key/button states

let input = char.InputReader()
let moving = input.Forward != 0.0 || input.Right != 0.0
let interacting = input.PressedE

GetInputs

character.GetInputs() -> { ...same fields as InputReader... }
GetInputs(player: character) -> { ...same fields... }

Sample the same twelve controls once, at the point the exec chain reaches this call, rather than reading them continuously. The field names are identical to InputReader’s, so only the context differs. Its operand also accepts a persistent player, which wires straight into the character parameter.

Being exec form, it must sit on an exec chain; in pure position it reports WS007.

on Clock(interval = 0.1) {
  let input = char.GetInputs()
  if input.PressedQ { char.ShowStatusMessage("q") }
}

Controller / Character Conversions (Exec)

These functions convert between entity types. They require exec context and support receiver syntax.

ControllerOf

entity.ControllerOf() -> controller
ControllerOf(entity: entity) -> controller

Get controller from entity. Receiver on entity.

CharacterOf

controller.CharacterOf() -> character
CharacterOf(controller: controller) -> character

Get character from controller. Receiver on controller.

on CharacterSpawned() -> (character) {
  let ctrl = character.ControllerOf()
  ctrl.DisplayText("Welcome!", fontSize = 24)
}

Camera / Aim (Exec)

GetAim

character.GetAim() -> { Origin: vector, Direction: vector }
GetAim(character: character) -> { Origin: vector, Direction: vector }

Reads the character’s camera/aim in a single gate. Returns a record:

• Origin: vector — aim origin position
• Direction: vector — aim direction vector

Receiver on character. Access the fields with .Origin / .Direction; both share one gate, so reading both costs a single GetAim.

on trigger {
  let aim = char.GetAim()
  let origin = aim.Origin
  let dir = aim.Direction
}

Display (Exec)

DisplayText

target.DisplayText(text, ...) -> int
DisplayText(target: controller, text: any, ...) -> int

Display HUD text to a player. Receiver on controller. Returns the resolved textId (an int) so a later call can update or clear the same on-screen text.

The 2D layout ports are Vector2D composites, and the call feeds them one axis at a time: positionX / positionY, anchorX / anchorY, and so on, each a float. There is no vector-typed position or anchor – passing one is a WS041 error. A constant axis bakes into the parent Vector2D data field; a runtime value wires the matching sub-port. The call also exposes the scalar styling below, plus fontSize / justify / easing / typeface / font, which are constant-only data fields (not wire inputs).

DisplayText Parameters

on RoundStart() {
  ctrl.DisplayText("Round Start!", fontSize = 48, lifetime = 3.0)
}

// Update text in-place: capture the id, then re-display with the same textId.
on trigger {
  let id = ctrl.DisplayText("Score: ${score}", fontSize = 24, lifetime = 10.0)
  ctrl.DisplayText("Score: ${score}", textId = id, transition = 0.25)
}

Entity Getters (Exec)

All entity getter functions require exec context and support receiver syntax on entity.

GetLocation

entity.GetLocation() -> vector
GetLocation(entity: entity) -> vector

Get entity’s world position.

GetRotation

entity.GetRotation() -> rotator
GetRotation(entity: entity) -> rotator

Get entity’s world rotation.

GetLocationRotation

entity.GetLocationRotation() -> {Vector: vector, Rotation: rotator}
GetLocationRotation(entity: entity) -> {Vector: vector, Rotation: rotator}

Get both position and rotation at once.

GetLinearVelocity

entity.GetLinearVelocity() -> vector
GetLinearVelocity(entity: entity) -> vector

Get entity’s linear velocity.

GetAngularVelocity

entity.GetAngularVelocity() -> vector
GetAngularVelocity(entity: entity) -> vector

Get entity’s angular velocity.

GetVelocity

entity.GetVelocity() -> {Vector: vector, Rotation: rotator}
GetVelocity(entity: entity) -> {Vector: vector, Rotation: rotator}

Get both linear and angular velocity at once.

on trigger {
  let pos = entity.GetLocation()
  let rot = entity.GetRotation()
  let vel = entity.GetLinearVelocity()
}

Entity Manipulation (Exec)

All entity manipulation functions require exec context and support receiver syntax on entity.

SetLocation

entity.SetLocation(pos: vector)
SetLocation(entity: entity, pos: vector)

Set entity position. Use this (not Teleport) to move an entity to world coordinates. pos is a real vector port.

SetRotation

entity.SetRotation(rot: rotator)
SetRotation(entity: entity, rot: rotator)

Set entity rotation.

SetLocationRotation

entity.SetLocationRotation(pos: vector, rot: rotator)
SetLocationRotation(entity: entity, pos: vector, rot: rotator)

Set both position and rotation.

AddLocationRotation

entity.AddLocationRotation(pos: vector, rot: rotator)
AddLocationRotation(entity: entity, pos: vector, rot: rotator)

Add to position and rotation.

Teleport

entity.Teleport(dest: any)
Teleport(entity: entity, dest: any)

Teleport entity to destination.

RelativeTeleport

entity.RelativeTeleport(source: any, dest: any)
RelativeTeleport(entity: entity, source: any, dest: any)

Relative teleport between two points.

SetVelocity

entity.SetVelocity(linear?: vector, angular?: vector)
SetVelocity(entity: entity, linear?: vector, angular?: vector)

Set velocity. Both linear and angular are optional – pass whichever components you want to set.

AddVelocity

entity.AddVelocity(linear?: vector, angular?: vector)
AddVelocity(entity: entity, linear?: vector, angular?: vector)

Add to velocity. Both linear and angular are optional.

SetLinearVelocity

entity.SetLinearVelocity(vel: vector)
SetLinearVelocity(entity: entity, vel: vector)

Set linear velocity only.

SetAngularVelocity

entity.SetAngularVelocity(vel: vector)
SetAngularVelocity(entity: entity, vel: vector)

Set angular velocity only.

SetGravityDirection

entity.SetGravityDirection(rot: rotator)
SetGravityDirection(entity: entity, rot: rotator)

Set gravity direction for entity.

SetFrozen

entity.SetFrozen(frozen: bool)
SetFrozen(entity: entity, frozen: bool)

Freeze or unfreeze an entity’s physics.

on trigger {
  entity.SetLocation(Vec(0.0, 0.0, 100.0))
  entity.SetVelocity(linear = Vec(0.0, 0.0, 500.0))
  entity.AddVelocity(linear = direction, angular = Vec(0.0, 90.0, 0.0))
}

Gamemode (Exec)

SetLeaderboard

controller.SetLeaderboard(key: string, value: any)
SetLeaderboard(controller: controller, key: string, value: any)

Set a leaderboard value. Receiver on controller.

IncLeaderboard

controller.IncLeaderboard(key: string, value: any)
IncLeaderboard(controller: controller, key: string, value: any)

Increment a leaderboard value. Receiver on controller.

GetLeaderboard

controller.GetLeaderboard(key: string) -> any
GetLeaderboard(controller: controller, key: string) -> any

Get a leaderboard value. Receiver on controller.

GetTeam

character.GetTeam() -> any
GetTeam(character: character) -> any

Get a character’s team. Receiver on character.

IsBuilderTeam / IsUnaffiliatedTeam

team.IsBuilderTeam() -> bool
IsBuilderTeam(team: entity) -> bool
team.IsUnaffiliatedTeam() -> bool
IsUnaffiliatedTeam(team: entity) -> bool

Pure predicates over a team entity: IsBuilderTeam is true for the builder team, IsUnaffiliatedTeam for the unaffiliated (no-team) group. Receiver on the team entity.

PlayerWins / TeamWins

player.PlayerWins(teamWinsInstead?: bool)
PlayerWins(player: controller, teamWinsInstead?: bool)
team.TeamWins()
TeamWins(team: entity)

End the current round by declaring a winner. (The old imperative EndRound gate was removed; a round now ends via a win.) PlayerWins declares a player the winner, or their team if teamWinsInstead is true; TeamWins declares a team the winner.

GetCurrentRound

GetCurrentRound() -> int

The current round number.

GetTeamByName / GetTeamName

GetTeamByName(name: string) -> entity
team.GetTeamName() -> string
GetTeamName(team: entity) -> string

Look up a team by name, or get a team’s display name.

SetTeam

controller.SetTeam(team: entity, pin?: bool)
SetTeam(controller: controller, team: entity, pin?: bool)

Assign a player to a team, optionally pinning them to it.

Team leaderboards

team.GetTeamLeaderboardValue(key: string) -> int
team.SetTeamLeaderboardValue(key: string, value: int)
team.IncrementTeamLeaderboardValue(key: string, value: int)

Read, set, or add to a team-scoped leaderboard value. Receiver on the team entity (also callable as free functions with team as the first argument).

on CharacterDied() -> (character) {
  let ctrl = character.ControllerOf()
  ctrl.IncLeaderboard("deaths", 1)
  let score = ctrl.GetLeaderboard("score")
}

Character (Exec)

ShowHint

character.ShowHint(title: string, text: string)
ShowHint(character: character, title: string, text: string)

Display a hint popup to a character. Receiver on character.

on CharacterSpawned() -> (character) {
  character.ShowHint("Welcome", "Press E to interact")
}

Damage

character.GetDamage() -> { Damage: float, DamageLimit: float }
character.SetDamage(damage: float)
character.IncDamage(amount: float)

Read, set, or add to a character’s accumulated damage. Receiver on character. GetDamage() auto-unwraps to Damage where a float is expected (e.g. if char.GetDamage() > 50.0), and .DamageLimit gives the death threshold.

SetTempPermission

character.SetTempPermission(permission: string, enable: bool)

Grant or revoke a temporary permission tag on a character. Receiver on character.

Inventory

character.GiveWeapon(weapon, slot?)                  // set a slot to an item asset
character.AddInventoryItem(item)                     // append an item
character.SetInventoryItem(item, slot?)              // set a slot to an item
character.AddInventoryBrick(brick, size?)            // append a placeable brick
character.SetInventoryBrick(brick, slot?, size?)
character.AddInventoryEntity(entityType)             // append a spawnable entity
character.SetInventoryEntity(entityType, slot?)
character.AddInventoryItemAdv(item, damage?, speed?, scale?, itemName?, projectile?)
character.SetInventoryItemAdv(item, slot?, damage?, speed?, scale?, itemName?, projectile?)

Give items, procedural bricks, or spawnable entities to a character’s inventory. Asset args are $Type/Name references — $BRItemBase/... for items, a brick asset for bricks, an entity type for entities — inlined into the gate’s data. The Adv variants add per-item overrides: damage/weapon speed/scale multipliers, a display-name override, and a projectile override. All receive on character.

on CharacterSpawned() -> (character) {
  character.GiveWeapon($BRItemBase/Weapon_Pistol, 0)
  character.AddInventoryItemAdv($BRItemBase/Weapon_Bow,
    damage = 2.0, itemName = "Longbow of Doom")
}

Controller (Exec)

ShowStatusMessage

controller.ShowStatusMessage(message: string)
ShowStatusMessage(controller: controller, message: string)

Display a status bar message to a player. Receiver on controller.

on RoundStart() {
  ctrl.ShowStatusMessage("Round started!")
}

ShowChatMessage

controller.ShowChatMessage(message: string)
ShowChatMessage(controller: controller, message: string)

Send a chat message that only this player sees (a whisper). Receiver on controller.

ShowMessageBox

controller.ShowMessageBox(message: string, title?: string)

Pop up a modal message box for this player. Receiver on controller.

Player info

controller.GetUserName() -> string
controller.GetUserId() -> string
controller.GetDisplayName() -> string
controller.IsTrusted() -> bool
controller.HasPermission(permission: string) -> bool
controller.HasRole(role: string) -> bool
controller.SetCanRespawn(canRespawn: bool)
controller.ForceRespawn()
controller.SetTeamPinned(pinned: bool)

Read a player’s account name, persistent user id, or current display name; check whether they are trusted by the brick owner, hold a named permission, or have a named role (HasRole); toggle their ability to respawn or immediately respawn them (ForceRespawn, also callable as ForceRespawn(player)); or pin them to their team. All receive on controller.

Broadcast Messaging (Exec)

BroadcastChatMessage(message: string)
BroadcastStatusMessage(message: string, flash?: bool)

Send a chat message or status-bar message to every player. flash re-flashes the status message even when its text is unchanged.

on roundEnd {
  BroadcastChatMessage("Red team wins!")
  BroadcastStatusMessage("Round over", flash = true)
}

Audio (Exec)

entity.PlayAudioAt(audio, volume?, pitch?, innerRadius?, maxDistance?, spatialized?)
PlayGlobalAudio(audio, volume?, pitch?)
player.PlayClientAudio(audio, volume?, pitch?)

Play a one-shot sound at an entity’s location (spatialized by default), globally for all players, or non-spatially for a single player (PlayClientAudio, receiver on the player — a character or persistent player reference; also callable as PlayClientAudio(player, audio, ...)). The audio arg is a $BrickOneShotAudioDescriptor/... asset reference. PlayAudioAt receives on entity (characters work too).

on ZoneEntered() -> (character) {
  character.PlayAudioAt($BrickOneShotAudioDescriptor/BOSA_Buttons_Button_1_Press)
}

Entity Tags (Exec)

entity.SetTag(tag: string)
entity.GetTag() -> string

Attach an arbitrary string tag to any entity and read it back later — handy for marking players/entities with game state (team, slot index, role). Zone components can also filter on tags. Receiver on entity.

Misc (Pure / Exec)

Blend/lerp/Easing/Tween interpolate any one math variant T: float|int|vector|rotator|quat|color. The result is whatever T the inputs carry.

Easing/Tween take an easing fn and dir: an int, a bare enum-name literal, or an EasingFunction / EasingDirection value (see Built-in game enums). function = EasingFunction.Bounce and function = Bounce set the same field. Functions: Linear, Sine, Quad, Cubic, Quart, Quint, Expo, Circ, Back, Elastic, Bounce. Directions: In, Out, InOut. Omitted, they default to Linear/In.

Timer is a function-call instance. The restart/pause/resume exec controls are optional; its outputs are a value (Time) and an exec (Expired):

in trigger: exec
let t = Timer(10.0, restart = trigger)
out elapsed = t.Time
on t.Expired { /* fired when Time reaches the limit */ }

ReadBrickGrid() is pure and takes no arguments — it returns the brick grid that this gate’s microchip is placed on as an entity, ready to pass to entity getters/setters or wire into gates that expect a brick grid:

let grid = ReadBrickGrid()
let origin = grid.GetLocation()

Gate config properties

Some gate settings are not wire inputs — they are the checkboxes, dropdowns, and values in a gate’s in-game settings menu. Wirescript sets them as optional, constant-only call arguments; a constant is baked into the gate’s data, and anything you omit keeps the game default. (A non-constant value is a compile error — these can’t be wired.)

Enum values are bare member names, validated against the game’s own enum member list at compile time. An unknown name is a WS028 error; a raw int is also accepted (and range-checked).

let e = Easing(0.0, 1.0, t, function = Bounce, direction = InOut)
let c = ColorBlend(a, b, t, blendSpace = Oklab, clampAlpha = true)
p.DisplayText("hi", typeface = Bold, justify = Center, easing = EaseInOut)

Each enum used this way is also a built-in game enum type of its own, so its qualified value form works too, side by side with the bare name, and the two set the same field:

let e = Easing(0.0, 1.0, t, function = EasingFunction.Bounce, direction = EasingDirection.InOut)
let c = ColorBlend(a, b, t, blendSpace = ColorSpace.Oklab, clampAlpha = true)
p.DisplayText("hi", typeface = TextTypeface.Bold, justify = DisplayTextJustification.Center, easing = DisplayTextEasing.EaseInOut)

Every config field is settable — not just the aliases below. In addition to the friendly names, each gate exposes each bool/int/float/string/enum settings-menu field under its raw game name, so any of the ~60 config gates works even without a curated alias:

SweepSimple(500.0, Direction = X_Negative, bOnlyHitPlayerBodyParts = true)
p.DisplayText("hi", FontSize = 40, Typeface = Bold, Justification = Center)

Completion offers these raw field names, and hovering one shows its type (and enum members). The friendly alias and the raw name set the same field, so pick either; the table below lists the ergonomic aliases for the common gates.

Config attributes by gate:

Enum member names: EBRColorSpace Linear Srgb Oklab Hsv; EBREasingFunction Linear Sine Quad Cubic Quart Quint Expo Circ Back Elastic Bounce; EBREasingDirection In Out InOut; EBRTextTypeface Regular Bold Italic BoldItalic; EBRDisplayTextJustification Left Center Right; EBRDisplayTextEasing Linear EaseIn EaseOut EaseInOut; EBrickDirection X_Positive X_Negative Y_Positive Y_Negative Z_Positive Z_Negative.

Each of these schema enum types is also usable directly, under its clean Wirescript name, as a built-in game enum – EBREasingFunction as EasingFunction, EBREasingDirection as EasingDirection, EBRColorSpace as ColorSpace, EBRTextTypeface as TextTypeface, EBRDisplayTextJustification as DisplayTextJustification, EBRDisplayTextEasing as DisplayTextEasing, and EBrickDirection as Direction.

Clock (Event)

The Clock gate emits a periodic execution pulse forever; it reads as an event. It takes interval and enabled, both wire inputs: a constant bakes into the gate and a variable wires in, so the rate and the on/off state can change at runtime. The handler body runs on each pulse.

in running: bool
var ticks: int = 0
on Clock(interval = 2.0, enabled = running) {
  ticks = ticks + 1
}

ChatCommand (Event)

Registers a chat command. The call parens hold only config args (the command name and an optional description); the event’s data outputs are bound by a trailing -> (…) tuple capture (or -> { field: local } record):

• String literals fill the config fields in order: CommandName, then HelpText. The description can also be given by name as Description = "...".
• The -> capture binds the event’s data outputs, in order: controller (the player who typed it), then arguments (the command text as a string).

on ChatCommand("greet", "Greets the player") -> (controller, arguments) {
  // CommandName = "greet", HelpText = "Greets the player"
  // controller: the player who typed the command
  // arguments: the command text as a string
  controller.ShowStatusMessage("You said: ${arguments}")
}

The description is optional and can use the named form. Binding params are also optional — omit the ones you don’t need:

on ChatCommand("wave", Description = "Wave at everyone") {
  // no bindings needed
}

Custom Events

A named, cross-gate event channel that carries up to 8 data values. Each comes in two flavours: personal (same-owner) and global (ownership-agnostic), on separate channel namespaces — a personal "x" and a global "x" never mix.

SendCustomEvent (Exec)

SendCustomEvent(name, data1, … data8, target = …) — name is the channel, a constant string baked into the gate (a variable or computed value is a WS028 error), followed by up to 8 optional data values of any type. target is an optional entity whose grid receives the matching object events. Delivery is same-owner; use SendGlobalCustomEvent for the ownership-agnostic version. Fires all matching receivers.

A targeted send needs isObject = true on the receiver. Giving a target (including the receiver spelling, ent.SendCustomEvent(...)) makes it an object event, and only an object-scoped receiver matches one. A plain on CustomEvent("x") is scoped grid-wide and silently never fires for it - no error, no warning, at check or compile. The two spellings pair up:

ent.SendCustomEvent("ui.init", who)          // targeted -> object event
on CustomEvent("ui.init", isObject = true) -> (who: character) { }

SendCustomEvent("ui.init", who)              // untargeted -> grid-wide
on CustomEvent("ui.init") -> (who: character) { }

This is the usual way to talk to a spawned prefab: keep the entity SpawnPrefab returned and target it, with isObject = true on the prefab’s receivers.

on hit {
  SendCustomEvent("damage", 7, attacker)   // send an int + a character
}

on CustomEvent (Event)

The receiver’s call parens hold only the channel name (positional) and any config (isObject = true); the typed data outputs are bound by a trailing -> (…) tuple capture. Each data slot’s type can be given explicitly (amount: int) or inferred from a matching in-unit SendCustomEvent on the same channel; when neither is available the slot defaults to float and a WS042 warning is emitted (the game stores each data slot as a typed value, not any). Unused slots default to float. isObject = true is constant config that scopes the receiver to a specific grid/object (an object event) instead of firing grid-wide.

var lastDamage: int = 0   // a top-level var is already persistent — no `static`

on CustomEvent("damage") -> (amount: int, attacker: character) {
  lastDamage = amount
  attacker.ShowStatusMessage("You took ${amount} damage")
}

Global variants — SendGlobalCustomEvent / on GlobalCustomEvent

SendGlobalCustomEvent and on GlobalCustomEvent are the ownership-agnostic counterparts: delivery ignores the owner, reaching every matching global receiver. They have the same shape (constant channel name, up to 8 typed data values, optional target entity, isObject config), on a channel namespace that is separate from the personal one — SendGlobalCustomEvent("x") reaches on GlobalCustomEvent("x") but never on CustomEvent("x"), and vice versa.

var total: int = 0

on GlobalCustomEvent("score") -> (points: int) { total = total + points }
on hit { SendGlobalCustomEvent("score", 10) }

One-tick delay. A CustomEvent receiver fires on the tick after the SendCustomEvent runs — the pulse is delivered on the next frame, not synchronously within the sender’s exec chain. Anything that must observe the event’s effect immediately has to account for that one-tick latency (and a send → receive → send round trip costs a tick each hop).

Signature checking (WS030). When a send targets a constant channel name, the compiler compares each data value’s wire type against the matching receiver’s declared param types and warns (WS030) on a mismatch — e.g. sending a float where the receiver declared int. This runs for both the personal (SendCustomEvent / on CustomEvent) and global (SendGlobalCustomEvent / on GlobalCustomEvent) pairs, each within its own namespace. Types that share a wire variant are interchangeable and never flagged (any two entity kinds — character/entity/controller/… — are all the same Object variant). The channel name must be a constant literal, so every send’s receiver set is known at compile time. In the editor, go-to-definition on a send’s channel-name string jumps to the receiver.

A non-constant data value is still typed as float on the wire at emit rather than from the value’s real type — full end-to-end typing waits on generics. For now the receiver’s annotations are the source of truth, and constant sends carry their type.

Prefab Spawning (Exec)

SpawnPrefab

Returns: entity – the spawned entity. Give the prefab with a $…brz reference; omit prefab to configure it on the placed gate in-game instead (copy a prefab onto the Spawn Prefab brick).

on trigger {
  let spawned = SpawnPrefab(
    prefab = $./turret.brz,
    offset = Vec(0.0, 0.0, 50.0),
    lifetime = 10.0,
    limit = 5
  )
  spawned.SetVelocity(linear = launchDir)
}

destroyAll is a secondary exec trigger (like Timer’s restart): wire a reset / round-start signal into it to remove every entity this spawner has produced, without re-spawning. The gate spawns when its own exec chain fires and clears when destroyAll fires:

in reset: exec
on trigger {
  let cube = SpawnPrefab(prefab = $./msg.brz, limit = 64, destroyAll = reset)
  cube.SetTag(payload)
}
// pulsing `reset` destroys every cube this gate has spawned

A $./file.brz reference reads the .brz at compile and embeds it into the output bundle (content-addressed at Prefabs/Uploads/<hash>.brz), so the compiled program carries its prefab. A $./file.ws reference compiles that source first and embeds the result, and a prefab can also be written inline as a $ followed by a triple-backtick block. See Prefab References and the per-entity fan-out section in best practices.

SpawnExplosion

Spawns an explosion of a given projectile/explosion class.

on hit {
  SpawnExplosion($BRWeaponProjectile/Grenade, instigator = attacker, scale = 2.0, damage = 1.5)
}

SpawnExplosionAt

Like SpawnExplosion, but at an absolute world position instead of an offset from the gate’s brick.

on hit {
  SpawnExplosionAt(Vec(0.0, 0.0, 200.0), $BRWeaponProjectile/Grenade, instigator = attacker)
}

Raycasting (Exec)

Sweep

Detection is opt-in. Every detect* flag defaults to false, so a Sweep with none set detects nothing and always fires Miss. Enable the channel you want: detectBricks for brick grids / spawned prefabs, detectPlayers1 for players, detectPhysics for loose physics objects.

Returns a record with fields:

• HitDistance: float – Distance to hit point
• HitEntity: entity – Entity that was hit
• HitLocation: vector – World position of hit
• HitNormal: vector – Surface normal at hit
• Hit: exec – Fires if something was hit
• Miss: exec – Fires if nothing was hit

on trigger {
  let aim = char.GetAim()
  // Run the Sweep INSIDE the exec handler; handle it with nested Hit/Miss branches.
  // A top-level `Sweep(..., exec = t)` does NOT fire.
  let r = Sweep(aim.Origin, aim.Direction, 10000.0,
    radius = 5.0, ignore = char, detectPlayers1 = true)
  on r.Hit  { r.HitEntity.ShowStatusMessage("hit!") }
  on r.Miss { /* nothing in range */ }
  // If should also work here
  if r.Hit  { r.HitEntity.ShowStatusMessage("hit!") }
  if r.Miss { /* nothing in range */ }
}

Random (Exec)

on RoundStart() {
  let r = Random(0, 15)
  if r == 0 { specialEvent = true }
}

Random rides the same PrimMath variant as the arithmetic operators, so its min/max may be a vector, rotator, quat, or color — it then rolls each component independently and returns that same type. Random(Vec(0.0, 0.0, 0.0), Vec(1.0, 1.0, 1.0)) is a random point in the unit cube; Random(a, b) on two colors is a random color between them (all four RGBA channels). Both bounds share the type of the result.

Note: Random is an exec function because it requires sequential execution to produce a new random value each time.

Sleep / Delay (Pure)

Buffer gates that delay a value passing through. Most useful with await and the _ armed flag placeholder.

• input – the value to delay. Use _ inside await to wire the armed flag.
• delay – seconds/ticks to wait before the output follows the input.
• hold – seconds/ticks to hold the output after the input drops to zero. Set to -1 to use delay instead.

// Sleep 2 seconds using await
on start {
  await Sleep(_, delay = 2.0)
  doAfterDelay()
}

// Sleep 60 ticks (~1 second at 60Hz)
on start {
  await SleepTicks(_, delay = 60)
  doAfterDelay()
}

// Pure usage: delay a signal by 5 ticks
let delayed = SleepTicks(rawSignal, delay = 5)

Exec Override

Exec functions that are called outside of an exec context can be given an explicit exec named argument to provide the execution trigger:

// Outside a handler -- provide exec explicitly
let r = Random(0, 10, exec = someTrigger)

This wires someTrigger as the exec input of the gate, bypassing the requirement for an enclosing handler context.

Newer builtins

Player-reference gates (DisplayText, ShowChatMessage, HasRole, leaderboard and team setters, the join/left/chat events, ControllerOf/CharacterOf) target the persistent player-state on the current build. The controller type is unchanged and still wires straight into them — existing scripts keep working.

Entity (Exec)

entity.GetSpeed() -> float                    // scalar speed
entity.GetVelocityAtPoint(point: vector) -> vector
entity.GetEntityTeam() -> entity              // team of any entity (grid/prefab)
entity.SetEntityTeam(team: entity)
entity.IsFrozen() -> bool                     // whether the entity / brick grid is frozen
entity.DestroySpawned()                       // despawn a spawned entity
entity.DestroySpawnedPrefab()                 // despawn a spawned prefab

Character ammo (Exec)

character.GetAmmo(resource: entity) -> int
character.GrantAmmo(resource: entity, amount: int)
character.SetAmmo(resource: entity, amount: int)
character.GetInventoryEntry(slot: int) -> { Item, BrickAsset, EntityType }
character.GetCurrentInventorySlot() -> int
character.GetWeaponChamberAmmo(resource: entity, slot: int) -> int
character.IncWeaponChamberAmmo(resource: entity, slot: int, amount: int)
character.SetWeaponChamberAmmo(resource: entity, slot: int, amount: int)

The CharacterFiredWeapon(character, direction, start) event fires when a player fires a weapon (direction/start are vectors). Sweep/SweepSimple results also carry a HitColor field (the color of the surface hit).

Date / time (Pure)

GetUnixTime() -> int
FormatDate(unixTime: int, format: string, useUTC?: bool) -> { Output: string, Success: bool }

Value conversions (Pure)

Remap(value, inMin, inMax, outMin, outMax) -> float   // rescale a value between ranges
LogicalShiftRight(a: int, b: int) -> int              // logical (unsigned) >>
EnumToInt(value: enum) -> int                     // enum tag; folds a known variant, else uses the gate
IntToEnum(value: int, wrap?: bool) -> enum        // enum type from context; const folds, runtime uses the gate
ItemToPickup(item: entity) -> entity                  // pickup asset for an item
color.ConvertColor(fromSpace?: int, toSpace?: int) -> color
"A".ToCharCode() -> { Codepoint: int, Success: bool }
FromCharCode(codepoint: int) -> { Character: string, Success: bool }

EnumToInt / IntToEnum are the gate-backed twins of .ToInt() (= .Discriminant) and Enum.FromInt(n). EnumToInt requires an enum argument (a non-enum is a type error); a compile-time-known enum folds to its discriminant literal, a runtime enum routes through the gate. IntToEnum’s result is an enum whose concrete type comes from the annotated target (like FromInt); a constant tag folds to the enum record, a runtime tag routes through the gate, and wrap clamps an out-of-range tag. See enums.md.

ParseInt / ParseNumber likewise now expose a Success flag: they auto-unwrap to their parsed Value in arithmetic/comparisons (ParseInt(s) == 5), and .Success is false when the string wasn’t a valid number.

Self transform + simple raycast (Exec)

GetOwnTransform() -> { Location: vector, Rotation: rotator }
SweepSimple(distance: float, radius?: float, spreadConeAngle?: float)
  -> { HitDistance, HitEntity, HitLocation, HitNormal, Hit, Miss }

SweepSimple sweeps from its own brick (the containing microchip’s brick, or the gate’s own brick if not in a microchip), in the configured direction. It has no origin input and takes no receiver. To sweep from an arbitrary point, use the full Sweep(origin, direction, distance, ...) gate, which has a vector origin input. distance is positional (SweepSimple(500.0, ...)).

Zone array fills (Exec) — array methods

arr.fillFromZoneEntities(zone, tagFilter?)   // entities inside a zone
arr.fillFromZonePlayers(zone, tagFilter?)    // players inside a zone

The character/entity zone enter/leave events also accept a tagFilter = argument (alongside zone =) to restrict them to tagged entities.

Generic type syntax

Types may be written in generic form:

var nums: Array<int> = [1, 2, 3]   // same as int[]
mod inc(v: Ref<int>) { v = v + 1 }   // same as *int

Array<V> and Ref<V> are exact aliases of V[] and *V.

Maps (var m: Map<K, V>)

A map is a keyed variable collection (the MapVar gate family), declared as a var of the generic Map<K, V> type. Keys must be int, string, or an object reference (entity/character/controller) — any other key type is a WS039 error; values may be any wire-storable scalar (int/float/bool/string/vector/rotator/quat/color/object). A map starts empty unless given a constant literal initializer (= {} is the explicit empty form).

A map value can also be a record (var m: Map<int, Point>): the map is stored as one parallel map per field and set/get/has/length/remove/clear/keys fan out (values/copyFrom are WS050). A record can never be a map key. See Records as storage.

var scores: Map<string, int>
var names: string[]

on tick {
  scores.set("alice", 10)                 // insert / overwrite
  let g = scores.get("alice")             // { Value, Found } — auto-unwraps to Value
  if g.Found { PrintToConsole(g.Value) }
  if scores.has("bob") { ... }
  scores.remove("bob")                    // -> bool (was present)
  let n = scores.length()
  scores.keys(names)                      // fill an array with the keys
  scores.clear()
}

Methods (exec context, like array methods): set(key, value), get(key), has(key), remove(key), clear(), copyFrom(otherMap), length(), keys(destArray), values(destArray).

Map literals

A var of Map<K, V> type can be given literal contents with { ... }. Entries use => for any key expression, or : for a string / atom / int literal key (or a bracketed [expr] computed key):

var m: Map<int, int>    = { :red => 10, 7 => 0 }    // arrow -- any key
var s: Map<string, int> = { "red": 1, "blue": 2 }    // colon -- string literal key
var a: Map<int, int>    = { :red: 1, :blue: 2 }      // colon -- atom literal key
var e: Map<int, int>    = {}                         // explicit empty map
on tick { m = { [runtimeKey] => x } }                // computed key -- desugars

A constant map literal (every key and value a compile-time constant) in a var initializer bakes straight into the map at rest – no runtime gates, the map loads pre-populated. An initializer with any non-constant entry doesn’t bake – its entries are dropped (with a compiler warning) and the map loads empty; build it at runtime instead. Inside an exec handler, m = { ... } (or a literal with runtime keys/values) desugars to clear() followed by one set(key, value) per entry, in source order – the same clear-then-populate shape as array literal assignment.

{ foo: 1 } with a bare identifier key is a record literal, not a map – : only introduces a map key for a string/atom/int literal or a [expr] computed key. Use foo => 1 or [foo]: 1 to key a map by an identifier’s value.

Assigning a whole map from another map variable (m = m2) is not supported – there is no whole-map-copy gate. Use m.copyFrom(m2) instead.

Exec-flow gates (Union / Branch)

Two exec-signal combinators, callable like any other builtin:

Union(a: exec, b: exec) -> exec
Branch(cond: bool, exec: exec) -> (A: exec, B: exec)

• Union(a, b) merges two exec signals into one — the result fires whenever either input fires. Handy for running one handler from several triggers:

  let go = Union(init, Change(team))
  on go { rebuild() }
  

• Branch(cond, exec) routes an incoming exec to .A or .B depending on cond at the instant it fires (a runtime if for exec flow). Bind or trigger on the named outputs:

  on Branch(isRed, tick).A { redTick() }
  on Branch(isRed, tick).B { blueTick() }
  

Callable gate builtins

Every variable / array / map wire gate is also exposed as a plain function named after the in-game gate, alongside its method / operator / assignment form. The two forms are identical — the call desugars to the method or assignment at parse time — so pick whichever reads better. Named after the game gates for discoverability (and completion).

Variables

Arrays — the function name maps to the array method of the same operation; the receiver is the first argument:

Array fills (Gamemode / Zone gates — the function-call twins of the fillFrom* array methods):

Maps — map to the map methods of the same name:

All array/map operations remain exec-context only (they run on the exec chain), exactly like their method forms.

Game Knowledge

Brickadia behaviour that the language does not define but that programs depend on. The language reference tells you what compiles; this page collects what the game does with the result, plus the practical tips that follow from it.

Contents

• Rich Text Markup
• Input Action Names
• DisplayText Screen Placement

Rich Text Markup

Any string the game renders as text accepts markup: DisplayText, BroadcastChatMessage, ShowStatusMessage, chat, and the text components a @label writes. Markup is ordinary string content, so it composes with interpolation and .. concatenation like any other text.