Block Programming Concepts

NORTHSTARSHOW SYSTEMS

Block Programming Concepts

How Compose's Block Editor models show logic

Document Number	Revision	Date	Platform Version
NSSS-DOC-0060	A	2026-05-20	1.0

The Model

Every Northstar cue is a stack of blocks. The top block is always a hat block — it defines when the cue fires. Below the hat is a script of stack blocks (actions) and C-blocks (control flow). Some blocks have slots into which reporter blocks (values) or boolean blocks (conditions) can be plugged.

Block Categories

Category	Role	Examples
Hat	Trigger — what makes a cue fire	event-manual, event-input, event-schedule
Stack	Action — what happens when the cue runs	action-fire, action-pulse, action-play-audio
Control	Flow — sequencing within a cue	wait, repeat, forever, if, if-else
Reporter	Value — plugs into number slots	current-time, channel-state, input-value
Boolean	Condition — plugs into boolean slots	equals, greater-than, and, or, channel-is-high

Execution Model

When a cue is fired, HelmOS starts a new AbortController and runs the cue's script as an async task. The script executes blocks in order, awaiting wait blocks, looping repeat / forever, branching on if / if-else. The task can be aborted at any time by stop-all, by Maintenance Mode activation, or by E-Stop. Aborted tasks exit at their next await point.

Cue Run Lifecycle

Cue fired
   │
   ▼
HelmOS creates AbortController + RunContext
   │
   ▼
Script execution begins
   │  (blocks evaluated in order)
   │
   ├──▶ action-fire    → UDP command to Polaris
   ├──▶ wait 500ms     → setTimeout, await
   ├──▶ if condition   → evaluate boolean, branch
   └──▶ ... final block
   │
   ▼
Cue finishes (or aborted)
   │
   ▼
event-cue-complete hats matching this cue fire next

Chaining

Cues chain in two ways. Implicit: a cue's nextCueId field points to another cue, which fires automatically when the parent finishes. Explicit: another cue uses an event-cue-complete hat that references the parent. Both mechanisms are first-class.

What Blocks Cannot Do

Direct serial / network calls — all Polaris communication is via action-* blocks
Persistent state between runs — each cue run is independent
User-defined functions or imports — flat block scripts only
Arithmetic beyond reporters and booleans — for advanced computation, expand the reporter set

NSSS-DOC-0061Block Type Reference
NSSS-DOC-0062Cue Triggers Explained

Revision History

Revision	Date	Description
A	2026-05-20	Initial publication