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

[[nav: reference | here=engine]]

<div class="doc">

# The engine: the twin's 25 exports

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

The reference simulation as a WebAssembly module with a plain C interface (no bindgen; it also exports `memory`). Every error is read through `sl_last_error_ptr` / `sl_last_error_len`. The grid's words: x varies fastest, then y, then z (`x + W*(y + H*z)`; y grows downward); a word's R byte holds the material's low nibble, the flags in its top bits (bit 6 `MAT_HI` for ids 16-31, 0x80 charged), G the activity, B the temperature, A the state. A demo beside an export is the twin itself, running in this page: one worker and one canvas for them all, the canvas in whichever is in sight.

## Memory

### `sl_alloc`

<pre class="sig">pub extern "C" fn sl_alloc(n: usize) -> *mut u8</pre>

Allocate `n` bytes the page can write a file into (freed by `sl_free` with the same length).

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:29</p>

### `sl_free`

<pre class="sig">pub unsafe extern "C" fn sl_free(p: *mut u8, n: usize)</pre>

Free a buffer from `sl_alloc` (the same `n`).

*Safety:* `p` from `sl_alloc(n)` with the same `n`.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:40</p>

### `sl_last_error_ptr`

<pre class="sig">pub extern "C" fn sl_last_error_ptr() -> *const u8</pre>

The last error's bytes (UTF-8) and length; the pointer is valid until the next call that can fail.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:48</p>

### `sl_last_error_len`

<pre class="sig">pub extern "C" fn sl_last_error_len() -> usize</pre>

The last error's length in bytes (see `sl_last_error_ptr`).

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:53</p>

## The world

### `sl_world_open`

<pre class="sig">pub unsafe extern "C" fn sl_world_open( meta: *const u8, meta_len: usize, png: *const u8, png_len: usize, air: *const u8, air_len: usize, flux: *const u8, flux_len: usize, biomes: *const u8, biomes_len: usize, geo: *const u8, geo_len: usize, sim_salt: u32, assume_mask: i64, ) -> *mut Handle</pre>

Open a world from its files in the module's memory: `meta.lua`, `grid.png`, and the sidecars the meta names (`air.bin`, `flux.bin`, `biomes.png`, `geo.png`; pass a null pointer and 0 for one that is absent). `sim_salt` and `assume_mask` (negative = none) are what the save does not carry. Returns a handle, or null (see the error).

*Safety:* Every (pointer, length) pair names readable bytes in the module's memory.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:64</p>

### `sl_world_close`

<pre class="sig">pub unsafe extern "C" fn sl_world_close(h: *mut Handle)</pre>

Close a world and free it.

*Safety:* `h` from `sl_world_open`, closed once.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:116</p>

### `sl_dims`

<pre class="sig">pub unsafe extern "C" fn sl_dims(h: *const Handle, w: *mut u32, hh: *mut u32, d: *mut u32)</pre>

The world's dims (x, y, z) through three out-pointers.

*Safety:* `h` from `sl_world_open`; the out-pointers writable.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:174</p>

## The clock

### `sl_step`

<pre class="sig">pub unsafe extern "C" fn sl_step(h: *mut Handle, n: u32)</pre>

Step the world `n` frames.

*Safety:* `h` from `sl_world_open`.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:126</p>

[[view: step | caption=the cube's spring and sea, stepped by the worker's clock]]

<p class="pinned">Rests at frame 240 with the digest <code>23e7eb22801d70df</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": [],
 "steps": 240
}
```

</details>

### `sl_frame`

<pre class="sig">pub unsafe extern "C" fn sl_frame(h: *const Handle) -> u32</pre>

The frame the world is at.

*Safety:* `h` from `sl_world_open`.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:137</p>

## The digest

### `sl_grid_hash_lo`

<pre class="sig">pub unsafe extern "C" fn sl_grid_hash_lo(h: *const Handle) -> u32</pre>

THE FINGERPRINT, as two halves (wasm32 has no u64 in its JS ABI): the grid digest's low and high 32 bits.

*Safety:* `h` from `sl_world_open`.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:146</p>

### `sl_grid_hash_hi`

<pre class="sig">pub unsafe extern "C" fn sl_grid_hash_hi(h: *const Handle) -> u32</pre>

The grid digest's high 32 bits (`sl_grid_hash_lo` the low; `sl_grid_hash64` both at once).

*Safety:* `h` from `sl_world_open`.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:153</p>

### `sl_grid_hash64`

<pre class="sig">pub unsafe extern "C" fn sl_grid_hash64(h: *const Handle, out: *mut u32)</pre>

THE FINGERPRINT in one pass (the toy renderer, 2026-11-03): both halves through an out-pointer to two u32s (low first), so a page that posts the digest with every frame hashes the grid once, not once per half.

*Safety:* `h` from `sl_world_open`; `out` names two writable u32s in the module's memory.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:163</p>

### `sl_words_hash_lo`

<pre class="sig">pub unsafe extern "C" fn sl_words_hash_lo(p: *const u32, len: usize) -> u32</pre>

The fingerprint of `len` words at `p` — the digest `sl_grid_hash_lo` / `_hi` print for an open world, over any words: a decoded frame hashes back to the digest its replay recorded.

*Safety:* `p` names `len` readable words in the module's memory.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:437</p>

### `sl_words_hash_hi`

<pre class="sig">pub unsafe extern "C" fn sl_words_hash_hi(p: *const u32, len: usize) -> u32</pre>

The high 32 bits of the digest over the same words as `sl_words_hash_lo`.

*Safety:* `p` names `len` readable words in the module's memory.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:444</p>

## The grid

### `sl_grid_ptr`

<pre class="sig">pub unsafe extern "C" fn sl_grid_ptr(h: *const Handle) -> *const u32</pre>

The grid's words in place (`sl_grid_len` of them, canvas order: x fastest, then y, then z) for a flat draw — the material in the low nibble (bit 6 the high page), the temperature in byte 2. Valid until the next step.

*Safety:* `h` from `sl_world_open`.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:189</p>

### `sl_grid_len`

<pre class="sig">pub unsafe extern "C" fn sl_grid_len(h: *const Handle) -> usize</pre>

The grid's length in words (see `sl_grid_ptr`).

*Safety:* `h` from `sl_world_open`.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:196</p>

### `sl_census`

<pre class="sig">pub unsafe extern "C" fn sl_census(h: *const Handle, mat: u32) -> u32</pre>

The census of one material (cells of that id).

*Safety:* `h` from `sl_world_open`.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:205</p>

[[view: census | caption=the comet: the census of ice, steam and stone as its geysers run]]

<p class="pinned">Rests at frame 240 with the digest <code>c23560ebfd317962</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": "comet",
 "ops": [],
 "steps": 240
}
```

</details>

### `sl_grid_decode`

<pre class="sig">pub unsafe extern "C" fn sl_grid_decode(png: *const u8, len: usize, w: u32, h: u32, d: u32, format: u32, out: *mut u32) -> i32</pre>

Decode a grid PNG (a world's `grid.png`, a replay's frame) for `w × h × d` into `out` — `w·h·d` words the page allocated with `sl_alloc(w·h·d·4)`; `format` ≤ 1 strips the R byte's 0x40 as the world reader does. Returns 0, or -1 with the error set.

*Safety:* `png` names `len` readable bytes and `out` `w·h·d` writable words in the module's memory.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:417</p>

## The ops

### `sl_op_box`

<pre class="sig">pub unsafe extern "C" fn sl_op_box(h: *mut Handle, x0: i32, y0: i32, z0: i32, x1: i32, y1: i32, z1: i32, mat: u32, temp: i32, state: i32) -> u32</pre>

★ THE TAPE'S OPS (`starlab.tape/1`, docs/formats/world-tape.md, 2026-10-29): the world-mutating acts a tape carries, applied through the twin's own spawn path (the word the engine writes). `temp` and `state` negative = the material's default. Corners inclusive and in order; a box or sphere is clamped to the grid. Returns the cells written.

*Safety:* `h` from `sl_world_open`.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:221</p>

[[view: op-box | caption=a box of sand (mat 1) over the sea at frame 0]]

<p class="pinned">Rests at frame 120 with the digest <code>d7e3c2969ec5574d</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": "box",
   "x0": 20,
   "y0": 10,
   "z0": 20,
   "x1": 28,
   "y1": 14,
   "z1": 28,
   "mat": 1,
   "frame": 0
  }
 ],
 "steps": 120
}
```

</details>

### `sl_op_sphere`

<pre class="sig">pub unsafe extern "C" fn sl_op_sphere(h: *mut Handle, x: i32, y: i32, z: i32, r: i32, mat: u32, temp: i32) -> u32</pre>

Fill a sphere (centre x, y, z; radius r) with `mat` at `temp` (negative = the material's default), clamped to the grid; returns the cells written.

*Safety:* `h` from `sl_world_open`.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:228</p>

[[view: op-sphere | caption=a sphere of water (mat 2, r 4) dropped over the island at frame 0]]

<p class="pinned">Rests at frame 120 with the digest <code>31ca6cb9c3f684a2</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": 8,
   "z": 32,
   "r": 4,
   "mat": 2,
   "frame": 0
  }
 ],
 "steps": 120
}
```

</details>

### `sl_op_cell`

<pre class="sig">pub unsafe extern "C" fn sl_op_cell(h: *mut Handle, x: i32, y: i32, z: i32, mat: u32, temp: i32, state: i32) -> u32</pre>

Write one cell: `mat`, `temp` and `state` (negative = the material's default); a cell outside the grid writes nothing; returns the cells written.

*Safety:* `h` from `sl_world_open`.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:235</p>

[[view: op-cell | caption=three cells of lava (the tape's cells op: xyz packed x | y<<10 | z<<20) at frame 0]]

<p class="pinned">Rests at frame 120 with the digest <code>688adbc78712a947</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": "cells",
   "xyz": [
    8388640,
    8389664,
    8390688
   ],
   "mat": [
    3,
    3,
    3
   ],
   "frame": 0
  }
 ],
 "steps": 120
}
```

</details>

### `sl_op_emitters`

<pre class="sig">pub unsafe extern "C" fn sl_op_emitters(h: *mut Handle, words: *const u32, n: usize) -> i32</pre>

The emitters replaced by `n` records of 13 words each (`EMITTER_WORDS`: x, y, z, r | scatter << 16, h, mat, temp, state, rate, period, burst, phase, heat; temp and state i32 bit patterns). n = 0 clears. Returns 0, or -1 when the twin refused the set (more than it holds).

*Safety:* `h` from `sl_world_open`; `words` names `n * 13` readable words.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:245</p>

[[view: emitters | caption=the comet's three steam geysers and its drains are its lay's emitters op]]

<p class="pinned">Rests at frame 240 with the digest <code>c23560ebfd317962</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": "comet",
 "ops": [],
 "steps": 240
}
```

</details>

## The sidecars

### `sl_lua_json`

<pre class="sig">pub unsafe extern "C" fn sl_lua_json(src: *const u8, len: usize) -> i32</pre>

Parse a Lua data file in the module's memory (`meta.lua`, `replay.lua`: the console's sidecar grammar, no code) and keep it as JSON for `sl_lua_json_ptr` / `sl_lua_json_len`. An array (keys 1..=n) becomes a JSON array, any other table an object; an empty table is `{}`. Returns 0, or -1 with the error set.

*Safety:* `src` names `len` readable bytes in the module's memory.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:378</p>

### `sl_lua_json_ptr`

<pre class="sig">pub extern "C" fn sl_lua_json_ptr() -> *const u8</pre>

The parsed JSON's bytes after `sl_lua_json`.

<p class="meta">starburn/crates/starlab-wasm/src/lib.rs:401</p>

### `sl_lua_json_len`

<pre class="sig">pub extern "C" fn sl_lua_json_len() -> usize</pre>

The parsed JSON's length in bytes.

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

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

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

</details>

<nav class="pager"><a href="../guides/start/">← guides/start</a><a href="../">The reference</a><a href="../worker/">worker →</a></nav>

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

</div>
