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

this page as plaintext

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

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)

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

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.

The work on this page: the checks that hold it
  • FAILlint/web-reference 12 Nov on tower

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