<!-- GENERATED by starlens/site/tools/reference_pages.py from the engine's sources: do not edit; run it. -->

[[nav: reference | here=starscript]]

<div class="doc">

# StarScript: the verbs and the tells

<p class="plain"><a href="../starscript.md">this page as plaintext</a></p>

One grammar, one source: `love-shared/dialogue_parser.lua`'s `VALID_VERBS`, parsed for the web at the site's build (`star-web/src/board_script.rs`) and stepped by `board_rt/stepper.js`, a line-for-line port of love-shared's `board/stepper.lua`. The prose is [the StarScript page](https://s2ar.dev/developers/starscript/); here each verb has a one-card board that runs it.

## The verbs

### `say`

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).

[[board: ref-say | w=fill]]

### `pause`

A world editor's beat; on a card Play steps over it.

[[board: ref-pause | w=fill]]

### `label`

A place in the script to go to. Three names are hooks (below).

[[board: ref-label | w=fill]]

### `goto`

Goes to a label in this script, or to a card.

[[board: ref-goto | w=fill]]

### `when`

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.

[[board: ref-when | w=fill]]

### `set`

Keeps a value. A name with dots (<code>door.open</code>) is a path; every card of the stack reads it while Play runs.

[[board: ref-set | w=fill]]

### `end`

Ends the card's script. A card with links, or with cards its script names, offers to go on to them.

[[board: ref-end | w=fill]]

### `wait_for_chat`

block until heard buffer matches

### `branch`

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. *(the grammar's note: multi-way jump on KV equality)*

[[board: ref-branch | w=fill]]

### `commit`

snapshot last-sealed manifest as npc author

### `choice`

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>). *(the grammar's note: choice <label> "<text>" [set:k=v]*)*

[[board: ref-choice | w=fill]]

### `ask`

Asks the reader for a line of text and keeps it at <code>name</code>. *(the grammar's note: ask <kv> "<prompt>")*

[[board: ref-ask | w=fill]]

### `request_file`

The desktop: waits for a file dropped on the window and keeps its path at <code>name</code>. *(the grammar's note: request_file <kv> <kind> "<prompt>")*

[[board: ref-request_file | w=fill]]

### `pass`

In an <code>onClick</code> hook: hands the click on to the background card under it. *(the grammar's note: pass <event_name>)*

[[board: ref-pass | w=fill]]

## The tells

A `set` on `tell.<to>` is kept as any set and told to the page the board is on (`sb-tell`, `{to, what}`). The home answers:

| to | what | |
|---|---|---|
| `tell.world` | `meteor`, `comet`, `flash`, `take` | a strike on the world (a sphere op on its tape), the light alone, or the session taken as a tape cart |
| `tell.act` | `starlab`, `starboard`, `starlore`, `startune`, `starsaga`, `desk` | a tool opened beside the board |
| `tell.camera` | `orbit` | a shot |

On these pages the live view answers `tell.world` (a meteor drops lava, a comet ice, a flash flashes it) and `tell.camera "orbit"` (one turn); the home's tools say so.

[[board: ref-tell-world | w=fill]]

[[view: tell | caption=the board beside it tells the world: meteor, comet, flash]]

<p class="pinned">Rests at frame 240 with the digest <code>23e7eb22801d70df</code> (pinned in <code>api.json</code>; <code>tools/demo_check.mjs</code> holds it).</p>

<details class="ops"><summary>The demo: its world, its ops and its steps</summary>

```json
{
 "world": "cube",
 "ops": [],
 "steps": 240
}
```

</details>

## The events

The other way: 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, after keeping the event's name at `event.name` and its words at `event.<word>` (`board.dispatchEvent(new CustomEvent("sb-event", {detail: {name, words}}))`; love-shared's walker takes the same, `fire`). A button needs no script: `data-sb-event`, `data-sb-words` and `data-sb-board` send it. This card waits for one; the button under it sends `ping` with `by=this-page`.

[[board: ref-event | w=fill]]

<p><button type="button" class="sb-btn" data-sb-event="ping" data-sb-words="by=this-page" data-sb-board="ref-event">Ping the board</button></p>

## Parsing in the page

`board_rt/script.js` parses a card's script in the browser: a port of the build's parser (`star-web/src/board_script.rs`), held to the build's own cases (`tests/board_rt/parse_cases.json`, minted from the Rust) and to the Lua's (`starboard/tests/stepper_cases.json`) by `tests/board_rt/script.test.mjs`. On an editable board the editor parses as you type: Play runs the new script the next time it enters the card, and a line the grammar refuses shows the Lua's words under the script. Rewrite this card's line and play it.

[[board: ref-edit | w=fill | edit=1]]

### `VERBS`

<pre class="sig">VERBS</pre>

The verbs (dialogue_parser.lua's VALID_VERBS), each with the line the graph's palette inserts and what it does. `board: false`: the board's stepper steps over it (an app's verb).

<p class="meta">rust-shared/star-web/src/board_rt/script.js:23</p>

### `TELLS`

<pre class="sig">TELLS</pre>

The tells a page answers (the home's and the reference's; StarScript's reference has the words): `set tell.<to>`.

<p class="meta">rust-shared/star-web/src/board_rt/script.js:42</p>

### `tokenise`

<pre class="sig">tokenise(line)</pre>

dialogue_parser.lua's M.tokenise, as board_script.rs ports it.

<p class="meta">rust-shared/star-web/src/board_rt/script.js:60</p>

### `parse`

<pre class="sig">parse(source)</pre>

A card's script as dialogue_parser.lua's M.parse makes it: `{ok, prog}`, or `{ok: false, err}` in the Lua's words.

```js
// with `parse` from board_rt/script.js and `Stepper` from board_rt/stepper.js
const r = parse('say s2ar "Hello"\nchoice next "Go on"\nend\nlabel next\nend\n');
return { ok: r.ok, kinds: r.prog.commands.map((c) => c.kind), labels: r.prog.labels };
```

Gives, held by `tests/board_rt/examples.test.mjs`:

```json
{
 "ok": true,
 "kinds": [
  "say",
  "choice",
  "end",
  "label",
  "end"
 ],
 "labels": {
  "next": 4
 }
}
```

<p class="meta">rust-shared/star-web/src/board_rt/script.js:116</p>

<details class="changes">
<summary>The work on this page: the commits of the last 30 days on its sources, the work open against them, its checks</summary>

[[timeline: src=love-shared/dialogue_parser.lua,starlens/site/media/house/house.js,starlens/site/content/developers/starscript.md,rust-shared/star-web/src/board_rt/script.js | kinds=commit | days=30]]

[[work: open | src=love-shared/dialogue_parser.lua,starlens/site/media/house/house.js,starlens/site/content/developers/starscript.md,rust-shared/star-web/src/board_rt/script.js]]

[[work: checks | rows=lint/web-reference,node/board-stepper]]

</details>

<nav class="pager"><a href="../board/">← board</a><a href="../">The reference</a><a href="../formats/world-tape/">formats/world-tape →</a></nav>

*Generated by `tools/reference_pages.py` from `love-shared/dialogue_parser.lua`, `media/house/house.js`, `content/developers/starscript.md`, `star-web/src/board_rt/script.js`, `star-web/tests/board_rt/examples.json`; the twin `bfaad079a7ce` (434093 bytes). The words are a draft.*

</div>
