staros.script/1 — a markdown note you play as pages
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# titlethere). - 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’ssong.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.volis 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,::doand::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 otherscheme://link opens through love-sharedlinks.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 formsound:<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.
The work on this page: the checks that hold it
- FAIL
lint/web-reference
Generated by tools/reference_pages.py from docs/formats/script.md; the twin bfaad079a7ce (434093 bytes). The words are a draft.