StarScript

StarScript is the language on StarBoard’s cards. A card may carry a few lines of it, and Play runs them: a line is spoken, a choice is offered, a value is kept, the walk goes on to another card. The desktop app and every board on the web run the same stepper, line for line; the two are held together by shared cases.

The tutorial on the home is a stack of seven cards written in it. Its first card’s script, as the stack holds it (tools/reference_pages.py writes this fence from boards/tutorial.stack.json, so it cannot drift):

say s2ar "Below us is an icy moon, drawn live. Shall we change it?"
choice strike "Drop a meteor on it"
choice c-tut-board "Show me how first"
end
label strike
set tell.world "meteor"
say s2ar "A rock from the dark. The shell gives, the heart glows through. That was one line of StarScript."
choice c-tut-board "Show me the line"
end

Lines

Each line is one command: a verb, then its words, separated by spaces. A word with spaces in it is quoted; inside quotes \" is a quote, \\ a backslash and \n a new line. Blank lines and lines that begin with # are nothing.

The verbs

LineWhat it does
say <who> "<text>"A line, spoken by who. Play holds on it until the reader goes on. $name in the text is the value kept at name (a full stop after it ends the sentence).
choice <to> "<text>" [set:<name>=<value> …]An answer offered under the say before it. to is a card (c-…) or a label in this script. The pick is kept at choice, and its set: pairs keep their values when it is picked (choice yes "Yes" set:mood=glad).
ask <name> "<prompt>"Asks the reader for a line of text and keeps it at name.
set <name> <value>Keeps a value. A name with dots (door.open) is a path; every card of the stack reads it while Play runs.
when <name> equals|notequals|gt|lt <value>Runs the next line only when the value at name is value; notequals runs it only when it is not. gt and lt compare as numbers (when hp gt 3); a value that is not a number is never greater or less.
branch <name> <value> <then> <else>Goes to then when the value at name is value, else to else: each a label or a card.
goto <to>Goes to a label in this script, or to a card.
label <name>A place in the script to go to. Three names are hooks (below).
endEnds the card's script. A card with links, or with cards its script names, offers to go on to them.
pass <event>In an onClick hook: hands the click on to the background card under it.
request_file <name> <kind> "<prompt>"The desktop: waits for a file dropped on the window and keeps its path at name.
pause <seconds>A world editor's beat; on a card Play steps over it.

The grammar’s other verbs (wait_for_chat, commit) belong to the world editors’ characters; a card’s Play steps over them.

Hooks

These labels are run by Play itself, as HyperTalk’s handlers were:

Values

Play starts with no values. set, ask and a picked choice (its label, and its set: pairs) keep them; when and branch read them; a say shows one as $name. A stack’s global_kv sets where Play begins (start).

The tell bridge

On the web a set on tell. is also told to the page the board is on: set tell.world "meteor" keeps the value, as any set does, and the board raises sb-tell on its wrapper with {to: "world", what: "meteor"}. The walker keeps a play’s tells in order too, on the web and on the desktop alike (2026-11-06). On the desk a tell to desk runs when it is open <uri>, toast <words> or pin; any other tell is listed there, never run. StarBoard on the web shows a tell in its status line. On s2ar.dev’s home:

A page of your own hears the same event:

document.addEventListener("sb-tell", (e) => console.log(e.detail.to, e.detail.what));

The event bridge

The tell bridge’s other half (2026-11-06): the page tells the board. An sb-event on a board’s wrapper, while it plays, runs label on.<name> on every card that has one. Before the handlers run, the event’s name is kept at event.name and each of its words at event.<word> (the last event’s are cleared first), so a handler, or the line the reader goes on to, reads them: when event.kind equals note, $event.by.

board.dispatchEvent(new CustomEvent("sb-event", { detail: { name: "strike", words: { at: "0.4,0.5" } } }));

A button needs no script of its own: <button data-sb-event="ping" data-sb-words="by=reader" data-sb-board="<the board's id>"> sends its board the event when pressed. The desktop’s walker takes the same events (love-shared board/stepper.lua’s fire), so a world’s strike or a song’s beat can reach a card as on.strike or on.tune.beat.

Where it runs

On a card in StarBoard (the desktop app’s Play mode, with a stepping debugger), and on any board published to the web (staros web ingest-board, then a board block in a page: the stack format is starboard/1). The tutorial runs here on its own page too.

On the web, a board you can edit has a bench too: Bench in its bar shows, while Play runs, the card being played and its script with the next line marked (press a line’s number for a breakpoint: Play stops before it), Step and Continue, the values the play keeps (the ones the last change touched marked), the tells it raised, the events its cards answer (fire one from there, or any by name), and the trace. A card’s Graph, in its inspector while you edit, draws its script as a flow: a column a label, a node a command, a path a jump. Edit it there: move, remove or add a command, point a jump elsewhere, rename a label. Each edit is made to the script’s text, as if typed, so comments and spacing stay. The board has the parts of both.