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

[[nav: reference | here=formats]]

<div class="doc">

# `staros.script/1` — a markdown note you play as pages

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

*The scripts program's phase 2 (2026-10-30; the log is `docs/working-scripts-2026-10.md`). The operator, 2026-10-29: "the
way markdown is used for a script is an idea we should implement in starlore", after windowpane, whose stories are
files a person writes in the editors they know. Her rulings: a script is first PAGES YOU PLAY, and its directions are
written ON THE PAGE as one-line `::` lines.*

A script is a plain StarLore note. Any editor can write it; StarLore plays it (Play, `starlore://play/<slug>#<page>`).
The compiler is love-shared `play/script.lua` (pure); the per-page table is `play/fold.lua`; the player is
`play/player.lua`. StarBoard's animatic (the program's phase 3) is to build the same page shape from a storyboard and
play it on the same player.

## An example

```
+++
kind = "script"
title = "The lights go out"
+++

## 1 · A dark room
::music[src=rain]::
::style[name=sidebar]::

The candle gutters.

## 2 · Crash
::sfx[src=lighter.wav]::

*crash!*  the lights go out...

## 2.5 · In the dark
::music[off]::

Nothing but the rain.
```

## The front matter

All values are strings (StarLore writes strings only).

| key | |
|---|---|
| `kind = "script"` | required: a note with it is a script (it makes no review cards) |
| `title` | the script's title |
| `start = "<id>"` | the page a first opening lands on (else the first page; a later opening lands where the reader left off) |
| `style = "<name>"` | the style every page starts with; `::style[off]::` returns to it |
| `format = "staros.script/1"` | optional; any other value is refused |

## Pages

- A `## ` line (outside a code block) starts a page.
- `## <id> · <title>` (a middle dot, U+00B7, with a space before it) names the page's **id**: up to 32 of letters,
  digits, `_ . -`. Every studies shot id (`F2`, `L`) is a page id. Without the dot, the id is the title's slug
  (lowercase, runs of anything else a `-`); a title that slugs to nothing (`## 暗い部屋`) is refused, with the fix.
- Ids are case-sensitive, and two that differ only by case are refused, so a link is never ambiguous.
- **Order is the document's.** An id is an address, never a position: a page inserted as `## 2.5 · …` between 2 and 3
  breaks nothing, and links, bookmarks and a reload find pages by id. Numeric ids that fall back are a warning.
- Text before the first `##` is the preface, never played (StarLore writes a `# title` there).
- A `#` after the first page is refused (kept for chapters); `###` and deeper are headings inside a page.
- Code blocks are opaque: no page and no direction inside one.
- Back follows the reader's own path; with no path behind, the page before.

## Directions

One per line, alone on it: `::name[args]::` (love-shared `starlore/fences.lua`, the one-line LEAF form). The vocabulary
is closed; an unknown name is refused with a "did you mean".

| line | lasts | meaning |
|---|---|---|
| `::music[src=…, vol=…]::`, `::music[src=…, once]::`, `::music[off]::` | sticky | loops under the pages, or plays once through with `once` (a bed: the scripts program's ruling 6); the same track named again keeps playing (a new `vol` only sets the volume); `off` stops it |
| `::style[name=…]::`, `::style[off]::` | sticky | a look the host draws (StarLore: `plain`, `sidebar`, `title`); `off` returns to the front matter's style |
| `::sfx[src=…, vol=…]::` | each entry | plays on every entry to the page, forward or back, never on a reload; several fire in order |
| `::sfx[src=…, loop]::` | the page | loops while the page shows; the next page naming the same loop keeps it going |
| `::wait[2s]::`, `[500ms]`, `[2s, hold]` | the page | moves on by itself after the time (0 < t ≤ 600 s); `hold` refuses Next until then (Back always works) |
| `::next[to=<id>]::`, `::next[off]::` | the page | where Next goes; `off`: no Next, the reader picks a link |
| `::image[…]::`, `::audio[…]::`, `::video[…]::` | the page | page media (block form too: `::image[src=…]` … `::`, the body its caption) |

- **A song by name** (2026-11-02 night, the scripts program's phase 3b): `::music[src=tune://<song>, once]::` plays
  that StarTune song's newest bounce, `tune://<song>#<section>` a section's newest bed (`docs/sound.md`, the address);
  a song not bounced yet is a warning naming what to do (StarTune's `song.bounce`), and the page plays without it.
- **Arguments:** `key=value`, quoted or bare; a bare word is a flag (`off`, `once`, `loop`, `hold`, a time). A key or
  flag a direction does not take is refused. `vol` is 0 to 2, as a placement's (`docs/sound.md`); a host that plays to
  1 plays above it as 1. (It was 0 to 1 until 2026-10-30.)
- **Sticky** means folded once into a per-page table (`fold.lua`): a page's row is every sticky value after its own
  settings, with where each was set, so a jump, a bookmark or a reload lands in the state reading straight through
  would have given.
- `::open`, `::do` and `::wait[run=…]` are reserved: they arrive with the cross-app phase (a page that opens a link or
  asks an app to act, risk-gated).

## Links

- `[text](#<id>)` jumps to a page; its target is checked when the script compiles.
- `[[slug]]` opens the note; any other `scheme://` link opens through love-shared `links.lua`.
- Inline HTML is shown as text, with a warning.

## Where a `src` points

One grammar, love-shared `sound/ref.lua` (`docs/sound.md` § One way to embed a sound; corrected 2026-10-30: this
section called the device's sound store "StarBoard's" and said StarLore had none, while StarLore's own takes were in
it):

- a store sound: `vault://sound/<sha16>.wav`, its short form `sound:<sha16>`, or a bare `<sha16>`;
- a name (`rain`, `rain.wav`): first the one file in StarLore's media store of that original name (what phase 2's
  scripts played; two are refused, naming both), else the newest sound in the device's store named so (a sound brought
  in or made, by its card's label or the file it came as);
- `vault://media/<file>`: StarLore's media store, its legacy;
- a store sound not on this device yet is fetched; the page plays without it until it has come, and the author strip
  says "fetching"; one found nowhere is a warning (the page plays without it, and the strip names it);
- refused: a path (`/`, `\`, `..`, a drive letter), a web address, or another scheme. Notes travel to the phone.

New sounds come into the store as 16-bit WAV (a drop or a capture in StarLore; StarLore's `media.audio_to_store` moves
the old ones), so name them as they were dropped, with or without the extension.

## Errors and warnings

A script that does not compile opens on an **error page**: each problem with its body line (as StarLore's editor
numbers lines), the page it is on, the line's own text, what is wrong and the fix. Fixing the note brings Play back on
the same page.

Errors: `no-pages`, `no-id`, `bad-id`, `duplicate-id`, `unknown-direction`, `reserved`, `bad-args`, `two-waits`,
`twice-on-page`, `bad-link`, `next-unknown`, `direction-in-preface`, `h1-in-page`, `unclosed-fence`, `unclosed-code`,
`stray-close`, `bad-format`, `bad-start`, `bad-style`, `bad-src`.

Warnings (never a refusal): `ids-fall`, `unreachable` (no Next and no link reaches a page), `missing-src`,
`inline-html`.

## Not copied from windowpane

Command lines split on spaces with no comments; unknown and orphaned commands ignored in silence; ids read as floats
(3.1 = 3.10); cues in a file of their own, drifting from the text.

<details class="changes">
<summary>The work on this page: the checks that hold it</summary>

[[work: checks | rows=lint/web-reference]]

</details>

<nav class="pager"><a href="../../formats/world-edition/">← formats/world-edition</a><a href="../../">The reference</a><a href="../../cli/guide/">cli/guide →</a></nav>

*Generated by `tools/reference_pages.py` from `docs/formats/script.md`; the twin `bfaad079a7ce` (434093 bytes). The words are a draft.*

</div>
