JavaScript and TypeScript binding

The engine’s binding for JavaScript and TypeScript is two packages on npm, for a browser page or for Node. @ripplefx/player carries the engine as a WebAssembly component, in both variants, and the TypeScript API over it. @ripplefx/soundscape is the Web Audio speaker for a campaign’s soundscapes, and is optional. Version 1.5.x of each binds Ripple Effect contract 1.5: a package’s MAJOR.MINOR is the contract, and its PATCH is the package’s own. The source is public at ConnectingTheDots-DCWK/ripple_effect_js_ts_integration.

@ripplefx/player’s code is MIT. The engine inside it is under the Ripple Effect Runtime Licence: free to ship, unmodified in function, as part of your own product. Reproduce the package’s ENGINE-NOTICE wherever your product lists the third-party software it uses. @ripplefx/soundscape carries no engine and is plain MIT.

Packages and installing

npm install @ripplefx/player                        # the player
npm install @ripplefx/player @ripplefx/soundscape   # and the Web Audio speaker

Package	Exports	Runs in	Needs
`@ripplefx/player`	`Campaign`, `Session`, `Player`, `SoundscapeDriver`, the effects, the values, the errors	browsers, Node 22.18 or later	nothing else
`@ripplefx/soundscape`	`WebAudioSpeaker`, `amplitude`	browsers (Web Audio)	`@ripplefx/player`

Both are ES modules. The player ships dist/, both engine variants under generated/, LICENSE and ENGINE-NOTICE.

Bundlers

The package names each engine file as new URL(…, import.meta.url), which Vite, webpack 5, esbuild and Astro all follow: the bundler copies the .wasm files beside the page with no configuration. In Node the files are read from disk.

To serve the engine’s files from somewhere else, a CDN say, pass wasmBase to Campaign.load or Campaign.fromFiles. It is a URL, resolved against the page, holding a python/ and a no-python/ directory laid out as the package’s generated/ is; each holds engine.core.wasm, engine.core2.wasm and engine.core3.wasm. Serve the engine with the page, never from a GitHub release: release downloads send no Access-Control-Allow-Origin, so a browser cannot read them.

Serving

What	Rule
`.wasm` files	Serve as `application/wasm`, so the engine compiles while it downloads. Any other type still works, after the download. A long cache lifetime on a hashed name.
Cross-origin isolation	Not needed. No `COOP` or `COEP` header: the engine uses no `SharedArrayBuffer` and no threads.
`X-Content-Type-Options: nosniff`	Set it; with the `.wasm` type it is the one header a static host has to be told about.
The campaign	A compiled campaign (the editor’s Export → Campaign) served as a folder, as it is, `campaign.json` at its root.
A campaign on another origin	That origin sends CORS headers on every file of the bundle.
Media on another origin	That origin sends CORS headers, or Web Audio hears the file as silence.

Media paths

A media path is the author’s own folder and file names, spaces, accents, # and ? included. It is URL-encoded a segment at a time, never as a whole, because an encoded / names a different file. Campaign.load does this for you. For a resolver of your own, the package exports the function it uses.

Export	Signature	Does
`encodePath`	`(path: string) => string`	Encodes each `/`-separated segment with `encodeURIComponent` and joins them with `/`.

Choosing the variant

The engine comes in two variants, python (with the Python interpreter) and no-python. Campaign.load and Campaign.fromFiles read campaign.json before any engine exists and pick one from the python option.

`python`	Loads
`'auto'` (default)	`python` when the bundle’s `needs` includes `python`, otherwise `no-python`. A bundle older than format 15 cannot say, and gets `python`. From format 15 an absent `needs` means none.
`true`	`python`, always.
`false`	`no-python`, always. A bundle whose `needs` includes `python` is refused with `NeedsPython`. A bundle older than format 15 opens, with its scripts unavailable.

Variant	Over the wire
`python`	about 1.36 MB, and the WASI shim it imports
`no-python`	about 0.31 MB

The python variant runs with a WASI that has nothing behind it: no files, no environment, no network. The engine asks it for a clock and for entropy.

In an engine without Python a Script node reports and a snippet renders a warning in place; session.pythonAvailable is false, and consoleFeed answers an unavailable failure rather than throwing.

Platforms

Platform	Status
Chromium	Tested: every conformance fixture through a Vite bundle loading each bundle over HTTP; the speaker’s voices.
Firefox	Tested, as Chromium.
WebKit	Tested, as Chromium, in WebKitGTK. Safari on macOS and iOS is not yet confirmed for the speaker’s tracks.
Node 22.18 or later	Tested: every conformance fixture, through `Session` and through `Player`, in both variants. No speaker.

The fixtures are 24 with Python and 21 without.

The engine runs on the calling thread. There is no Worker transport: every verb is synchronous, and a Worker would make every verb a promise. A page whose campaign runs heavy scripts can run the binding in a Worker of its own and post the effects across.

For the engine’s native and web targets, see Engine targets.

The engine

No engine class is exported. A Campaign loads its engine: each .wasm file is compiled once per page and cached by URL, and each campaign gets an instance of its own, so a trap ruins one campaign and no other.

Export	Kind	What it is
`Variant`	type	`'python' \| 'no-python'`.
`EngineOptions`	interface	`{ wasmBase?: string \| URL }`, extended by `CampaignOptions`.

Member of `Campaign`	Type	What it is
`variant`	`Variant`	Which engine the campaign was opened in.
`hasPython`	`boolean`	Whether that engine has the interpreter.
`engineVersion`	`string`	The engine’s version, `MAJOR.MINOR.PATCH`.

Campaign

A compiled campaign, opened in an engine of the variant it needs. The constructor is private.

Opening

static load(base: string | URL, options?: CampaignOptions): Promise<Campaign>
static fromFiles(files: BundleFiles, options?: CampaignOptions): Promise<Campaign>

Function	Takes	Does
`Campaign.load`	`base`: a URL ending in `/`, or the URL of `campaign.json` itself. A relative URL resolves against the page; a URL ending in neither gets a `/`.	Fetches `campaign.json` and every document its tables name (boards, passages, components, scripts, machines, soundscapes) while the engine loads, then opens the campaign. No media bytes are fetched. Media resolve against `base`, a segment at a time.
`Campaign.fromFiles`	`files`: a `Map` or a plain object of bundle path to `string` or `Uint8Array`. Must contain `campaign.json`.	Opens a bundle you already hold. A string is a document; bytes are an asset handed to the engine. Media resolve only through `options.mediaUrl`: without it no picture or sound has a URL.

BundleFiles is ReadonlyMap<string, string | Uint8Array> or Readonly<Record<string, string | Uint8Array>>.

`CampaignOptions`

Option	Type	Default	Meaning
`python`	`boolean \| 'auto'`	`'auto'`	Which variant to load. See Choosing the variant.
`fetch`	`RequestInit`	none	Passed to every `fetch` the loader makes: credentials, a signal.
`mediaUrl`	`(path: string) => URL \| string \| undefined`	none	Where a media file is, for a campaign opened with `fromFiles`. A string resolves against the page. Ignored by `load`.
`wasmBase`	`string \| URL`	beside the package	Where the engine’s files are served. See Bundlers.

Members

Member	Signature	Answers
`manifest`	`CampaignManifest`	The bundle’s `campaign.json`, as the engine read it.
`variant`, `hasPython`, `engineVersion`		See The engine.
`mediaUrl`	`(index: number) => URL \| undefined`	Where the media file at `index` in `manifest.media` is, or `undefined`.
`mediaPath`	`(index: number) => string \| undefined`	That file’s path in the bundle.
`coverUrl`	`URL \| undefined`	Where the project’s cover picture is, if it has one.
`soundscape`	`(index: number) => Soundscape`	The soundscape at `index` in `manifest.soundscapes`. Throws `BundleError` for one that will not read.
`boardIndex`	`(id: string) => number \| undefined`	The index of the board whose catalog id is `id`.
`validate`	`() => { message: string; location: string }[]`	What is wrong with the bundle, each problem and where. Empty when nothing is.
`coerceCvar`	`(type: string, value: RippleValue) => RippleValue \| undefined`	The value as a console variable of `type` would hold it, or `undefined` when it does not fit.
`asText`	`(value: RippleValue) => string`	The value as the story prints it, the text a snippet shows.
`describeCvarRefusal`	`(name: string, type: string, value: RippleValue) => string`	The sentence the engine refuses writing `value` to a variable of `type` with. English, for showing.
`session`	`(start?: SessionStart) => Session`	A session on this campaign, not yet started. See Session.

coerceCvar, asText and describeCvarRefusal need no session.

`CampaignManifest`

Field	Type	Meaning
`format`	`number`	The bundle format.
`generator`	`string`, optional	What wrote the bundle.
`textFormat`	`string`	`markdown`, or `html` for a campaign exported as HTML.
`project.title`	`string`
`project.description`	`string`
`project.defaultLocale`	`string`	The language the story was written in.
`project.locales`	`readonly string[]`	Every language the campaign has.
`project.cover`	`string`, optional	The cover picture’s path in the bundle.
`entries`	`readonly number[]`	The boards a story may begin on, as indices into `boards`.
`boards`, `passages`, `components`, `scripts`, `media`, `machines`, `soundscapes`	`readonly BundleEntry[]`	The bundle’s tables. A `BundleEntry` is `{ id, name, path }`, all strings.
`cvars`	`readonly { name: string; type: string; default: RippleValue }[]`	The console variables the campaign declares.
`needs`	`readonly string[]`	What the campaign needs of an engine: `python` when it runs scripts.

Session

The host API’s verbs, one to one with the engine’s. Every verb runs synchronously and answers the ordered effects it led to; the last of them says where the story now is.

campaign.session(start?: SessionStart): Session
Session.create(campaign: Campaign, start?: SessionStart): Session   // the same
Session.resume(campaign: Campaign, save: string, start?: ResumeStart): Session

Session.create throws BundleError when the campaign cannot be started as asked. Session.resume picks up a save that pause() or checkpoint() wrote, and throws ResumeError when the save no longer fits the campaign. A resumed session is started with start(), like a new one.

`SessionStart`

SessionStart is SessionOptions and these fields.

Field	Type	Default	Meaning
`seed`	`number \| bigint`	`0`	What the dice are seeded with. The one setting to always choose: left out, every reader rolls the same dice.
`locale`	`string`	`project.defaultLocale`	The language to begin in.
`board`	`number`	`manifest.entries[0]`, or `0`	The board to begin on, by index into `manifest.boards`.
`entryNode`	`string`	the board’s entry	The node to begin at.
`digest`	`string`	none	A label stamped on every save this session writes, a hash of the bundle say, so you can tell your own saves apart. The engine carries it and never compares it.

`ResumeStart`

ResumeStart is SessionOptions and seed (number | bigint, default 0). A save carries no dice state: to roll on where the story was, copy generator from the old session to the resumed one.

`SessionOptions`

Each defaults to the engine’s own.

Option	Type	Default	Meaning
`stepBudget`	`number`	`1048576`	How many node turns one board may take before the run is called a runaway and the story fails, rather than hang the page.
`silentJumpLimit`	`number`	`64`	How many boards may hand over in a row without a word of story before the story fails. `0` fails the first such jump.
`loopLimit`	`number`	`512`	How often one loop node may go round in one board run before the story fails. `0` is no ceiling.
`scriptLimits`	`ScriptLimits`	the engine’s	`{ deadlineMs, memoryBytes, recursionDepth }`, all numbers: how long a script may run, how much it may hold, how deep it may recurse.
`untranslated`	`'report' \| 'fall-back'`	`'report'`	A passage with no text in the language being read: `report` shows it empty and names the language; `fall-back` shows the default language’s text and still names it.
`trace`	`boolean`	`false`	Collect the run trace in every batch, as `trace` effects.
`tracePayloads`	`boolean`	`false`	Include payloads in the trace.

Verbs

Verb	Answers	Notes
`start()`	`Effect[]`	Begins the story, or a resumed one.
`choose(index?: number)`	`Effect[]`	Takes the choice at `index` among those offered. With none, the reader leaves: the passage flows nowhere and the story ends there.
`answer(values?: Answers)`	`Effect[]`	Answers the prompt showing. Values go to the engine exactly as given. With none, the reader leaves, as with `choose()`.
`elapsed()`	`Effect[]`	Says the wait a `hold` asked for is over. A `Player` calls it for you.
`setLocale(locale: string)`	`Effect[]`	Reads on in another language; the passage showing is shown again in it.
`restart()`	`Effect[]`	Starts over, forgetting every entity and keeping the language.
`stop()`	`Effect[]`	Ends the session for good.
`pause()`	`Paused`	Puts the story down and ends the session, answering a save. Only on a passage or a prompt: anywhere else nothing stops, and there is no save and no effect.
`checkpoint()`	`string \| undefined`	A save of where the story is, without putting it down. `undefined` unless the story is on a passage or a prompt.
`writeCvar(name, value)`	`{ outcome, effects }`	Writes a console variable.
`resetCvar(name)`	`{ outcome, effects }`	Puts a console variable back to its default.
`resetAllCvars()`	`Effect[]`	Puts every console variable back.
`removeEntity(key)`	`{ removed: boolean; effects: Effect[] }`	Forgets the entity under `key`.
`consoleFeed(code: string)`	`{ result: PythonResult; effects: Effect[] }`	One line of Python against the live story: its entities, its variables, its sounds.

A refused verb throws HostError and nothing moves. Paused is { save?: string; effects: Effect[] }. Answers is a Map or a plain object of field name to value; a nested plain object is taken as a map.

A cvar write’s outcome is 'done', 'unknown' (no such variable), or { refused: string }, carrying the engine’s sentence in English, for showing and never for parsing.

Readers

Each is a snapshot as of the last verb.

Reader	Type	What it is
`campaign`	`Campaign`	The campaign the session plays.
`board`	`number`	The index of the board the story is on.
`locale`	`string`	The language being read.
`defaultLocale`	`string`	The language the story was written in.
`ambience`	`Ambience \| null`	The soundscape in force, or `null` for silence.
`entities`	`Entity[]`	Everything the story has made.
`memory`	`Memory`	What the story remembers of its nodes and machines.
`cvars`	`CvarSnapshot[]`	Every console variable, with its default and value.
`guard`	`GuardReport`	What the script guard has given up on this playthrough.
`pythonAvailable`	`boolean`	Whether this session’s engine can run the campaign’s scripts.
`describeCvarWrite(name, value)`	`string \| undefined`	Why writing `value` to `name` would be refused, or `undefined` if it would not.

GuardReport is { abandoned: readonly string[]; refused: number; exhausted: boolean }: the names the scripts stopped at the deadline ran under, sorted with repeats kept; how many runs were never started; whether no script will be started again.

Python results

`PythonResult` field	Type	Meaning
`value`	`RippleValue`	The last expression’s value, or `null`.
`output`	`string`	Everything it printed.
`error`	`PythonFailure`, optional	Why it stopped.

`PythonFailure` field	Type	Meaning
`type`	`string`	The Python exception’s class (`NameError`, `SyntaxError`), or one of the engine’s labels: `timeout`, `refused`, `closed`, `host-error`, `unavailable` (an engine without Python).
`message`	`string`
`line`	`number`, optional
`traceback`	`string`, optional

Trace and dice

Member	Signature	Does
`setTrace`	`(enabled: boolean) => void`	Turns the run trace on or off.
`setTracePayloads`	`(enabled: boolean) => void`	Turns trace payloads on or off.
`generator`	`{ lo: number; hi: number }`, get and set	The dice’s state. A save carries none; hand it to a resumed session to roll on where the story was.

Effects

An Effect is a plain object tagged on kind, so a switch over effect.kind is checked for exhaustiveness. Times and indices are numbers, story values are RippleValues, and a picture or a sound comes with its URL.

`kind`	Fields	Notes
`show`	`passage: Passage`	A passage. A turn.
`ask`	`prompt: Prompt`	A prompt. A turn.
`hold`	`ms: number`	A wait. A turn. Call `elapsed()` once `ms` have passed; a `Player` does.
`ended`	`title?: string`, `ranOut: boolean`	The story is over as the author wrote it, or ran out of road (`ranOut`). A turn.
`failed`	`message: string`, `node?: string`	The story stopped on an error. `message` is English, for showing and never for parsing. A turn.
`stopped`	none	The session ended, after `stop()` or `pause()`. A turn.
`jumped`	`board: number`, `node?: string`	The story moved to another board. `board` indexes `manifest.boards`; it is not the catalog id.
`ambience`	`ambience: Ambience \| null`	The soundscape in force changed. `null` is silence.
`audio`	`command: AudioCommand`	What a speaker is told. See Sound.
`changed`	`entities?`, `memory?`, `cvars?`	Which of the stores moved, each with its new contents.
`callback`	`event: CallbackEvent`	A named callback the author declared. See Named callbacks.
`trace`	`event: RunEvent`	Only with `trace` on. The engine’s own `{ tag, val }` shape, kebab-case tags and all, unmapped.

The six turns (show, ask, hold, ended, failed, stopped) are the type Turn; one is always the last effect of a batch. isTurn(effect: Effect): effect is Turn tells them apart.

Records

`Passage`

Field	Type	Meaning
`node`	`string`	The passage’s node.
`title`	`string`
`text`	`string`	The prose, after its snippets ran, in the language being read. Markdown, or HTML when `manifest.textFormat` is `html`. Render it with a library and sanitise what it produces.
`choices`	`readonly Choice[]`	The choices offered, in order.
`snippets`	`readonly { code: string; isInline: boolean }[]`	The snippets the prose ran.
`media`	`ReadonlyMap<string, URL>`	Every link in the prose that names a file of the campaign, to that file’s URL. Links with no URL are absent.
`mediaIndex`	`ReadonlyMap<string, number>`	The same links, to the media index each names.
`untranslated`	`string`, optional	The language the passage has no text in, when that is why it is empty.
`soundscape`	`Soundscape`, optional	The soundscape the passage plays.
`silence`	`boolean`	The passage asks for silence.

`Choice`

Field	Type	Meaning
`port`	`string`	The choice’s port.
`text`	`string`
`available`	`boolean`	`false` for a choice that has run out: shown, and refused with `choice-spent` if taken.

`Prompt` and `PromptField`

Field	Type	Meaning
`Prompt.node`	`string`
`Prompt.title`	`string`
`Prompt.fields`	`readonly PromptField[]`
`PromptField.name`	`string`	The key to answer it under.
`PromptField.type`	`string`	The field’s type.
`PromptField.default`	`RippleValue`

`Ambience`

Field	Type
`soundscape`	`Soundscape`
`board`	`number`
`node`	`string`

`Soundscape` and `Track`

Every time is in milliseconds.

Field	Type	Meaning
`Soundscape.id`	`string`
`Soundscape.name`	`string`
`Soundscape.length`	`number`
`Soundscape.looping`	`boolean`
`Soundscape.fadeIn`, `fadeOut`	`number`
`Soundscape.volume`	`number`
`Soundscape.tied`	`boolean`
`Soundscape.tracks`	`readonly Track[]`	One clip each.
`Track.media`	`number`	Index into `manifest.media`.
`Track.lane`	`number`
`Track.start`	`number`	Where on the timeline the clip begins.
`Track.clipStart`, `clipEnd?`	`number`	Where in the file it begins and ends.
`Track.volume`, `speed`	`number`
`Track.fadeIn`, `fadeOut`	`number`	The clip’s own fades.
`Track.mode`	`TrackMode`	`auto`, `looping` or `once`.
`Track.interval`	`number`	For `auto` only: the silence between one play ending and the next; `0` is a gapless bed.

`Entity`, `Memory`, `CvarSnapshot`, `Changed`

Field	Type	Meaning
`Entity.key`	`string`
`Entity.component`	`string`, optional
`Entity.label`	`string`
`Entity.values`	`RippleValue`
`Memory.nodes`	`RippleValue`
`Memory.machines`	`readonly (readonly [string, string])[]`	Pairs of strings, one per state machine.
`CvarSnapshot.name`, `type`	`string`
`CvarSnapshot.default`, `value`	`RippleValue`
`Changed.entities`	`readonly Entity[]`, optional	Present when the entities moved.
`Changed.memory`	`Memory`, optional	Present when memory moved.
`Changed.cvars`	`readonly CvarSnapshot[]`, optional	Present when the console variables moved.

`CallbackEvent`

Field	Type	Meaning
`callback`	`string`	The author’s name for it, the key a handler is registered under.
`event`	`CallbackEventName`	What it was declared on, dotted: `cvar.changed`.
`board`	`number`, optional
`node`	`string`, optional
`name`	`string`, optional
`from`, `to`	`RippleValue`, optional
`index`	`number`, optional

CallbackEventName is one of story.started, board.entered, soundscape.changed, passage.shown, choice.taken, delay.started, delay.elapsed, story.ended, story.failed, cvar.changed, entity.spawned, entity.removed, entity.renamed, entity.field.changed, machine.state.entered, node.entered, node.exited, node.failed. CallbackKind is the same set as the engine’s WebAssembly interface spells it, with dashes (cvar-changed).

`AudioCommand`

`kind`	Fields
`play`	`soundscape: Soundscape`, `fadeInMs: number`
`stop`	`fadeOutMs: number`
`cut`	none
`cue`	`media: number`, `url?: URL`, `volume: number`, `speed: number`, `node?: string`

`RunEvent`

One step of the run trace, as the engine’s WebAssembly interface spells it. A debugging view.

`resolveLink`

resolveLink(passage: Passage, src: string): string

Rewrites one link in a passage’s prose to the URL of the file it names, through passage.media, or answers src unchanged. The prose keeps the author’s own links; give this to your renderer’s image hook.

Values

A story’s value is a RippleValue.

Story type	JavaScript
Null	`null`
Boolean	`boolean`
Int	`bigint`, all 64 bits
Float	`number`, NaN and the infinities included
String	`string`
List	`readonly RippleValue[]`
Map	`ReadonlyMap<string, RippleValue>`, in the engine’s key order

Int and Float are different types and stay different: 7n is an Int and 7 a Float, and a story comparing them gets false. Times, indices and voice ids are JavaScript numbers. A seed takes either.

Writing a value back:

a plain object is taken as a map, in its own key order, so { gold: 3n } is accepted where a map is meant;
undefined is written as null;
a bigint outside 64 bits throws RangeError;
any other type (a function, a symbol) throws TypeError.

Export	Signature	Does
`asRecord`	`(value: RippleValue) => Record<string, RippleValue>`	A map value’s entries as a plain object; `{}` for anything else.

Player

The loop over a session: it delivers every effect in order, keeps the turn the last one named, waits out a hold, applies the story’s sound and dispatches named callbacks.

new Player(session: Session, handlers: PlayerHandlers)

`PlayerHandlers`

Handler	Type	Meaning
`onEffect`	`(effect: Effect) => void`	Required. Every effect, in the order the engine produced it.
`onError`	`(error: unknown) => void`	An error from a verb the player made by itself (the `elapsed()` after a hold), or thrown by a handler while a batch was being delivered. Without it, a failure after a hold is an uncaught exception thrown from a timer, and a handler’s error goes to `reportError`, or `console.error` where there is none.
`audio`	`SoundscapeDriver`	Where the story’s sound goes. Every `audio` effect is applied to it as well as handed to `onEffect`. Without one, nothing is heard.

Members

Member	Signature	Does
`session`	`Session`	The session underneath, for what the player does not wrap: the state readers, `checkpoint`, cvars, entities. A verb called on it goes round the player: a pending hold is not cancelled and may wake a later turn, and nothing it answers reaches `onEffect` or the sound.
`handlers`	`PlayerHandlers`	As given.
`turn`	`Turn \| undefined`	The last passage, prompt, wait or ending delivered.
`start()`	`void`	`session.start()`, delivered.
`choose(index?)`	`void`	`session.choose(index)`, delivered.
`answer(values?)`	`void`	`session.answer(values)`, delivered.
`setLocale(locale)`	`void`	`session.setLocale(locale)`, delivered.
`restart()`	`void`	`session.restart()`, delivered.
`stop()`	`void`	`session.stop()`, delivered.
`pause()`	`string \| undefined`	`session.pause()`: delivers its effects and answers the save, or `undefined` and nothing stopped unless the story is on a passage or a prompt. Still answers after `dispose()`, so a page can save on its way out. Not `SoundscapeDriver.pause`.
`consoleFeed(code)`	`PythonResult`	`session.consoleFeed(code)`; what it led to is delivered like any verb’s effects.
`onCallback`, `onAnyCallback`, `clearCallbacks()`, `callbackMisses`		See Named callbacks.
`dispose()`	`void`	Stops waiting on any hold and delivers nothing more. After it, `start`, `choose`, `answer`, `setLocale`, `restart` and `stop` do nothing at all, and `pause` still answers a save.

A verb on the player throws whatever the session’s verb throws (HostError, EngineTrap), to you.

Delivery

For each effect of a batch, in order:

a turn becomes turn;
an audio effect is applied to audio;
a callback effect is dispatched to its handlers;
the effect is handed to onEffect.

A handler that throws is reported, and the rest of the batch still arrives. A handler that calls dispose() stops the batch there.

Holds

When the last effect of a batch is a hold, the player sets a timer for ms and then calls session.elapsed() and delivers what it answers. Any verb called while the hold is pending cancels the timer first, so a restart during a pause in the story does not wake the story a moment later. An error from that elapsed() goes to onError.

Named callbacks

An author publishes named points in the editor: chapterTwo when a board is entered, goldChanged when a variable moves. A callback carries no code; you register the handler against its name.

Member	Signature	Does
`onCallback`	`(name: string, handler: CallbackHandler) => () => void`	Calls `handler` whenever the callback the author named `name` fires, replacing any handler already under that name. Answers the function that removes it.
`onAnyCallback`	`(handler: CallbackHandler) => () => void`	Calls `handler` for every callback that fires, registered or not. Answers the function that removes it.
`clearCallbacks`	`() => void`	Forgets every callback handler. The miss count is kept.
`callbackMisses`	`number`	How many callbacks fired with nothing registered under their name.

CallbackHandler is (fired: CallbackEvent) => void. The named handler runs first, then every onAnyCallback handler, then onEffect receives the same event as { kind: 'callback', event }.

A handler runs where the engine placed the callback, inside the verb: a callback about a passage arrives before the passage does.
A handler must not call a verb on the player. A verb called while a batch is being delivered, from a handler or from onEffect, throws ReentrantVerb. Schedule it with queueMicrotask or setTimeout.
A name nobody registered is not an error. The story plays the same, and callbackMisses counts it.
A handler that throws does not stop the story. The error goes to onError, and the rest of the batch still arrives.
A name is a published API, the only thing joining the author’s declaration to your code. Renaming one in the editor breaks the handler registered under the old name.

The names and their events are listed in Host callbacks.

Sound

Three layers: the session says what the story asks for as audio effects; the engine’s scheduler decides every voice, gain and handover from them; a speaker makes the sounds. SoundscapeDriver drives the scheduler and does every duty it asks of a host. A speaker is the only part that touches an audio API.

const audio = new SoundscapeDriver(campaign, speaker, options?);
const player = new Player(session, { onEffect, audio });

`SoundscapeDriver`

new SoundscapeDriver(campaign: Campaign, speaker: Speaker, options?: SoundscapeOptions)

`SoundscapeOptions`	Type	Default	Meaning
`maxCues`	`number`	`8`	How many cues may sound at once; the oldest gives way.
`gainStep`	`number`	`0.004`	The smallest change of gain worth writing.
`tickMs`	`number`	`25`	How often the scheduler is ticked while anything sounds.
`muted`	`boolean`	`false`	Starts muted: every gain written as zero, and remembered.
`now`	`() => number`	`performance.now`	The clock, in milliseconds, monotonic.

Member	Signature	Does
`apply`	`(command: AudioCommand) => void`	Obeys one of the session’s audio commands. A `Player` with `audio` calls it for you. A `play` whose soundscape was copied, rebuilt or parsed from JSON throws `RippleError`: pass the effect’s own object, or one `campaign.soundscape()` answered. A `cue` with no `url` is ignored. Does nothing after `dispose()`.
`setMuted`	`(muted: boolean) => void`	Mutes or unmutes at once; the gains the scheduler would have written are kept.
`muted`	`boolean`	Whether it is muted.
`pause`	`() => void`	Holds every voice where it is, and the clock with them, a hidden tab say. The story is not touched: not `Player.pause`.
`resume`	`() => void`	Lets them go again.
`playing`	`string \| undefined`	The id of the soundscape in force: the one sounding, or the one waiting its turn while the last fades out.
`idle`	`boolean`	Whether nothing sounds, waits or cues.
`dispose`	`() => void`	Stops everything and lets every voice go.

What the driver does, so that a speaker does not:

the timer;
the scheduler’s commands;
a late voice: the time voice() took, times rate, is added to from, and a looping clip wraps inside its loop; a clip already over plays nothing;
gains written before a voice was ready, applied when it is;
tracks whose file has no URL, told to the scheduler as silence rather than tried;
mute, which is the scheduler’s: it writes zero and remembers;
the handover between soundscapes, which never overlap. A handover waits for the outgoing soundscape’s fade-out.

The `Speaker` contract

interface Speaker {
  voice(url: URL, role: VoiceRole): Promise<Voice>;
}

type VoiceRole = 'track' | 'cue';

interface Voice {
  play(request: VoicePlay): void;
  setGain(gain: number): void;
  pause(): void;
  resume(): void;
  stop(): void;
  onEnded?: () => void;              // set by the driver
  onDuration?: (ms: number) => void; // set by the driver
}

interface VoicePlay {
  from: number;      // ms into the file
  to?: number;       // ms into the file; the file's end when absent
  gain: number;      // 0 to 1, on the engine's gain scale
  rate: number;      // 1 is as recorded
  looping: boolean;
  loopFrom: number;  // ms: where each turn of a loop comes round to
}

Member	Obligation
`Speaker.voice(url, role)`	Resolves once the voice can begin at once: load the file, or enough of it. Rejects when the file cannot be played; the scheduler hears that as silence and never retries. `role` is a hint: a `track` may be minutes long, a `cue` is a short sound effect that must start on time.
`Voice.play(request)`	Begins at once and replaces whatever the voice was playing. May be called again on the same voice for a gapless bed whose file ended coming round, and must follow on as closely as the API allows. Plays from `from` to `to`, or to the file’s end. When `looping`, reaching `to` comes round to `loopFrom`, not `from`.
`Voice.setGain(gain)`	Writes a new gain, on the same scale as `VoicePlay.gain`. The scheduler writes one every tick a fade moves; smooth between them over a few milliseconds, or a fade is a staircase.
`Voice.pause()`, `resume()`	Hold the voice exactly where it is, and let it go again. The driver pauses every voice together.
`Voice.stop()`	Ends the voice for good and lets its resources go. No `onEnded` follows.
`Voice.onEnded`	Fire once per play, when a non-looping voice reaches the end of what it was given. Never after `stop()`, never for a looping voice.
`Voice.onDuration(ms)`	Fire once, when the file’s length is known. Until then a track played to its file’s end has no end the scheduler can plan a fade-out or a gapless turn for.

The gain scale is cubic. The editor writes a gain to mpv’s volume control, whose curve is cubic, so a speaker that writes amplitude writes gain ** 3: half the gain is an eighth of the amplitude. A speaker that writes the gain as amplitude mixes every soundscape louder in its quiet parts than its author heard it.

A speaker of your own should pass the checks @ripplefx/soundscape passes: a file ends near its length and reports it; a clip ends near its to; a loop never ends; a cue ends near its length; a paused cue ends later by the pause; a stopped voice never ends. The contract is also published as docs/speaker.md.

`@ripplefx/soundscape`

new WebAudioSpeaker(options?: WebAudioSpeakerOptions)

`WebAudioSpeakerOptions`	Type	Default	Meaning
`context`	`AudioContext`	a new one	The context to play in.
`destination`	`AudioNode`	the context’s `destination`	Where every voice goes.
`crossOrigin`	`'anonymous' \| 'use-credentials'`	`'anonymous'`	The CORS mode for a track on another origin.
`cueCache`	`number`	`32`	How many decoded cues are kept for the next time they are cued; the least recently used goes first.

Member	Signature	Does
`context`	`AudioContext`	The context it plays in.
`unlock`	`() => Promise<void>`	Resumes the context unless it is running. Browsers start no sound before the reader has clicked, tapped or pressed a key on the page, so call it from that gesture’s handler: a Begin button.
`voice`	`(url: URL, role: VoiceRole) => Promise<Voice>`	The `Speaker` method.
`close`	`() => Promise<void>`	Closes the context; nothing plays through this speaker afterwards.

Export	Signature	Does
`amplitude`	`(gain: number) => number`	A gain on the engine’s scale as an amplitude: clamped to 0–1, a non-finite gain read as `0`, then cubed.

How it makes each kind of sound:

A track streams through a media element into a gain node. A music bed decoded whole is about 23 MB a minute. The element is routed into Web Audio once it is playing, muted until then, and the file’s end is watched for as well as listened for.
A cue is decoded once, cached, and started from its buffer, so a sound effect is never late. It is fetched with mode: 'cors'.
Every gain goes through a GainNode, on the cubic scale, smoothed between the scheduler’s steps. It never uses HTMLMediaElement.volume, which iOS ignores.

A file on another origin needs that origin’s CORS headers, or Web Audio hears it as silence. MP3, AAC, FLAC and WAV play in every current browser; Ogg and Opus do not play in older Safari, and on iOS that is every browser.

Errors

Every error the package throws is a RippleError, and each is a class you tell apart with instanceof. Every message is English, for a log; branch on the fields.

Class	Thrown by	Fields	Met in use
`RippleError`	the base of the rest; also `SoundscapeDriver.apply` given a copied soundscape	`message`	no: a bug
`LoadError`	`Campaign.load`, and the engine’s own download	`url: string`, `status: number \| undefined` (`undefined` when the fetch itself failed)	yes: a network or server failure
`BundleError`	`Campaign.load`, `Campaign.fromFiles`, `campaign.soundscape`, `Session.create`	`failure: BundleFailure`	yes: a bundle that will not open, or one from a newer engine
`NeedsPython`	`Campaign.load`, `Campaign.fromFiles` with `python: false`	none	yes, by your choice
`ResumeError`	`Session.resume`	`failure: ResumeFailure`	yes: a save that no longer fits the campaign
`HostError`	any session verb	`failure: HostFailure`	two kinds only (below)
`ReentrantVerb`	a `Player` verb called while it delivers a batch	none	no: a bug
`EngineTrap`	any call into the engine after it panicked	`cause`	yes, and rare

`BundleFailure`

`kind`	Fields	Meaning
`format`	`message`, `location?`	The bundle is unreadable, and where.
`version`	`message`, `found`, `supported`, `oldest?`	The bundle’s format is one this engine cannot open: `found`, against the newest it `supported` and the `oldest`.

`ResumeFailure`

`kind`	Fields	Meaning
`bundle`	`failure: BundleFailure`	The save itself will not read.
`board-gone`	`board`	The board the save was on is not in this campaign any more.
`node-gone`	`board`, `node`	The node the save was on is not on that board any more.

`HostFailure`

A refused verb leaves the story where it was.

`kind`	Fields	Meaning	Met in use
`choice-spent`	`port`	A choice drawn as unavailable was taken.	yes: handle it
`unknown-locale`	`locale`	A language the campaign was not written in.	yes: handle it
`wrong-turn`	`asked`, `answered`	A verb that does not fit the turn. `asked` is `present`, `ask`, `wait`, `ended`, `failed` or `stopped`; `answered` is `choose`, `answer` or `elapsed`.	no: a bug
`no-such-choice`	`offered`, `chosen`	An index past the choices offered.	no: a bug
`stopped`	none	The session is stopped.	no: a bug
`nothing-asked`	none	The story is not waiting for anything.	no: a bug

`EngineTrap`

The engine panicked. The campaign’s instance is poisoned: every later call on that campaign, and on any session, player or driver over it, throws EngineTrap again. Other campaigns are unaffected. To recover, load the campaign again and resume your last save.

Threading and lifetime

Every verb is synchronous and runs on the calling thread. Nothing in Session returns a promise; only Campaign.load, Campaign.fromFiles, Speaker.voice, WebAudioSpeaker.unlock and WebAudioSpeaker.close do.
A passage costs microseconds. A Script node runs under its deadline (scriptLimits.deadlineMs), and the page does not paint while it runs.
One queue, in call order. Calls on a session are made one after another; a Player is that queue, and refuses a verb from inside its own delivery with ReentrantVerb.
The timers are the Player’s, for a hold, and the SoundscapeDriver’s, ticking every tickMs while anything sounds and stopping when it is idle or paused.

Object	Lets go with
`Player`	`dispose()`: no more holds, no more deliveries.
`SoundscapeDriver`	`dispose()`: cuts the sound and stops every voice.
`WebAudioSpeaker`	`close()`: closes its `AudioContext`.
`Session`	`stop()` ends it. It has no `dispose`.
`Campaign`	No `dispose`. Its compiled engine stays cached for the page.

A complete host

A page with a #stage element, a #begin button and a #locale select, rendering Markdown with marked and sanitising with DOMPurify. The callback names (chapterTwo, goldChanged, skipAhead) are the author’s, agreed with you.

import {
  Campaign,
  type Effect,
  EngineTrap,
  HostError,
  LoadError,
  NeedsPython,
  type Passage,
  Player,
  type Prompt,
  type RippleValue,
  ResumeError,
  resolveLink,
  Session,
  type SessionOptions,
  SoundscapeDriver,
} from '@ripplefx/player';
import { WebAudioSpeaker } from '@ripplefx/soundscape';
import DOMPurify from 'dompurify';
import { Marked } from 'marked';

const BASE = '/campaigns/the-city-of-elsenmar/';
const SAVE_KEY = 'elsenmar:save';
const stage = document.querySelector<HTMLElement>('#stage')!;
const begin = document.querySelector<HTMLButtonElement>('#begin')!;
const languages = document.querySelector<HTMLSelectElement>('#locale')!;

const OPTIONS: SessionOptions = { untranslated: 'fall-back' };

// --- Rendering ---------------------------------------------------------------

// The passage being drawn, for the image hook to resolve against.
let drawing: Passage | undefined;
const markdown = new Marked({
  walkTokens(token) {
    if (token.type === 'image' && drawing) token.href = resolveLink(drawing, token.href);
  },
});

let campaign: Campaign;
let player: Player | undefined;
let audio: SoundscapeDriver | undefined;
const speaker = new WebAudioSpeaker();

function el<K extends keyof HTMLElementTagNameMap>(tag: K, text?: string) {
  const node = document.createElement(tag);
  if (text !== undefined) node.textContent = text;
  return node;
}

function prose(passage: Passage): HTMLElement {
  drawing = passage;
  const html =
    campaign.manifest.textFormat === 'html'
      ? passage.text
      : (markdown.parse(passage.text, { async: false }) as string);
  drawing = undefined;
  const body = el('div');
  body.innerHTML = DOMPurify.sanitize(html);
  return body;
}

function choose(index?: number): void {
  try {
    player?.choose(index);
  } catch (error) {
    // A choice drawn as unavailable is refused if pressed; nothing moved.
    if (error instanceof HostError && error.failure.kind === 'choice-spent') return;
    fail(error);
  }
}

function showPassage(passage: Passage): void {
  stage.replaceChildren(el('h2', passage.title), prose(passage));
  if (passage.choices.length === 0) {
    const next = el('button', 'Continue');
    next.onclick = () => choose();
    stage.append(next);
  }
  passage.choices.forEach((choice, index) => {
    const button = el('button', choice.text || 'Continue');
    button.disabled = !choice.available; // run out: shown, not taken
    button.onclick = () => choose(index);
    stage.append(button);
  });
}

function showPrompt(prompt: Prompt): void {
  const form = el('form');
  for (const field of prompt.fields) {
    const input = el('input');
    input.name = field.name;
    if (field.type === 'bool') input.type = 'checkbox';
    else if (field.type === 'int' || field.type === 'float') input.type = 'number';
    if (field.default !== null && typeof field.default !== 'object') {
      input.value = String(field.default);
    }
    const label = el('label', field.name);
    label.append(input);
    form.append(label);
  }
  form.append(el('button', 'Continue'));
  form.onsubmit = (event) => {
    event.preventDefault();
    const values: Record<string, RippleValue> = {};
    for (const field of prompt.fields) {
      const input = form.elements.namedItem(field.name) as HTMLInputElement;
      values[field.name] =
        field.type === 'bool'
          ? input.checked
          : field.type === 'int'
            ? BigInt(Math.trunc(Number(input.value || 0))) // an Int is a bigint
            : field.type === 'float'
              ? Number(input.value || 0)
              : input.value;
    }
    try {
      player?.answer(values);
    } catch (error) {
      fail(error);
    }
  };
  stage.replaceChildren(el('h2', prompt.title), form);
}

function showHold(ms: number): void {
  // The Player waits the ms itself and calls elapsed(); this only draws it.
  const bar = el('progress');
  bar.max = ms;
  stage.append(bar);
  const started = performance.now();
  const step = () => {
    bar.value = performance.now() - started;
    if (bar.value < ms && bar.isConnected) requestAnimationFrame(step);
  };
  requestAnimationFrame(step);
}

// --- Saving ------------------------------------------------------------------

interface Stored {
  save: string;
  generator: { lo: number; hi: number };
}

function checkpoint(): void {
  const session = player?.session;
  const save = session?.checkpoint(); // undefined unless on a passage or a prompt
  if (!session || save === undefined) return;
  const stored: Stored = { save, generator: session.generator };
  try {
    localStorage.setItem(SAVE_KEY, JSON.stringify(stored));
  } catch {
    // Storage unavailable: the reader starts over next time.
  }
}

function stored(): Stored | undefined {
  try {
    const text = localStorage.getItem(SAVE_KEY);
    return text ? (JSON.parse(text) as Stored) : undefined;
  } catch {
    return undefined;
  }
}

function openSession(): Session {
  const seed = BigInt(Date.now());
  const last = stored();
  if (last) {
    try {
      const resumed = Session.resume(campaign, last.save, { ...OPTIONS, seed });
      resumed.generator = last.generator; // a save carries no dice
      return resumed;
    } catch (error) {
      if (!(error instanceof ResumeError)) throw error;
      // The campaign changed under the save: start afresh.
    }
  }
  const wanted = navigator.language.split('-')[0]!;
  const locale = campaign.manifest.project.locales.includes(wanted) ? wanted : undefined;
  return campaign.session({ ...OPTIONS, seed, ...(locale ? { locale } : {}) });
}

// --- Effects -----------------------------------------------------------------

function onEffect(effect: Effect): void {
  switch (effect.kind) {
    case 'show':
      showPassage(effect.passage);
      queueMicrotask(checkpoint);
      break;
    case 'ask':
      showPrompt(effect.prompt);
      queueMicrotask(checkpoint);
      break;
    case 'hold':
      showHold(effect.ms);
      break;
    case 'ended':
      stage.replaceChildren(el('h2', effect.ranOut ? 'The story ran out.' : (effect.title ?? 'The End')));
      try {
        localStorage.removeItem(SAVE_KEY);
      } catch {}
      break;
    case 'failed':
      stage.replaceChildren(el('h2', 'The story stopped.'), el('p', effect.message));
      break;
    case 'stopped':
    case 'jumped':
    case 'ambience':
    case 'audio': // applied to the driver by the Player
    case 'changed':
    case 'callback': // dispatched through onCallback below
    case 'trace':
      break;
  }
}

function fail(error: unknown): void {
  if (error instanceof EngineTrap) {
    // This campaign's instance is poisoned: load it again, resume the last save.
    void open();
    return;
  }
  console.error(error);
}

// --- Playing -----------------------------------------------------------------

function play(): void {
  player?.dispose();
  audio?.dispose();
  audio = new SoundscapeDriver(campaign, speaker);
  player = new Player(openSession(), { onEffect, onError: fail, audio });

  player.onCallback('chapterTwo', () => console.info('chapter two unlocked'));
  player.onCallback('goldChanged', (fired) => {
    const gold = fired.to; // a bigint when the variable is an Int
    console.info('gold', gold === undefined ? '' : campaign.asText(gold));
  });
  player.onCallback('skipAhead', () => {
    // A verb from a handler throws ReentrantVerb: schedule it instead.
    queueMicrotask(() => choose(0));
  });

  player.start();
}

async function open(): Promise<void> {
  player?.dispose();
  audio?.dispose();
  begin.hidden = true;
  stage.replaceChildren(el('p', 'Loading…'));
  try {
    campaign = await Campaign.load(BASE); // python: 'auto'
  } catch (error) {
    const why =
      error instanceof LoadError
        ? `${error.url} could not be fetched`
        : error instanceof NeedsPython
          ? 'this campaign needs Python'
          : (error as Error).message;
    stage.replaceChildren(el('h2', 'This campaign would not open.'), el('p', why));
    return;
  }
  stage.replaceChildren(el('h1', campaign.manifest.project.title));
  begin.hidden = false;
}

// No browser makes a sound before the reader's first gesture.
begin.onclick = async () => {
  begin.hidden = true;
  await speaker.unlock();
  play();
};

function setLocale(locale: string): void {
  try {
    player?.setLocale(locale);
  } catch (error) {
    if (error instanceof HostError && error.failure.kind === 'unknown-locale') return;
    fail(error);
  }
}

languages.onchange = () => setLocale(languages.value);

// A hidden tab is not listening: hold the sound, keep the story.
document.addEventListener('visibilitychange', () => {
  if (document.hidden) audio?.pause();
  else audio?.resume();
});

// Save on the way out.
window.addEventListener('pagehide', () => checkpoint());

void open();

Embedding the engine: why a host is shaped as sessions, effects and a speaker.
How the engine ships: versions, variants and the Runtime Licence the player carries.
Play a campaign in your program: the steps from an exported campaign to a running host.
Engine targets: every platform the engine is built for.
Host callbacks: what an author’s named callbacks are for, and how the two halves meet.

JavaScript and TypeScript binding

Packages and installing

Bundlers

Serving

Media paths

Choosing the variant

Platforms

The engine

Campaign

Opening

CampaignOptions

Members

CampaignManifest

Session

SessionStart

ResumeStart

SessionOptions

Verbs

Readers

Python results

Trace and dice

Effects

Records

Passage

Choice

Prompt and PromptField

Ambience

Soundscape and Track

Entity, Memory, CvarSnapshot, Changed

CallbackEvent

AudioCommand

RunEvent

resolveLink

Values

Player

PlayerHandlers

Members

Delivery

Holds

Named callbacks

Sound

SoundscapeDriver

The Speaker contract

@ripplefx/soundscape

Errors

BundleFailure

ResumeFailure

HostFailure

EngineTrap

Threading and lifetime

A complete host

Related

`CampaignOptions`

`CampaignManifest`

`SessionStart`

`ResumeStart`

`SessionOptions`

`Passage`

`Choice`

`Prompt` and `PromptField`

`Ambience`

`Soundscape` and `Track`

`Entity`, `Memory`, `CvarSnapshot`, `Changed`

`CallbackEvent`

`AudioCommand`

`RunEvent`

`resolveLink`

`PlayerHandlers`

`SoundscapeDriver`

The `Speaker` contract

`@ripplefx/soundscape`

`BundleFailure`

`ResumeFailure`

`HostFailure`

`EngineTrap`