The engine: the twin’s 25 exports

this page as plaintext

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).

starburn/crates/starlab-wasm/src/lib.rs:29

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.

starburn/crates/starlab-wasm/src/lib.rs:40

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.

starburn/crates/starlab-wasm/src/lib.rs:48

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).

starburn/crates/starlab-wasm/src/lib.rs:53

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.

starburn/crates/starlab-wasm/src/lib.rs:64

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.

starburn/crates/starlab-wasm/src/lib.rs:116

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.

starburn/crates/starlab-wasm/src/lib.rs:174

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.

starburn/crates/starlab-wasm/src/lib.rs:126

the cube’s spring and sea, stepped by the worker’s clockshows sl_step

Rests 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.

starburn/crates/starlab-wasm/src/lib.rs:137

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.

starburn/crates/starlab-wasm/src/lib.rs:146

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.

starburn/crates/starlab-wasm/src/lib.rs:153

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.

starburn/crates/starlab-wasm/src/lib.rs:163

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.

starburn/crates/starlab-wasm/src/lib.rs:437

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.

starburn/crates/starlab-wasm/src/lib.rs:444

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.

starburn/crates/starlab-wasm/src/lib.rs:189

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.

starburn/crates/starlab-wasm/src/lib.rs:196

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.

starburn/crates/starlab-wasm/src/lib.rs:205

the comet: the census of ice, steam and stone as its geysers runshows sl_census

Rests 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.

starburn/crates/starlab-wasm/src/lib.rs:417

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.

starburn/crates/starlab-wasm/src/lib.rs:221

a box of sand (mat 1) over the sea at frame 0shows sl_op_box

Rests 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.

starburn/crates/starlab-wasm/src/lib.rs:228

a sphere of water (mat 2, r 4) dropped over the island at frame 0shows sl_op_sphere

Rests 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.

starburn/crates/starlab-wasm/src/lib.rs:235

three cells of lava (the tape’s cells op: xyz packed xshows sl_op_cell

Rests 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.

starburn/crates/starlab-wasm/src/lib.rs:245

the comet’s three steam geysers and its drains are its lay’s emitters opshows sl_op_emitters

Rests 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.

starburn/crates/starlab-wasm/src/lib.rs:378

sl_lua_json_ptr

pub extern "C" fn sl_lua_json_ptr() -> *const u8

The parsed JSON’s bytes after sl_lua_json.

starburn/crates/starlab-wasm/src/lib.rs:401

sl_lua_json_len

pub extern "C" fn sl_lua_json_len() -> usize

The parsed JSON’s length in bytes.

starburn/crates/starlab-wasm/src/lib.rs:406

The work on this page: the commits of the last 30 days on its sources, the work open against them, its checks

  • starburn 87e5ac4 techno, 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 ec01144 techno 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 fc074fc tape: 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 acbe7d0 wasm: 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 cfcdc0f starlab-wasm web: every demo of api.json pins its digest at rest (2026-11-09)

  • starburn 35f5c51 starlab-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 8e86aa2 starlab-wasm: the twin's build for the web, and the digest in one pass (2026-11-03, the tower)

  • starburn cc93e42 the 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 52161e9 starlab.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-split
  • starburn 9507515 world.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.

  • FAILlint/web-reference 12 Nov on tower

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.