3 · The trigger

A blaster that cannot be fired is a lamp. Carry on from part 2 — or open Project ▾ ▸ Examples ▸ Tutorial · 02 first light to catch up.

Live Press TRIGGER. White flash, red afterglow, back to idle.

1 · Add the button

SETUP ▸ Inputs ▸ type trigger into ＋ new input.

An input card. type, wiring and pull are dropdowns; the rest is a label, a colour and a pin.

Control	Set it to	Meaning
type	digital	a button, not a knob
label	TRIGGER	what the on-screen button says
color	#ff3b30	what the on-screen button looks like
wiring	pin	it is soldered to a GPIO
pin	14	which GPIO
activeLow	ticked	button to GND: pressing pulls the pin down
pull	up	enable the internal pull-up
hold	blank	the tap/held split in ms; blank means the default, 400

Set wiring to blank and the input is virtual

The wiring dropdown has a blank option — “a GPIO, or blank for a dashboard-only button”, as the hint beside it says. A virtual input exists only in the dashboard, which is how you prototype a six-button prop before you have wired one button, and why you can press TRIGGER in the preview above with nothing attached.

The filter row underneath is for noisy hardware: ＋ stage adds a debounce or a smoothing step. A clean button needs none.

What an input does not decide

It does not decide what a press means. Every digital input emits all four of these, always:

Event	Fires when
trigger.pressed	it went active — the moment of contact
trigger.released	it went inactive
trigger.tapped	released quickly: a short press, under holdMs (default 400)
trigger.held	still down past holdMs: a long press begins

Your states pick which ones they care about, from a dropdown. The same physical button is a tap in one state and a hold in another, and you write no timer.

2 · Add the firing sequence

BEHAVIORS ▸ Scripts ▸ ＋ new script ▸ fire.

Add two set steps to its list (＋ action ▸ set, twice) and fill them in:

Step	device	mode	colour	sec
1	@barrel	color	#ffffff	0.05
2	@barrel	color	#ff2a00	0.12

A device set row has a color / on-off dropdown, because a device set is one or the other and never both. Leave it on color.

`sec` on a `set` is a hold — and forgetting it is the most common first bug

Without sec the set lasts exactly one frame: the engine asserts it once, and the looping idle underneath repaints over it on the very next frame, so you see nothing at all. With sec, the set keeps winning for that long — and, as a serial step, blocks the next step for the same time. Two sets in a row are therefore a two-frame animation with real timing.

“My flash doesn’t show up” is nine times out of ten a device set with no sec sitting under a looping effect that owns the same device.

3 · Give the state machine somewhere to go

Open States. You have Ready from part 2; add Firing with ＋ new state.

A whole state on one card: what happens on entry, what each event does, what happens on the way out.

On the Ready card:

1. on enter already has start ▸ idle from part 2.
2. on exit — ＋ action ▸ stop, target idle.
3. Click ＋ when event and choose trigger.pressed from the list. A row appears: when trigger.pressed → (stay). Change the second dropdown to Firing.

On the Firing card:

1. on enter — ＋ action ▸ run, target fire.
2. ＋ when event ▸ fire.done → Ready.

The event list is a list of real events

＋ when event offers the events your show can actually produce — every event of every input you declared, plus <script>.done for every script. It is not a free-text box, so a handler cannot be waiting for an event that will never arrive because of a typo.

start versus run

Both begin a script; the difference is what you get back.

• start — set it going and forget it. For looks and loops. stop ends it.
• run — set it going, and the engine promises a <script>.done event when it finishes. For anything the show has to wait for.

fire.done is what brings the state machine home. Nothing had to know how long the fire script takes; change its timings and the transition still lands on the last frame.

A looping script never finishes

loop ticked means <script>.done will never fire. If you are waiting on a .done that never arrives, check whether the script you are waiting on loops.

A button is enabled by the state machine

The button exists because a state handles one of its events.

There is no separate list of which buttons are live. A button is enabled exactly when the current state has a handler for one of its events, and the Studio dims it when it is not. If you press something and nothing happens, the answer is almost always that the current state has no handler for that event.

Tap to toggle, hold to run

Both patterns come out of the same button and the same two dropdowns:

• Tap to toggle — handle trigger.tapped in both states, one going each way. The button is momentary; the states remember which side you are on.
• Hold to run — trigger.pressed starts it, trigger.released stops it.

What the editor wrote

step-03-the-trigger.json 56 lines Copy

{
  // ===========================================================
  //  BLASTER · STEP 3 — The trigger
  //  A button, and a state machine with somewhere to go.
  // ===========================================================
  "schemaVersion": 1,
  "name": "Blaster 03 - The Trigger",
  "board": "t-display-s3",

  "devices": {
    "barrel": { "kind": "ledstrip", "count": 8, "pin": 16, "order": "GRB", "brightness": 160 }
  },

  // An input is the HARDWARE. What a press MEANS is decided by
  // the states below, which is why one button can be a tap in
  // one state and a hold in another.
  "inputs": {
    "trigger": { "label": "TRIGGER", "color": "#ff3b30", "pin": 14, "activeLow": true, "pull": "up" }
  },

  "scripts": {
    "idle": {
      "children": [
        { "blink": "@barrel", "color": "#ff6a00", "off": "#140400", "sec": 1.4, "loop": true }
      ]
    },

    // A one-shot. Two steps, one after the other: a white flash,
    // then a red afterglow. `sec` on a `set` HOLDS the colour for
    // that long — without it the set lasts a single frame.
    "fire": {
      "children": [
        { "set": "@barrel", "color": "#ffffff", "sec": 0.05 },
        { "set": "@barrel", "color": "#ff2a00", "sec": 0.12 }
      ]
    }
  },

  "states": {
    "initial": "Ready",

    "Ready": {
      "enter": [ { "start": "idle" } ],
      "exit":  [ { "stop": "idle" } ],
      "on": { "trigger.pressed": "Firing" }
    },

    // `run` starts the script AND promises a `fire.done` event
    // when it finishes. That event is what brings us home.
    "Firing": {
      "enter": [ { "run": "fire" } ],
      "on": { "fire.done": "Ready" }
    }
  }
}

Two shapes worth recognising in that file, because the editor draws them differently:

• A handler that is a bare string — "fire.done": "Ready" — is a pure transition. That is the when … → … row with no actions under it.
• A handler that is an object — { "do": [...], "to": "...", "when": "..." } — has actions, and optionally a guard. Click ＋ actions on a when row and the editor converts one into the other for you.

---

Next: 4 · Flow — the one idea the rest of the engine is built on.