The world tape (starlab.tape/1)
The format, 2026-10-29 (the replayable-worlds slice; the brand line’s engineering half, PRACTICES.md ruling 44).
Commons: the reference implementation is the open twin’s command starlab-replay play (starburn/crates/starlab-replay,
Apache-2.0 with the reference crate) and the cart reader in love-shared/cart/kinds.lua. This text is CC BY 4.0, as
every format spec in the house.
A world cart is a still; a tape is a run. A starlab.world/1 cart carries the cells as they were saved, and its
record’s replay witness says what the reference sim prints after N steps from there. Nothing in it says what a
person DID: where they poured the water, when they struck the vent, which cells they painted. A tape carries that:
the world as it stood when the recording began, every world-mutating act at the frame it landed, and the digest the
recorder measured at chosen frames. Anyone with the open twin replays the acts from the saved world and holds every
digest to the tape’s; the browser twin does the same in a page. A verified run is a tape cart whose sealed record
carries an agreeing replay witness; “Verified with StarLab” follows that record, never the maker’s word
(licenses/TRADEMARKS.md).
The tape is the smallest form of the sentence the platform is built on, replay is the API: a core is a pure
function of a seed and a history (docs/working-engine-strategy-2026-10.md). The world record’s tape of actors
(docs/formats/world-record.md, the Tape row; the world-record program’s L18) is the same idea one stratum deeper:
the record at T0 plus the bodies’ intents plus D(T) per decision. This format is the cells’ tape, the one every
copy of the twin can play today; the actor intents join it as ops when the record carries bodies (actor ops are
reserved below).
The container
A starlab.tape/1 cart’s content/ is a starlab.world/1 content exactly as the console’s world save wrote it
at the recording’s first frame (grid.png, meta.lua, and the sidecars the meta says were captured), plus one
file:
content/
grid.png the cells at the first frame
meta.lua the world's sidecar (format, name, dims, frame, sim, …)
tape.lua the tape (below), canonical Lua data
The world part is read by the world kind’s reader unchanged; a world the reference refuses by name (a captured pool, a heightfield, surface layers) makes a tape the reference refuses by the same names, and the record says so.
tape.lua
-- starlab.tape/1 · basin_splash
return {
format = 1,
name = "basin_splash", -- the world's name (meta.lua's)
first_frame = 0, -- the frame the world stands at (meta.lua's frame; 0 when it has none)
steps = 120, -- the tape's length: the last frame is first_frame + steps
options = { sim_salt = 0, model_mask = 40, xfer_every = 4, air_every = 4 },
ops = {
{ at = 10, op = "box", x0 = 4, y0 = 2, z0 = 4, x1 = 11, y1 = 5, z1 = 11, mat = 2 },
{ at = 10, op = "sphere", x = 16, y = 8, z = 16, r = 3, mat = 1, temp = -1 },
{ at = 30, op = "cell", x = 7, y = 3, z = 7, mat = 3, temp = 200, state = -1 },
{ at = 40, op = "cells", xyz = { 2099205, 2099206 }, mat = { 1, 1 }, temp = { -1, -1 }, state = { -1, -1 } },
{ at = 50, op = "emitters", list = { { 16, 20, 16, 2, 6, 3, -1, -1, 32768, 60, 10, 0, 0 } } },
},
checkpoints = {
{ frame = 0, grid_hash = "2a6037e4e5e8297e" },
{ frame = 60, grid_hash = "aa823f64bad7d352" },
{ frame = 120, grid_hash = "c34b25a902770413" },
},
recorder = { app = "starlab-console", engine_sha256 = "…", backend = "vulkan" },
}
formatis 1.nameis the world’s name and must equalmeta.lua’s.first_framemust equal the frame the world stands at when opened (meta.lua’sframe, 0 when absent).stepsis a non-negative integer.optionsis what the save does not carry and the replay must repeat, as integers:sim_salt,model_mask(the engine’s model bits),xfer_every,air_every. An absent key is the reference’s default. For a tape these live in the content, not incart.toml’s[replay]: they change what the run IS, and the content digest must cover them. (cart.toml’s[replay]may mirror them for a world cart’s tooling; the tape’s are authoritative.)opsis the list of world-mutating acts in the order they are applied. Each hasat, an integer frame withfirst_frame ≤ at < first_frame + steps, andop, one of the names below. The list is sorted byat; two ops at one frame apply in list order.checkpointslists at least one{ frame, grid_hash }, frames strictly increasing within[first_frame, first_frame + steps], eachgrid_hashsixteen lowercase hex digits (the engine’sgrid_hash, the digeststarlab_sim_grid_hashprints and the twin’sgrid_hash()reproduces). The last frame’s checkpoint is required: a tape with no digest at its end claims nothing.recorderis optional provenance, free-form strings the reference does not check and the record carries: which app recorded, the engine it ran (engine_sha256), its backend. It answers the determinism program’s open question (c), “tapes carry no provenance”.
The clock
The world stands at frame f. In this order: (1) the checkpoint at f, if listed, is the digest of the world
as it stands on arrival at f, before any op at f; (2) the ops at f apply, in list order; (3) one step
takes the world to f + 1. So the checkpoint at first_frame is the saved world’s own digest, and the checkpoint
at the last frame is the digest after the final step; no op may be listed at the last frame. A recorder measures a
checkpoint at the top of the frame, before it applies that frame’s edits.
The ops
The parameters are the engine’s own (starlab_sim_spawn_*, starlab_sim_edit_cells, starlab_sim_set_emitters
in starlab_sim.h); the twin applies each through the same word the engine writes (encode_cell_state,
grid_fill_box, grid_fill_sphere, Emitter::from_words). temp and state are i32 with a negative meaning the
material’s default; absent means −1. Corners are inclusive, in order; a box or sphere is clamped to the grid; a
cell outside the grid writes nothing.
op |
fields | the engine’s call |
|---|---|---|
box |
x0 y0 z0 x1 y1 z1 mat [temp] [state] |
spawn_box_state (the console’s spawn_box, edit_box) |
sphere |
x y z r mat [temp] |
spawn_sphere |
cell |
x y z mat [temp] [state] |
spawn_cell_state |
cells |
xyz = {…}, mat = {…}, [temp = {…}], [state = {…}]: parallel integer arrays of one length; xyz packed `x |
y<<10 |
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 |
set_emitters (replaces the set) |
actor_add and actor_intent are the creature strand (below; readable since 2026-10-30, the reference handing a
tape that carries them to starlab-char’s reader). Reserved, not yet readable: actor_remove (the world record’s
bodies, L18), words (a dense box of arbitrary words, write_box), columns (edit_columns). A reader refuses an
op it does not know by name; it never skips one.
The reference
starlab-replay play <content dir> [--json] exit 0 agrees · 1 diverged · 2 refused
starlab-replay play <content dir> --mint [--every K] writes the checkpoints the twin measures
play opens the world with the tape’s options, refuses by name anything it cannot replay (the world’s refusals;
an unknown op; a frame mismatch; a missing hash), then walks the clock: at each listed frame it holds the twin’s
grid_hash() to the tape’s and stops at the first that differs, naming the frame, the expected digest and the one
it found. --mint keeps the listed frames (or every K frames from the first, plus the last) and rewrites tape.lua
with the digests the twin measured; it is how a tape is made without a console, and how the reference countersigns
one made with one. The browser twin plays the same tape through its C ABI (sl_op_box, sl_op_sphere,
sl_op_cell, sl_op_emitters; starburn/scripts/tape-wasm.mjs in node), and the fleet row holds native and wasm to the
same verdict on the same tape. The worlds page’s player plays it too (mountTape in
starburn/crates/starlab-wasm/web/starlab-player.js; a tape cart at /play/<record sha>), held to
tape-wasm.mjs’s verdict word for word by starburn/crates/starlab-wasm/web/tape.test.mjs (2026-10-30).
The record
A tape cart’s record.json is the cart record (docs/formats/cart.md, “The record”) with its replay witness run
by play: the payload’s replay carries verdict (agrees or diverged), the checkpoints held, the first and
last digests, the frame reached and the host; a diverged tape’s record has the verdict diverged (the cart is
well-formed and its claim is false, which the record says). A world the reference refuses leaves the record
replayable = false with the reasons (the refusal was recorded as a deterministic witness before this date; it is
not one).
The creature strand (2026-10-29; the reference plays it since 2026-10-30)
The sim-RL design’s D3 (docs/working-sim-rl-design-2026-10.md), drafted by the crate that reads it
(starburn/crates/starlab-char, starlab-char replay) on 2026-10-29. Since 2026-10-30 the reference starlab-replay play knows the two ops: a tape that carries them is handed to its reader, the program starlab-char replay
(STARLAB_CHAR_BIN, or starlab-char beside the reference’s binary), whose verdict and exit code the reference
relays: the same twin, the same grid_hash digests, actor_hash beside them. Without the reader the tape is refused
by name, saying where the reader was looked for; --mint on such a tape is refused (a creature tape is minted by
starlab-char episode --tape). A program and not a crate dependency: the creature’s contract and senses live with the
creature, and the reference keeps the open twin as its one dependency, so the engine’s export
(releases/starlab-engine.manifest) stays a closed set. A reader of another kind still refuses the ops by name.
The reserved actor_add and actor_intent ops carry a creature’s run over the cells’ tape: what it was when the
recording began, and what it DECIDED at each decision frame. Everything else (the kinematic substeps, the drives,
the consumption of a sensed cell, death) the reader re-derives from the world and the contract, so a tape of
intents is a tape of the run, not a transcript of it.
op |
fields | meaning |
|---|---|---|
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 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 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) |
The clock keeps its order: at a decision frame f, the checkpoint at f (the world AND the creature on arrival),
then the ops at f (the intent), then eight steps to f + 8 with the held intent, the drives at the rates sensed at
f, and the consumption at the boundary. An intent at a frame that is not a decision frame (first_frame + 8k) is
refused; a decision frame without an intent is refused (“no intent at frame f”); a creature that died ends the
tape (its steps end where the window broke).
A checkpoint may carry actor_hash beside grid_hash: sixteen hex digits, the actors’ state digest on
arrival at the frame (FNV-1a 64 over the creature’s words, then each mate’s in index order: position and energy by
their bits, the held drives and the held move, the commitment, alive; then the decision count). A reader that
knows the strand holds both; a reader that does not reads only grid_hash (it ignores a key it does not know, as
recorder’s keys are ignored).
recorder gains brain (which row decided: random, scripted, policy), contract, contract_hash, seed,
level (compact, sampled, herd, burn), actors, and not_in_twin (the stages of the console’s frame the
twin does not carry: the particle pool, the heightfield), so the record says what the run’s physics was.
ops = {
{ at = 0, op = "actor_add", id = 1, x = 14.3, z = 10.2, energy = 1, eat_commit = 0, held_sun = 0, contract = 3 },
{ at = 0, op = "actor_intent", id = 1, action = 1 },
{ at = 8, op = "actor_intent", id = 1, action = 1 },
…
},
checkpoints = {
{ frame = 0, grid_hash = "…", actor_hash = "…" },
{ frame = 32, grid_hash = "…", actor_hash = "…" },
…
},
Not drafted: more than one creature per tape (the fields allow it; the reader takes one), actor_remove, the
world record’s bodies (L18: the same clock one stratum deeper, docs/formats/world-record.md).
The console’s recorder: the matter door (2026-11-10)
The console writes tape.lua itself since the bodies program’s phase B1 (docs/design-bodies-2026-11.md §5;
starlab/console/elements/world_tape.lua, the verb tape). It is not the session tape below: that one records the
VERBS that came through the remote door, and this one hears the sim’s cell writers, whoever called them (a
creature’s bite, a body’s hand, the Kinect scene, a paint dab, a verb). What it adds to the shape above, all of it
additive (the reader passes over a key it does not name):
sourceon every op: who wrote ("humanoid:<id>","character:bite","serpent:graze","kinect_life:joint","verb:<action>";"untagged"for a caller that has not said). The design’s source attribution. A reader that plays the tape ignores it; a reader that audits one groups by it.via = "edit_box"on aboxthe console wrote on the device (edit_box) rather than through the host (spawn_box_state): the console’s replay calls the writer that made it. The two write the same words.tempandstateare the bytes the engine was handed (0 to 255), left out for the material’s default.breaks, a top-level list{ at, kind, source }: writes the format cannot carry that happened under the recording (write_box,load_linear,restore,record_load,clear,blast,emitters). A tape with a break is not replayable and says so: the console refuses to replay it, and so should any reader.recorder:{ app = "starlab-console", door = 1, every, trailing? }.trailingcounts writes made after the last step: by the clock above they are in no tape, and the tape is cut back to the last frame whose arrival digest was measured.
The origin. Beside tape.lua the console keeps state0.slws, the crate’s own save of the first frame
(docs/formats/world-record.md: every stratum, exact), and replays from that, in the console, on the native lane.
That is what makes its replay exact whatever the scene arms. It is NOT yet this kind’s content: the world cart
(grid.png + meta.lua, options) that the open twin plays is the export still owed, and most console scenes arm
what the twin refuses. emitters is not written yet either (a break).
The gate (starlab/console/tools/door_check.py): a real Kinect take played into a scene with a body writing
sand from its hands, a box, a sphere and a cell from verbs; the replay meets every checkpoint; the same run with one
writer made to bypass the door diverges; a run with no writes agrees; a scene load under a recording is refused.
What this is not
Not a recording of frames (starlab.replay/1 is: cells every K steps, scrubbed, never stepped); not the console’s
session tape (starlab/console/tools/tape.py, starbox verbs replayed on a live console, native lane only: its
export to this kind is the console’s half of the slice); not the writing-session tape (docs/formats/tape.md,
staros.steps/1); not the environment episode (envsvc.py: actions and a digest per ply over a served core). Each
of those is a replay; this is the one a stranger plays on the open twin.
The work on this page: the checks that hold it
- FAIL
lint/web-reference
Generated by tools/reference_pages.py from docs/formats/world-tape.md; the twin bfaad079a7ce (434093 bytes). The words are a draft.