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
| Line | What 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). |
end | Ends 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:
label openCard: where the script starts when its card opens (without it, the first line);label closeCard: run as Play leaves the card, to its nextend(it may set values; it cannot hold on a line);label onClick: run when the reader clicks the card while it plays;pass mouseUphands the click on to the background card beneath. A card with noonClickhands it on by itself;label on.<event>: run when the page sends the board that event while it plays (below), on every card that has it, the playing card first. LikeonClickit cannot hold on a line: asayends it, and the values it set stay.
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:
tell.world:meteor(a ball of lava dropped on the crater),comet(a ball of ice),flash(the light alone, no op on the world’s tape),take(the session as a tape cart: the world as it opened and every strike at its frame, downloaded under the tutorial);tell.act: a tool opened beside the tutorial (starlab,starboard,starlore,startune,starsaga,desk);tell.camera:orbit(one slow turn around the crater).
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.