# 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](/#tools) 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

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

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 next `end` (it may set values; it cannot hold on a line);
- `label onClick`: run when the reader clicks the card while it plays; `pass mouseUp` hands the click on to the
  background card beneath. A card with no `onClick` hands 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. Like `onClick` it cannot hold on a line: a `say` ends 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:

```js
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`.

```js
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](/tools/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](/toys-tutorial.html) 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](/reference/board/) has the parts of both.
