The world edition (starlab.edition/1)
The format, 2026-10-30 (the editions slice of the replayable-worlds program; PRACTICES.md ruling 44, “the line
is Replayable worlds”; the operator’s rulings of 2026-10-30: the profile is content beside meta.lua, and the
difference tool lives first in the starlab console). Commons: the reference reader is love-shared/cart/kinds.lua
(Kinds.check_edition, chained from the world and tape readers) and the witness is
starlens/src/starlens/cartrec.py (edition_witness), run over the open twin’s commands. 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, an edition says where the run can be played. A starlab.world/1
cart carries the cells; a starlab.tape/1 cart carries the acts; neither says what the world was MADE FOR: a
phone in a hand, one page inside Discord, the open twin on any CPU, the engine under WebGPU. An edition names
the lanes the maker claims, and for each lane what the world needs from it, the budget it must hold, the picture
it is drawn with, and the device it assumes. The record’s witness then says, lane by lane, whether the claim
held on a named host, with the numbers, or was refused by name, or was never measured. A reader never fakes: a
lane that names a feature the lane lacks is refused by the witness with the twin’s own words (the sim’s law,
world.rs: “WHAT IS REFUSED, never faked … each named in the error, so a cart’s record can say what its world
needs”).
The edition is content, not manifest: it changes what the run IS for a visitor (the lane’s render tier, its
budget), so the content digest covers it, as the tape’s options are (world-tape.md: “these live in the content
… the content digest must cover them”). “A cartridge is a published data format plus a sealed record. It is never
code and never an engine” (cart.md): the WGSL a page carries, the parameter block, the module itself are the
PAGE’s, never the cart’s; an edition only names them.
The container
A starlab.world/1 or starlab.tape/1 cart MAY list one more file in its content:
content/
grid.png the cells
meta.lua the world's sidecar
tape.lua (a tape's run)
edition.lua the edition (below), canonical Lua data
The world (or tape) reader reads the world unchanged, then the edition against it: the edition’s name and the
lanes’ dims must be the world’s, and a lane’s model_mask must be the save’s when the save carries one. The
edition reads meta.lua’s name, dims, frame and sim.model_mask only, never the sidecars.
edition.lua
-- starlab.edition/1 · basin_splash
return {
format = 1,
name = "basin_splash", -- the world's (meta.lua's)
lanes = {
twin = { -- the open CPU twin: starlab-ref native, starlab-wasm in a page; the flat picture
needs = { features = { "flux", "air", "soot", "warm_air" }, model_mask = 40, emitters = 2, dims = { 64, 64, 64 } },
budget = { step_ms = 33, module_bytes = 600000, memory_mb = 64 },
render = { tier = "flat" },
device = {},
touch = false,
},
engine = { -- renderer 4 under WebGPU, CubeCL compiling in the page (starlab-web)
needs = { features = { "flux", "air", "soot", "warm_air" }, model_mask = 40 },
budget = { step_ms = 33, first_frame_ms = 8000, module_bytes = 20000000 },
render = { tier = "r4", passes = 7, render_scale = 1, bypass = 0 },
device = { webgpu = true, f16 = false, storage_buffers = 9 },
touch = { hold_ms = 260, pinch = true },
},
activity = { -- a Discord Activity: one self-contained page, the wasm twin inside it
needs = { features = { "flux", "air", "soot", "warm_air" }, model_mask = 40, emitters = 2 },
budget = { step_ms = 33, page_bytes = 4000000 },
render = { tier = "flat" },
device = {},
touch = { hold_ms = 260, pinch = true },
},
phone = { -- Safari on a phone: a secure context, the lab's touch rules, a lower render scale
needs = { features = { "flux", "air", "soot", "warm_air" }, model_mask = 40 },
budget = { step_ms = 33, first_frame_ms = 17000, memory_mb = 512 },
render = { tier = "r4", passes = 3, render_scale = 0.45, bypass = 1280 },
device = { webgpu = true, f16 = true, storage_buffers = 9, secure_context = true },
touch = { hold_ms = 260, pinch = true },
},
wgsl = { -- the table edition: the engine's WGSL recorded at build, a page that compiles nothing
needs = { features = { "flux", "air", "soot", "warm_air" }, model_mask = 40 },
budget = { step_ms = 33, first_frame_ms = 3000, module_bytes = 2000000 },
render = { tier = "r4", passes = 3, render_scale = 1, bypass = 0 },
device = { webgpu = true, f16 = true, storage_buffers = 9 },
touch = { hold_ms = 260, pinch = true },
compiled = { build = "0123456789ab", f16 = true, passes = 3, params = 840,
kernels = { "r4_main_kernel", "r4_water_pass", "step_prologue_kernel" },
table = "<sha256 of the WGSL table the page carries>" },
},
},
recorder = { app = "starlab-console", engine_sha256 = "…", backend = "vulkan" }, -- optional, unchecked
}
formatis 1.nameis the world’s.lanesnames at least one lane. An edition that names no lane claims nothing and is refused. The lanes aretwin,wgsl,engine,activity,phone;desktop,coopandblenderare reserved for a later catalog and refused; any other name is refused by name.- A lane’s keys are
needs,budget,render,device,touch, andcompiledon thewgsllane only. A key the reader does not know is refused by name; it never skips one. recorderis free provenance, as the tape’s: unchecked.
The lanes
twin. The open reference simulation, word-exact with the engine: starlab-ref natively and starlab-wasm
in a page (the C ABI sl_*, no bindgen, ~0.5 MB). Not in it: the particle pool, actors, the heightfield, the
surface layers, FLIP, bedload, the console’s tides, the CA spray, the flux jets; sixteen emitters. Its picture is
flat: the player’s WebGL2 voxel view, one fixed light, the material palette, “Not renderer 4”. The lane the
Activity and every phone without WebGPU get.
engine. Renderer 4 under WebGPU, CubeCL compiling the kernels inside the page (starlab-web). Needs
navigator.gpu; f16 where offered; at most nine storage arrays a kernel. The cost is the compiler in the page:
the first frame pays CubeCL’s compile and the browser’s own pipeline compile.
wgsl. The same engine with its kernels’ WGSL recorded at build, per (build, f16), and fed back through
CubeCL’s precompiled-source door, so the page compiles nothing of its own. Bit-identical to engine by
construction; the three-way row proves it per build. compiled names what the page carries.
activity. A Discord Activity: ONE self-contained page, every asset inlined, no host outside the app’s mapping
(the proxy’s content-security policy), the click guard, the storage keys inventoried, no OAuth scope. The wrapper
is staros web activity; the page’s bytes are the lane’s budget.
phone. Safari on a phone: WebGPU in a secure context only, a lower render scale, the lab’s touch rules (hold to arm, pinch to zoom), a GPU memory a few labs can exhaust.
What a lane claims
needs:features, a list of names from the catalog — the twin’s refusal names made nouns —flux,flux_mass,air,soot,warm_air,biomes,geo,climate,emitters,charge,consol,xfer,pool,heightfield,surf,bedload,flip,ca_spray,jets,moon;actors,columns,wordsandshardsare reserved for a later catalog (the tape’s reserved ops, the record’s P/Q/X strata).model_maskis an integer 0..1023 (the ten model bits, FLUX 1 … GRAN_RUN 512) and equalsmeta.sim.model_maskwhen the save carries one.emittersis what the world books (≥ 0; the native lane carries 16).dimsare the world’s. A lane may name a feature the lane lacks (poolontwin): the reader accepts the shape and the witness refuses it by name.budget: at least one ofstep_ms,first_frame_ms,page_bytes,module_bytes,memory_mb, each a positive number. A lane with no budget claims nothing and is refused.step_ms = 33is the house’s live line (a world runs live under 33 ms a step on the reference,carts.json’slive_ms).render:tierisflatorr4. Underr4:passes0..7 (renderer 4’s pass gate: WATER 1, ICE 2, UW 4; 7 is every pass),render_scalein (0, 1] (render param 81),bypass≥ 0 (param 169’s bits), and optionallylens = { mode, band, lo, hi }(param 168’s lens; mode 6 is the map lens, mode 7 the game lens: the flat three-face look with edge lines) andortho = { yaw, pitch, tile_w }(2026-10-30, the iso edition: the lane draws through renderer 4’s orthographic camera at that pose, yaw and pitch in degrees (45 and 30 are the 2:1 diamond; pitch in (0, 90]),tile_wthe pixels across a cell’s diagonal, an even integer 2..256, the view’s half-height following from the pane’s). Underflatthose keys are refused.device:webgpu,f16,secure_context(booleans),storage_buffers(≥ 1, the arrays a kernel may bind). A fact absent assumes nothing.touch:false, or{ hold_ms = n, pinch = bool }.compiled(wgslonly):build(hex, 12 or more digits: the module build the WGSL was emitted by),f16,passes,params(840, the render block’s length),kernels(the stable kernel names, at least one),table(optionally, the sha256 of the WGSL table the page carries).
Nothing in this version is removed by a later one.
What the record witnesses
The cart’s record (record.json, assay/2, kind cart) gains a payload edition with one entry per lane the
edition names, each with a verdict:
| verdict | meaning |
|---|---|
held |
every named budget under its number, every device fact present, nothing refused — on the named host |
over_budget |
a budget missed: over = [{ budget, value, limit }], the numbers beside the claim |
refused |
the lane refused the world: refused = [names], the tool’s own words |
unmeasured |
no tool here for the lane; never a pass |
The witness entry { name = "edition", deterministic = true } joins the record only when at least one lane was
measured; the cart’s verdict (conforms, malformed, diverged) and replayable are untouched by a lane’s
word. An edition whose lanes all read unmeasured has claimed and proved nothing, and the record says so lane by
lane.
The reference
| lane | the tool | measures, against the budget | refuses |
|---|---|---|---|
| twin | starlab-replay <content> --steps N --json (a world), starlab-replay play <content> --json (a tape); the browser twin’s replay-wasm.mjs / tape-wasm.mjs when the module is at hand |
ms_per_step → step_ms; wasm_bytes → module_bytes; memory_mb |
the twin’s refusal list IS the witness; more than sixteen emitters |
| activity | staros web activity --check <page> and the page’s bytes; the wasm twin’s numbers |
page_bytes, step_ms |
a --check finding, by its line |
| engine | the lab’s facts (__starlabLab / facts()), recorded to a facts file |
first_frame_ms, step_ms, wasm_bytes → module_bytes; device against adapter, shader_f16, max_storage_buffers_per_shader_stage |
f16 claimed and absent; webgpu claimed and no adapter |
| phone | the web-phone report’s facts | as engine, and secure_context |
as engine |
| wgsl | the table lab’s facts | as engine, and compiled.build against the runner’s build |
a build mismatch (both ids named); a kernel not in the table, by name |
The console
THE EDITIONS (the starlab console, ' e): one world, one frame, one pane per lane the edition names. An r4
lane’s pane is renderer 4 through the frame’s view table with the lane’s lens; a flat lane’s pane is the
twin’s picture drawn from the same cells (the player’s shader over the console’s grid stream). Under each pane
the lane’s word, its measured numbers, its refusals, its tier. Renderer 4’s pass set, render scale and bypass
bits are the FRAME’s, not a view’s: a lane’s tier is applied to the whole frame on a key, and the sheet
(starbox editions-sheet) shoots each lane’s tier in turn on the same frame and camera and prints each pane’s
FLIP against the engine pane — the difference number.
Reserved
Lane names desktop, coop, blender; feature names actors, columns, words, shards. A reader refuses
them as reserved; it never skips them.
What this is not
Not a build target, not a deploy, not a page: the edition names lanes, it does not make them. Not a licence or a
price. Not the tape’s options (sim_salt, model_mask, xfer_every, air_every stay the tape’s; an edition’s
model_mask is the same number, claimed per lane, and must agree with the save’s).
The work on this page: the checks that hold it
- FAIL
lint/web-reference
Generated by tools/reference_pages.py from docs/formats/world-edition.md; the twin bfaad079a7ce (434093 bytes). The words are a draft.