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

[[nav: reference | here=worker]]

<div class="doc">

# The worker: the twin on its own thread

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

`media/toys/lab-worker.js` instantiates the module in a module worker and steps the world on its own clock (20 steps a second; a post at most every 33 ms); the page sends the acts and gets the cells that changed, the frame, the digest and the census. One world a worker; a message carries no id.

## Messages in

### `open`

Instantiates the module and opens the world; every URL starts at once.

| field | |
|---|---|
| `wasm` | a URL or bytes of the module |
| `files` | {name: URL or bytes} of the world's files (meta.lua, grid.png, the sidecars the meta names); empty = the carved basin |
| `lay` | a list of ops laid at frame 0, or the URL of a JSON holding them (an array, or {ops}); optional |

*Reply:* state with opened: true and carved (the basin's carve, when the files were empty)

### `run`

Starts or stops the worker's own clock.

| field | |
|---|---|
| `on` | boolean |

*Reply:* state posts while it runs (20 steps a second, a post at most every 33 ms)

### `write`

Writes the word in sand on the sill as 5x7 glyph cells: one text op on the tape.

| field | |
|---|---|
| `text` | up to 7 characters |

*Reply:* op (the text op with its frame and the cells written), then state

### `step`

Steps the world n frames now, whatever the clock.

| field | |
|---|---|
| `n` | steps, at least 1 |

*Reply:* state

### `op`

Applies an op at the frame the worker is on, which it echoes for the tape.

| field | |
|---|---|
| `op` | one op of the table below; the worker stamps its frame |

*Reply:* op (the op with its frame and the cells written), then state

### `reset`

Closes the world and opens it again from its files and lay.

*Reply:* state with reset: true and the whole grid

### `load`

A tape laid on a fresh world (its ops at their frames, stepped to its last frame), which stays live.

| field | |
|---|---|
| `tape` | {ops: [{..., frame}], last} |
| `run` | boolean: start the clock after |

*Reply:* state with loaded: true and ops (the count), the whole grid

### `replay`

A second world on the same module, the same ops at the same frames, stepped to the live world's frame: the digest compared. An op the reader does not know refuses the tape by name.

| field | |
|---|---|
| `tape` | {ops: [{..., frame}]} |
| `resume` | boolean: start the clock again after |

*Reply:* replay {ok, got, want, frame} or {ok: false, refused, want, frame}

## Messages out

### `state`

The world as the page draws it. The typed arrays are transferred, not copied.

| field | |
|---|---|
| `frame` | u32 |
| `digest` | 16 hex digits (sl_grid_hash64) |
| `dims` | [W, H, D] |
| `odims` | the block field's dims (4-cell blocks) |
| `grid` | Uint32Array of every word (at open, reset, load, or when more than a quarter moved) |
| `idx` | Uint32Array: the indices of the cells whose material or heat changed (with val) |
| `val` | Uint32Array: their words |
| `occ` | Uint8Array: the block distance (0 = a cell in the block is not air; else the Chebyshev distance in blocks to the nearest such block, capped at 15), when it changed |
| `census` | {material: cells} over the census materials |
| `stepMs` | the twin's ms a step, a running mean |
| `postMs` | the post's own ms, a running mean |
| `opened` | true once, at open |
| `carved` | the basin's carve, with opened |
| `reset` | true once, after reset |
| `loaded` | true once, after load |
| `ops` | the count, with loaded |

### `op` (posted)

An op applied (from op or write).

| field | |
|---|---|
| `op` | the op with its frame |
| `cells` | the cells written |

### `replay` (posted)

The replay's verdict.

| field | |
|---|---|
| `ok` | boolean |
| `got` | the replay's digest |
| `want` | the live digest |
| `frame` | the frame compared at |
| `refused` | why, when an op was unknown |

### `error`

A thrown error in any handler, the worker alive.

| field | |
|---|---|
| `message` | string |

[[view: load-tape | caption=a tape of two ops (lava at frame 30, ice at 90) laid on a fresh cube]]

<p class="pinned">Rests at frame 290 with the digest <code>a7e246336ea2acb4</code> (pinned in <code>api.json</code>; <code>tools/demo_check.mjs</code> holds it).</p>

<details class="ops"><summary>The demo: its world, its ops and its steps</summary>

```json
{
 "world": "cube",
 "ops": [
  {
   "op": "sphere",
   "x": 32,
   "y": 6,
   "z": 32,
   "r": 3,
   "mat": 3,
   "frame": 30
  },
  {
   "op": "sphere",
   "x": 40,
   "y": 6,
   "z": 24,
   "r": 2,
   "mat": 5,
   "frame": 90
  }
 ],
 "steps": 200
}
```

</details>

## The ops

The tape's ops (`docs/formats/world-tape.md`: the format is the grammar; a reader refuses an op it does not know by name, never skips one) and the lay's own (a world's dressing at frame 0, never on a tape).

| op | fields | where | the engine's call |
|---|---|---|---|
| `box` | `x0 y0 z0 x1 y1 z1 mat [temp] [state]` | the tape | `spawn_box_state` (the console's `spawn_box`, `edit_box`) |
| `sphere` | `x y z r mat [temp]` | the tape | `spawn_sphere` |
| `cell` | `x y z mat [temp] [state]` | the tape | `spawn_cell_state` |
| `cells` | `xyz = {…}`, `mat = {…}`, `[temp = {…}]`, `[state = {…}]`: parallel integer arrays of one length; `xyz` packed `x | the tape | y<<10 | z<<20` (the engine's packing); a cell named twice keeps the last word | `edit_cells` (per cell, in order) |
| `emitters` | `list = { {13 integers}, … }`: each record the FFI's `EMITTER_WORDS` (x, y, z, r·scatter, h, mat, temp, state, rate, period, burst, phase, heat); an empty list clears | the tape | `set_emitters` (replaces the set) |
| `actor_add` | `id x z energy eat_commit held_sun contract`, at `first_frame` only, ONE PER ACTOR (`id` 1 the creature, 2.. the herd's mates in index order) | the tape (not on the web: the creature strand: read by starlab-char's reader, not by the browser twin) | the actor as it stood: its position and energy (floats, exact as canonical numbers), its eat commitment, the day phase it last held, and the contract version its senses and drives follow (`CONTRACT_VERSION`, `starlab-char`'s `contract.rs`; a reader of another contract refuses by name) |
| `actor_intent` | `id action`, at a decision frame, one per LIVING actor | the tape (not on the web: the creature strand, as actor_add) | the decoded action (0 stay · 1 +x · 2 −x · 3 +z · 4 −z) the actor holds for the next `DECISION_PERIOD` (8) frames; the creature's (`id` 1) is required at every decision frame, a mate's missing reads 0 (rest) |
| `text` | `text x y z mat [temp] [state]` | the lay | 5x7 glyph cells along z, one glyph a column of cells; the lay's and the worker's write, never a tape's own (`lab-world.js text()`) |
| `frost` | `[on=4] [depth=1] [scale=6] [cover=0.5] [seed] mat [temp]` | the lay | ice (mat) laid depth cells deep on the sunward tops of on (stone) where a value noise of the column passes cover; read first, written after (`lab-world.js frost()`) |
| `runs` | `r = [x0, x1, y, z, ...] mat [temp]` | the lay | x-runs of one material, both ends in (`lab-world.js runs()`) |

Reserved by the format, not yet readable anywhere: `actor_remove`, `words`, `write_box`, `columns`, `edit_columns`.

<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=starlens/site/media/toys/lab-worker.js,starlens/site/media/toys/lab-world.js,starburn/crates/starlab-wasm/web/api.json | kinds=commit | days=30]]

[[work: open | src=starlens/site/media/toys/lab-worker.js,starlens/site/media/toys/lab-world.js,starburn/crates/starlab-wasm/web/api.json]]

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

</details>

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

*Generated by `tools/reference_pages.py` from `media/toys/lab-worker.js`, `media/toys/lab-world.js`, `docs/formats/world-tape.md`, `web/api.json`; the twin `bfaad079a7ce` (434093 bytes). The words are a draft.*

</div>
