Skip to content

Home

Jump to bottom
UnitBuilds edited this page Oct 13, 2026 · 22 revisions

Merkles World

A voxel sandbox engine where the world is a deterministic function of position and epoch rather than a database of blocks, player edits are sparse delta masks compacted into a Merkle ledger, and every asset is code, not art — SDF shaders and procedural materials written by LLM agents or modders, never modelled or textured.

No 3D modelling. No textures. No mesh pipeline. No per-tick chunk simulation.

Status: Phase 0 largely closed, Phase 1 in progress. The architecture is fully written down, and its internal contradictions are catalogued rather than hidden: nine registered SPEC conflicts (4 locked, 4 proposals, 1 open — SPEC-09, the conflict that had blocked freezing the coordinate and delta-record contracts, was closed on 2026-10-11 by ADR-029) plus 61 open questions. The first code has landed: a cargo workspace, the contracts/ surface (A-01 coordinates and A-10 tree shape — both frozen, the latter on 2026-10-12 by ADR-030; A-03 delta record, A-08 ActionTx, A-09 error taxonomy, A-02 ledger-api.wit and A-07's node grammar with its FlatBuffers envelope — all still draft), crates/coords, crates/ledger — the first crate with behaviour (the BLAKE3 hasher, the epoch commit path, the read path and gate P1.6's bisection), crates/memory (A3's slabs), crates/render (a CPU reference for A-07 — thirteen of its fifteen kinds), crates/assetc (authored shape → records → ShapeAsset bytes → a loaded tree, plus the assetc command) and crates/engine — a binary that boots: slab into epoch root, the published vectors asserted, an edit read back, and a compiled asset marched — loaded from bytes it made or from a file you point it at, on a CPU. Spike S2 has its first numbers: gate P1.2 met, gate P1.3 not met, and the gap recorded as OQ-49. 194 tests are green — the same thirty suites on x86-64 Linux, x86-64 Windows and ARM64 macOS in CI, where EPOCH_0 still prints byte-identically and one flatc-packed asset parses into the same nodes on all three. The repo is licensed MIT OR Apache-2.0, and ADR-026 (wgpu), ADR-028 (BLAKE3-256) and ADR-030 (the tree shape) are signed off — the decisions that let engine code start, with BLAKE3 the workspace's first external dependency. Still missing from the pitch demo: a drawn scene on real hardware — no GPU upload and no frame timing yet, which is OQ-51 (one CC0-1.0 licence inside wgpu's tree, and it cannot be feature-trimmed away), macro simulation, and the frame-0 visibility of a committed edit (OQ-47's naming, waiting on OQ-50's voxel-span ruling). Culling is no longer among them: enclosure, per-node bounds, a ray-level descent and tiling are landed and measured; compaction landed as a root-preserving transform (its frequency is the open OQ-49); and a WGSL master interpreter matches the CPU reference within 0.0001 world units wherever a CI runner has a device — and on main since 2026-10-13 — OQ-51 was decided, hexf-parse's CC0-1.0 allowed with its reason in the file and paste waived by the advisory id cargo-deny printed (RUSTSEC-2024-0436); what R1 still waits on is hardware, not a licence. Still missing, and unchanged: gate P1.5's four devices — the N2600, the RTX 3060 box, the Linux-Mesa machine, and a real browser on an M1: 0 of 4 named targets have reported, a count that comes out of docs/evidence.json's gate_p1_5_targets register and is checked against this sentence by tools/check_docs.mjs, so the gate's public state is data rather than memory. Running the roots inside a WASM engine turned out not to need the export-lint decision after all: the engine builds for wasm32-wasip1 on every CI architecture, runs under a WASI host, and prints roots identical to that runner's own native build — parity ok on arm64 and parity ok on x86_64 twice, 13 lines identical each at that run, which is historical — the boot block is 18 lines today and hashes to db71f8a0bf5818d6…, what docs/evidence.json publishes and every CI leg reproduces. That run, 38270620391 — with no export and no unsafe written in this repository. That decision stays open, and still governs mods exporting functions a host calls. See Roadmap & status and Open questions.

The two-phase plan

Phase Name Knows about Ships
1 Voxel-Ledger Engine Nothing game-specific: state, hashing, slabs, SDF rendering, WASM host, graph compiler A runtime that renders a procedural scene, edits it, and commits the edit into a new epoch root
1.5 Multiplayer Intent streams, rollback, epoch verification Co-op over the same deterministic state
2 Project Genesis Pigs, biomes, crafting, hunger, weather The game — built as Mod #1 on the public API

The idea in six lines

  1. Simulation is cheap; rendered simulation is expensive. Separate them and the world can be deep and fast.
  2. Unobserved land is an equation, not a saved chunk: BlockState = f(Position, Epoch) ⊕ PlayerDelta.
  3. Causality is an observation. A river that dried at tick 50 and is first seen at tick 100 is simply dry at 100 — the intermediate steps never run.
  4. Player edits live in a slab-backed delta mask, compacted into a new Merkle epoch when the player sleeps (an LSM-tree in disguise).
  5. A 32-byte epoch root proves two clients see the identical world.
  6. Assets, logic and mods are all text → compiled to zero-copy binaries and sandboxed WASM, so the mod API is the engine API.

Wiki pages

Page Contents
Vision & pillars Why the project exists; what was learned from Minecraft's rise
Architecture Layer map, data lifecycle, core equations, invariants
Roadmap & status Phases, spikes, blocking artifacts, the Bitwise Determinism Suite, honest timeline position
Decision log 29 ADRs, one line each
Open questions SPEC conflicts + the OQ register + unmeasured claims
Glossary Terms, symbols, abbreviations

Where the real documentation lives

These wiki pages are a condensed mirror. The authoritative, versioned spec is in the repository under docs/:

Doc Subject
00 · 01 vision, architecture overview
02 · 03 · 04 coordinates, state/ledger/slabs, rendering
05 · 06 · 07 simulation, circuits, physics/audio/animation
08 · 09 · 10 modding, assets, multiplayer
11 · 12 roadmap, agent swarm operations
13 · 14 · ADRs risks & open questions, glossary, decision log

Working rules for contributors (human or agent): AGENTS.md.

License

Licensed under either of

at your option. The same terms cover the code in crates/ and contracts/, which declare license = "MIT OR Apache-2.0" in [workspace.package]; cargo deny check licenses enforces it in CI. This settles the licensing half of OQ-43 (2026-10-11) — the naming half stays open, so the crates are not published yet.

Contributing

  • This is a build-in-public project: commits are clean and conventional, and documentation is updated in the same commit as the change it describes. When a repo doc changes materially, this wiki is updated to match.
  • Before proposing code for a subsystem, check whether its SPEC-/OQ- rows are still open in docs/13. Open means "write the decision first, not the code".
  • No mesh, texture or image assets — ever. That constraint is the project's identity, not a limitation to be eased later.

Clone this wiki locally