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

[[nav: reference | here=player]]

<div class="doc">

# The player: mounting the twin in a page

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

`starlab-player.js` mounts the reference simulation in a page: a player over a world's files and its record, the `figure.world[data-world]` blocks, a recording scrubbed, a tape played and held to its checkpoints, a sealed record from `/play/<sha>`. One module instance a URL a page.

## Exports

### `MATS`

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

The materials by id, each `[name, colour]`: the engine's `materials.rs` names them (the reference's view page holds the two tables to each other); a slot absent here is free in the engine too.

<p class="meta">starburn/crates/starlab-wasm/web/starlab-player.js:16</p>

### `PAL`

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

The palette the view draws with: `[r, g, b]` per material id from `MATS`' colours; magenta marks an id with no material (a bug made visible), and air (0) is null, drawn as nothing.

<p class="meta">starburn/crates/starlab-wasm/web/starlab-player.js:25</p>

### `ALPHA`

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

The opacity per material id, 1 unless set below: water, ice, steam, smoke, glass and the like let the cells behind them show.

<p class="meta">starburn/crates/starlab-wasm/web/starlab-player.js:28</p>

### `FILES`

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

A world's files, in the order `sl_world_open` takes them: the meta, the grid, and the sidecars a world may lack (air, flux, biomes, geo), each given as bytes or left empty.

<p class="meta">starburn/crates/starlab-wasm/web/starlab-player.js:32</p>

### `LABEL`

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

The caption under a live player: what it is and what it is not (renderer 4 is the desktop's).

<p class="meta">starburn/crates/starlab-wasm/web/starlab-player.js:34</p>

### `REPLAY_LABEL`

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

The caption under a replay of a recorded cart.

<p class="meta">starburn/crates/starlab-wasm/web/starlab-player.js:36</p>

### `loadModule`

<pre class="sig">loadModule(url)</pre>

The wasm module, instantiated once per URL and shared by every player on the page.

<p class="meta">starburn/crates/starlab-wasm/web/starlab-player.js:40</p>

### `mountPlayer`

<pre class="sig">mountPlayer(root, opts)</pre>

Mount a player. `opts.files`: name → URL (fetched) or Uint8Array; `opts.record`: the cart's record.json (its payload.replay is the witness); `opts.wasm`: the module's URL; `opts.name`: shown; `opts.autoplay`; `opts.live` (the record's budget verdict, shown as a word); `opts.stepsPerFrame`.

| option | type | |
|---|---|---|
| `wasm` | URL | the module (one instance a URL a page) |
| `files` | {name: URL | Uint8Array} | the world's files |
| `record` | record.json | the cart's record; its payload.replay is the witness |
| `name` | string | shown |
| `autoplay` | boolean |  |
| `live` | string | the record's budget verdict, shown as a word |
| `stepsPerFrame` | int |  |
| `width` | px | the canvas (960 by default) |
| `height` | px | the canvas (540 by default) |
| `onDraw` | function | called after each draw |

<p class="meta">starburn/crates/starlab-wasm/web/starlab-player.js:65</p>

### `mountBlocks`

<pre class="sig">mountBlocks(selector = "figure.world[data-world]")</pre>

Mount every `<figure class="world" data-world="…">` on the page: the block's markup, the player on demand (a click on its control) or at once when the record says live. `data-world` is JSON: {name, wasm, files, record, live}.

<p class="meta">starburn/crates/starlab-wasm/web/starlab-player.js:160</p>

### `mountReplay`

<pre class="sig">mountReplay(root, opts)</pre>

A `starlab.replay/1` cart (M4 of the cartridge program): the recording scrubbed, never stepped — for a world too large to run in a page. `opts.files`: name → URL or bytes (`replay.lua` and the frames it names); `opts.wasm`. The module reads replay.lua as JSON (sl_lua_json); each frame is fetched when first shown, decoded by the module (sl_grid_decode) and hashed back (sl_words_hash): the frame on screen says whether it hashes to the digest the recording names. Returns { show(i), play, pause, index, frame, frames, digestOk, dims, close }.

<p class="meta">starburn/crates/starlab-wasm/web/starlab-player.js:198</p>

### `mountRecord`

<pre class="sig">mountRecord(fig, opts)</pre>

/play/<record> (M4 of the cartridge program): the player alone on one sealed cart, the one URL an essay, a StarBoard card or an embed carries. The record's sha comes from the path (`/play/<sha>`; the host rewrites it to the page), from `?r=<sha>`, or from the hash; the page fetches `<opts.carts><sha>/record.json`, names the content files from the record's subject and mounts the player on them (the witness is the record's). `opts.words` are the page's own lines: `missing` (no record named), `reading`, `kind` (a cart this player does not open). Returns the player.

<p class="meta">starburn/crates/starlab-wasm/web/starlab-player.js:294</p>

### `TAPE_KIND`

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

The tape format this player replays (docs/formats/world-tape.md): a cart whose `kind` is another is refused by name.

<p class="meta">starburn/crates/starlab-wasm/web/starlab-player.js:371</p>

### `TAPE_LABEL`

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

The caption under a tape's replay.

<p class="meta">starburn/crates/starlab-wasm/web/starlab-player.js:373</p>

### `readTape`

<pre class="sig">readTape(ex, tapeBytes)</pre>

A tape.lua read by the module and checked as the reference checks it. -> {name, first, last, ops, cps, claimed, salt, mask, reasons}: `reasons` is empty for a well-formed tape; `unread` is set when the file is no Lua data.

<p class="meta">starburn/crates/starlab-wasm/web/starlab-player.js:380</p>

### `openTapeWorld`

<pre class="sig">openTapeWorld(ex, files, v)</pre>

The tape's world opened on the module with the tape's options: -> {h} or {refused: [...]} in the reference's words. `files`: name → bytes (meta.lua and grid.png required; the sidecars the save captured when present).

<p class="meta">starburn/crates/starlab-wasm/web/starlab-player.js:425</p>

### `applyTapeOp`

<pre class="sig">applyTapeOp(ex, h, op)</pre>

One op through the module's C ABI (the twin's own spawn path). -> null, or the reason it was refused.

<p class="meta">starburn/crates/starlab-wasm/web/starlab-player.js:444</p>

### `mountTape`

<pre class="sig">mountTape(root, opts)</pre>

Mount a tape: the world drawn in 3-D while the page plays the tape on the reference sim, a row per checkpoint (the tape's digest beside the one the module printed), the verdict in the reference's words, and the record's own witness beside it when the cart has one. `opts.files`: name → URL (fetched; a missing one is absent) or Uint8Array (tape.lua, meta.lua, grid.png and the sidecars the save captured); `opts.wasm`; `opts.record`: the cart's record.json; `opts.autoplay` (default true); `opts.stepsPerFrame` (default 1: the run at its own pace; "to the end" plays the rest at once). Returns {done: Promise<verdict>, play, pause, finish, frame, fingerprint, verdict, close}, or the refusal itself when the tape cannot be played.

<p class="meta">starburn/crates/starlab-wasm/web/starlab-player.js:519</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=starburn/crates/starlab-wasm/web/starlab-player.js,starburn/crates/starlab-wasm/web/api.json | kinds=commit | days=30]]

[[work: open | src=starburn/crates/starlab-wasm/web/starlab-player.js,starburn/crates/starlab-wasm/web/api.json]]

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

</details>

<nav class="pager"><a href="../view/">← view</a><a href="../">The reference</a><a href="../board/">board →</a></nav>

*Generated by `tools/reference_pages.py` from `starburn/crates/starlab-wasm/web/starlab-player.js`, `web/api.json`; the twin `bfaad079a7ce` (434093 bytes). The words are a draft.*

</div>
