The engine: the twin’s 25 exports
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
pub extern "C" fn sl_alloc(n: usize) -> *mut u8
Allocate n bytes the page can write a file into (freed by sl_free with the same length).
sl_free
pub unsafe extern "C" fn sl_free(p: *mut u8, n: usize)
Free a buffer from sl_alloc (the same n).
Safety: p from sl_alloc(n) with the same n.
sl_last_error_ptr
pub extern "C" fn sl_last_error_ptr() -> *const u8
The last error’s bytes (UTF-8) and length; the pointer is valid until the next call that can fail.
sl_last_error_len
pub extern "C" fn sl_last_error_len() -> usize
The last error’s length in bytes (see sl_last_error_ptr).
The world
sl_world_open
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
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.
sl_world_close
pub unsafe extern "C" fn sl_world_close(h: *mut Handle)
Close a world and free it.
Safety: h from sl_world_open, closed once.
sl_dims
pub unsafe extern "C" fn sl_dims(h: *const Handle, w: *mut u32, hh: *mut u32, d: *mut u32)
The world’s dims (x, y, z) through three out-pointers.
Safety: h from sl_world_open; the out-pointers writable.
The clock
sl_step
pub unsafe extern "C" fn sl_step(h: *mut Handle, n: u32)
Step the world n frames.
Safety: h from sl_world_open.
sl_stepRests at frame 240 with the digest 23e7eb22801d70df (pinned in api.json; tools/demo_check.mjs holds it).
The demo: its world, its ops and its steps
{
"world": "cube",
"ops": [],
"steps": 240
}
sl_frame
pub unsafe extern "C" fn sl_frame(h: *const Handle) -> u32
The frame the world is at.
Safety: h from sl_world_open.
The digest
sl_grid_hash_lo
pub unsafe extern "C" fn sl_grid_hash_lo(h: *const Handle) -> u32
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.
sl_grid_hash_hi
pub unsafe extern "C" fn sl_grid_hash_hi(h: *const Handle) -> u32
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.
sl_grid_hash64
pub unsafe extern "C" fn sl_grid_hash64(h: *const Handle, out: *mut u32)
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.
sl_words_hash_lo
pub unsafe extern "C" fn sl_words_hash_lo(p: *const u32, len: usize) -> u32
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.
sl_words_hash_hi
pub unsafe extern "C" fn sl_words_hash_hi(p: *const u32, len: usize) -> u32
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.
The grid
sl_grid_ptr
pub unsafe extern "C" fn sl_grid_ptr(h: *const Handle) -> *const u32
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.
sl_grid_len
pub unsafe extern "C" fn sl_grid_len(h: *const Handle) -> usize
The grid’s length in words (see sl_grid_ptr).
Safety: h from sl_world_open.
sl_census
pub unsafe extern "C" fn sl_census(h: *const Handle, mat: u32) -> u32
The census of one material (cells of that id).
Safety: h from sl_world_open.
sl_censusRests at frame 240 with the digest c23560ebfd317962 (pinned in api.json; tools/demo_check.mjs holds it).
The demo: its world, its ops and its steps
{
"world": "comet",
"ops": [],
"steps": 240
}
sl_grid_decode
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
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.
The ops
sl_op_box
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
★ 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.
sl_op_boxRests at frame 120 with the digest d7e3c2969ec5574d (pinned in api.json; tools/demo_check.mjs holds it).
The demo: its world, its ops and its steps
{
"world": "cube",
"ops": [
{
"op": "box",
"x0": 20,
"y0": 10,
"z0": 20,
"x1": 28,
"y1": 14,
"z1": 28,
"mat": 1,
"frame": 0
}
],
"steps": 120
}
sl_op_sphere
pub unsafe extern "C" fn sl_op_sphere(h: *mut Handle, x: i32, y: i32, z: i32, r: i32, mat: u32, temp: i32) -> u32
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.
sl_op_sphereRests at frame 120 with the digest 31ca6cb9c3f684a2 (pinned in api.json; tools/demo_check.mjs holds it).
The demo: its world, its ops and its steps
{
"world": "cube",
"ops": [
{
"op": "sphere",
"x": 32,
"y": 8,
"z": 32,
"r": 4,
"mat": 2,
"frame": 0
}
],
"steps": 120
}
sl_op_cell
pub unsafe extern "C" fn sl_op_cell(h: *mut Handle, x: i32, y: i32, z: i32, mat: u32, temp: i32, state: i32) -> u32
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.
sl_op_cellRests at frame 120 with the digest 688adbc78712a947 (pinned in api.json; tools/demo_check.mjs holds it).
The demo: its world, its ops and its steps
{
"world": "cube",
"ops": [
{
"op": "cells",
"xyz": [
8388640,
8389664,
8390688
],
"mat": [
3,
3,
3
],
"frame": 0
}
],
"steps": 120
}
sl_op_emitters
pub unsafe extern "C" fn sl_op_emitters(h: *mut Handle, words: *const u32, n: usize) -> i32
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.
sl_op_emittersRests at frame 240 with the digest c23560ebfd317962 (pinned in api.json; tools/demo_check.mjs holds it).
The demo: its world, its ops and its steps
{
"world": "comet",
"ops": [],
"steps": 240
}
The sidecars
sl_lua_json
pub unsafe extern "C" fn sl_lua_json(src: *const u8, len: usize) -> i32
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.
sl_lua_json_ptr
pub extern "C" fn sl_lua_json_ptr() -> *const u8
The parsed JSON’s bytes after sl_lua_json.
sl_lua_json_len
pub extern "C" fn sl_lua_json_len() -> usize
The parsed JSON’s length in bytes.
The work on this page: the commits of the last 30 days on its sources, the work open against them, its checks
starburn 87e5ac4techno, the day after: a tempo that is a RATIO of steps (any beats a minute), a lane's ACCENT and ARRANGEMENT, the tempo and the lanes in the snapshot and the record; ABI id 3aa530db (2026-11-12, the tower)starburn ec01144techno T1: the lanes, rhythms that strike the sound plane on the world's tempo (both sim lanes, a saved world, a tape op, the reference and the browser twin); ★ the ABI id moves f9de7f70 -> d9103976; ★ T0's stated tempi corrected (the sim clock is 60 a second, not 33) (2026-11-12, the tower)
starburn fc074fctape: one reader. The parser, its refusals and the applier are the core's tape module; the command and the browser module call it, and the two JavaScript walkers hold no checks of their own (dev loop S2; 2026-11-11, the tower)starburn acbe7d0wasm: the browser twin reads the tape's sound ops and holds sound_hash; a sound tape over a grid that is not whole lattice cells is refused (waves V2b; 2026-11-11, the tower)
starburn cfcdc0fstarlab-wasm web: every demo of api.json pins its digest at rest (2026-11-09)
starburn 35f5c51starlab-wasm: api.json, the web engine's protocol table; words on the eleven undocumented exports; the web names material 14 as the engine does (D1 of the reference lane, 2026-11-05)
starburn 8e86aa2starlab-wasm: the twin's build for the web, and the digest in one pass (2026-11-03, the tower)
starburn cc93e42the world tape, the twin's half (starlab.tape/1; 2026-10-29, the tower): `starlab-replay play <content> [--json] [--mint [--every K]]` plays a tape — a world as saved plus ops at frames (box, sphere, cell, cells, emitters) — and holds every checkpoint; the browser twin's `sl_op_*` and `scripts/tape-wasm.mjs` play the same tape in node to the same verdict
starburn 52161e9starlab.replay/1, the recording (M4 of the cartridge program): world::write_replay_dir (the cells every K steps as frames/<frame>.png with replay.lua naming each frame's digest) and write_lua_canon (canon_lua's text byte for byte, held to three conformance goldens); starlab-replay record; the wasm module reads Lua data as JSON, decodes a grid PNG and hashes words (sl_lua_json, sl_grid_decode, sl_words_hash); the player's mountReplay scrubs a recording and hashes every frame back, mountRecord routes a replay record to it; the derived crate re-splitstarburn 9507515world.rs: the starlab.world/1 folder read into the CPU frame (S8b / S10c of the cartridge program); starlab-replay, the command; starlab-wasm, the frame as a WebAssembly module, measured
The work record as of , from the fold on tower.
Nothing open against these sources.
- FAIL
lint/web-reference
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.