Cheat sheet

Everything on one scannable page. Full spec: show.json format · tutorial: first show.

Show files are JSONC (comments allowed). Vars are bare (heat); devices use @ (@strip).

Top-level sections

schemaVersion (=1, required) · name · board · devices · vars · palette · defs · lists · inputs · buses · drivers · sensors · scripts · states (required) · rules

buses, drivers and sensors are the v2 peripheral tier — declare a transport once, describe a part as data, and read it as variables. See show.json format.

There are no scenes/sequences/effects sections — everything is a script.

Scripts (flow control)

A script is one recursive container: { loop, speed, children }. There is no container mode — each child declares its own flow (default serial):

child `flow`	gates next sibling	awaited by parent	use for
`serial` (default)	yes	yes	a step in a script
`parallel`	no	yes	a join / a looping look
`detached`	no	no	fire-and-forget

loop: true — repeat forever; loop: <N> — repeat N times. Looping children are auto-detached. speed — number/expr or { chase, rate }.

Launch from states: start/run = begin (background vs awaited-via-.done), stop = end.

Devices — `@id`

field	units / values	notes
`kind`	`ledstrip` \| `digital` \| `pwm` \| `screen` \| `servo` \| `stepper`	omit for a segment
`kind` (reserved)	`readout` \| `relay` \| `motor` \| `dac`	validated, but nothing drives them yet — the loader says so
`count`	integer ≥ 1	channels / pixels (default 1)
`pin`	GPIO number	validated against `board`; omit for a `screen`
`order`	e.g. `GRB`, `RGBW`	LED color order
`brightness`	0..255	LED master (default 120)
`width` + `height`	pixels	`screen` framebuffer size (0 = backend default)
`segmentOf` + `start` + `count`	parent id, index, length	names a slice of a strip

Inputs → events

type is digital (default) or analog. The state machine decides tap-vs-hold, not the input.

`type`	events emitted
`digital`	`id.pressed` · `id.released` · `id.tapped` (short) · `id.held` (long)
`analog`	`id.high` · `id.low`

Tap-to-toggle: two states both handling id.tapped. Hold-to-run: id.pressed start, id.released stop.

Fields: label, color, pin (omit = virtual), activeLow (bool), pull (up/down), holdMs (tap/held split, default 400), min/max (analog raw range → 0..1), high/low (analog 0..1 thresholds). An input’s live level is readable as a var under its id.

Don’t name an input after an event suffix (pressed/tapped/…) — use a distinct name.

Effect verbs

Target an LED strip, or a segment of one.

verb	value	params	what it does
`bar`	`@device`	`color`, `sec`	Fill a device like a VU / progress bar.
`blink`	`@device`	`color`, `off`, `sec`, `duty`	On/off cycle.
`chase`	`@device`	`color`, `off`, `sec`	One lit pixel runs across.
`comet`	`@device`	`color`, `lapSec`, `tail`	A bright head with a fading tail sweeps around.
`pattern`	`@device`	`color`	Per-pixel color expression, 1-D (reads i, count).
`spark`	`@device`	`color`, `off`, `sec`	Random single-pixel flickers.

Sound verbs

A play names a file that lives beside the show; tone needs no file at all.

verb	value	params	what it does
`play`	`file`	`volume`, `pick`	Play audio from the data folder — a file (“a.wav”), a FOLDER (no extension: all files in it), or an array of filenames. A folder/array defaults to random selection; `pick` overrides.
`tone`	`number`	`wave`, `seconds`, `volume`	Synthesized tone at a frequency in Hz (number or expression) — no file needed.

Screen verbs

Target a @screen. Coordinates are pixels unless the verb says otherwise.

verb	value	params	what it does
`anim`	`@screen`	`file`, `x`, `y`, `fps`	Play `file` (.rfxanim) at (x,y); `fps` overrides the clip rate.
`circle`	`@screen`	`color`, `x`, `y`, `r`, `outline`	Circle at (x,y) radius r.
`fill`	`@screen`	`color`	Fill the whole canvas.
`image`	`@screen`	`file`, `x`, `y`	Blit `file` (.bmp/.rgb565) at (x,y).
`line`	`@screen`	`color`, `x0`, `y0`, `x1`, `y1`	Line from (x0,y0) to (x1,y1).
`number`	`@screen`	`value`, `color`, `x`, `y`, `size`, `digits`, `font`	Draw the live numeric `value` (a var/expr) at (x,y).
`paint`	`@screen`	`color`, `coarse`	Per-pixel color expression, 2-D (reads x,y,w,h,nx,ny).
`pixel`	`@screen`	`color`, `x`, `y`	A single pixel at (x,y).
`polygon`	`@screen`	`color`, `points`, `outline`	Polygon through `points`.
`polyline`	`@screen`	`color`, `points`, `close`	Connected OPEN path through `points`; set `close` to join the ends.
`rect`	`@screen`	`color`, `x`, `y`, `w`, `h`, `outline`	Rectangle at (x,y) size (w,h).
`text`	`@screen`	`value`, `color`, `x`, `y`, `size`, `font`	Draw the static string `value` at (x,y).

Screen widgets

Compound drawings that read a value every frame.

verb	value	params	what it does
`gauge`	`@screen`	`value`, `min`, `max`, `x`, `y`, `r`, `color`	Radial gauge (arc + needle) of `value` in [min,max].
`graph`	`@screen`	`value`, `min`, `max`, `x`, `y`, `w`, `h`, `color`	Scrolling line graph of `value` over time.
`meter`	`@screen`	`value`, `min`, `max`, `x`, `y`, `w`, `h`, `color`	Bar meter of `value` in [min,max] — fills left/up.

Actions

Legal as a script child, in a state enter/exit, or in a handler do.

verb value params what it does

disable script — Disable a script by name — it and its whole subtree are skipped (not tended, not voted on), as if pruned from the tree. Different from pause, which freezes but still counts as active.

emit event scope Raise a custom event by name; handled like an input event.

enable script — Enable a script by name — the opposite of disable (a disabled node and its subtree are skipped entirely, unlike pause).

fade var to, rate, sec, ease Fade a scene’s intensity (or a var) toward to. On a container, “in”/“out” over sec along ease.

follow target target, rate Continuously glide a float (a var, or @effect.prop) toward a moving target.

move @device to, sec, from, ease Move a @servo/@stepper output to to (angle/position), eased over sec.

pause script — Pause a running script by name (freezes its clock).

ramp var to, rate Linear-rate animate a var toward to.

resume script — Resume a paused script by name.

run

script

args

Begin a one-shot script; listen for

"states": {
  "initial": "Off",
  "Off": { "enter": [...], "exit": [...],
           "on": { "power.tapped": "On" },       // string handler = pure transition
           "after": { "sec": 10, "to": "X" } },  // fire once, N sec after entry
  "On":  { "on": { "fire.pressed": { "do": [...], "to": "Firing", "when": "heat<1" } } }
}

Handler: string → transition · object → { do, to, when }. A button is enabled only when the current state handles one of its events.

Units

sec, lapSec, wait, after.sec, for, every, after → seconds. rate → units per second. duty, intensity, volume, analog high/low → 0..1. speed → multiplier. brightness → 0..255. color → #RRGGBB or a color expression.

Expressions (any color/number, as a quoted string)

Operators: + - * / % · == != < > <= >= · && || ! · a ? b : c Names: bare var (heat), input value, @effect.prop. Hex 0x... Constants: true false pi.

abs floor ceil round sqrt sin cos tan sign pow mod frac
min max clamp lerp step smoothstep if map random pick
rgb(r,g,b)   0..255 → color
hsv(h,s,v)   0..1   → color (h wraps)
mix(a,b,t)   blend two colors (use mix, not lerp, for colors)
map(x,inLo,inHi,outLo,outHi)   lerp(a,b,t)

Built-in variables

name	where	value
`time`	everywhere	seconds since start
`pi`	everywhere	3.14159…
`i`, `count`	`pattern` (1-D)	pixel index, pixel total
`x` `y` `w` `h` `nx` `ny`	`paint` (2-D)	pixel coords, canvas size, normalized 0..1
`<input>`	everywhere	an input’s live level (0/1 digital, 0..1 analog)

References

@device · bare var · script/state by name · input.event · script.done · as (names a play/effect instance) · @effect.prop (in expressions).