Skip to content

Architecture

Jump to bottom
UnitBuilds edited this page Oct 11, 2026 · 3 revisions

Architecture

Condensed from docs/01-architecture.md.

Status: architecture specified. A-01 contracts/coords.rs is frozen (2026-10-11, on ADR-029's sign-off) — every layer may now implement against the coordinate surface. The rest of contracts/ is not frozen. A layer whose subsystem doc cites an open SPEC/OQ is a description, not a build target.

The stack

Layer Choice Property
Engine runtime Rust + WebGPU/WGSL memory-safe, cross-platform, browser-capable
Coordinates HDCS: i64 global + camera-relative f32 infinite range, bit-identical across machines
Macro state Merkle ledger + localized octree roots, LSM-style compaction world bounded by hash/disk, not RAM/tick rate
Micro edits Sparse delta mask, bitpacked u64 in slabs O(1) write, cleared at commit
Memory Slab allocator, bump pointer, L1 VRAM / L2 RAM, LRU zero fragmentation, O(1) mass reset
Rendering GPU compute SDF raymarching no meshes, no textures, infinite detail
Culling Spatial BVH keyed to slabs O(log N) entity skip
Physics Analytic ∇SDF gradient queries normals without vertex buffers
Animation Domain deformation over time no skeletons
Audio Sphere-traced SDF occlusion sound knows the geometry, nothing baked
Circuits Compiled graph topology f(inputs, t) zero wire latency, runs while unloaded
Macro simulation Time functions + bounded CA + event tags lazy, fast-forwarded at observation
Logic & mods Polyglot WASM behind WIT contracts deterministic, sandboxed, hot-reloaded
Assets RON/JSON/KDL/TOML authored → FlatBuffers runtime human to write, zero-copy to run
Multiplayer Signed intent streams + rollback + epoch root verification 32 bytes proves world equality

Data lifecycle

AUTHORING (RON · JSON · KDL · TOML · Rust/TS/C++/Python/Go · WGSL)
      │  assetc: parse once, validate, emit binary   (<5 ms, never at frame time)
      ▼
CONTRACTS (FlatBuffers .fbs + WIT worlds)            ← the only thing the runtime trusts
      │  mmap / memcpy → GPU storage buffers
      ▼
ENGINE RUNTIME  (ledger · slabs · BVH · gradients · WASM · graphs)
      │  per frame, camera-relative f32
      ▼
RENDER PROJECTION (WGSL compute raymarcher → pixels)

The rule this encodes: text exists only to the left of the compile step. The runtime never parses.

Two-layer state

        GLOBAL MERKLE LEDGER   (slow, cheap, authoritative, hashable)
                    ▲ commit at epoch / sleep
   LOCAL DELTA MASK ┘──► GPU RENDER PROJECTION   (fast, local, disposable)

The ledger records what happened as transactions and named event tags. The projection computes what you see from MerkleRoot_N ⊕ LocalDelta for this frame's frustum.

Core equations

Name Form
view-time state BlockState = f(Position, CurrentTick) ⊕ PlayerDelta
rendered state Final = S_base ⊕ M_local
epoch commit S_new = S_old ⊕ M_local, then M_local = ∅
render pass pixels = Render(SlabState(FrustumSlabs), C_global) — state arrives by buffer, the shader only projects it
clock circuit state(t) = ⌊(t + φ)·ω⌋ mod 2
factory output items = ∫[t_start → t_sleep] ProductionRate(t) dt
epoch proof EpochHash = MerkleHash(BaseGenesisRoot ⊕ CommittedSlabs)
surface normal N = ∇SDF(p) (central differences, 6 evaluations)
camera transform P_local = P_global − C_global

Note on the render-pass row. The source wrote it as VoxelOutput = ComputeShader(XYZ, MerkleRoot_N) ⊕ LocalDelta — the GPU deriving voxel state from a Merkle root. That form is rejected (SPEC-02, ADR-017): f(pos, epoch) runs in deterministic Rust/WASM, because WGSL float math differs per adapter and two GPUs would produce two roots. The row above is the sanctioned reading; the original is kept here so the correction is visible rather than silent.

Invariants

  1. One coordinate truth — every subsystem resolves space through HDCS; no private axes.
  2. Simulation never reads the GPU — gradients come from SDF source on CPU/WASM, not VRAM.
  3. Hot path is allocation-free — pre-reserved slab slots only.
  4. Runtime parses nothing — FlatBuffers / static WASM memory.
  5. Deterministic or not shipped — canonical state uses integers, fixed-point, or deterministic WASM float ops whose result nothing hashes; nothing a hash depends on comes from a shader (ADR-017, the fix for the design's most dangerous inconsistency).
  6. The delta mask is the memory — player changes survive in M_local or a committed epoch; untouched base land is regenerable and never treated as storage.
  7. Epochs are total — mid-epoch truth is always base ⊕ pending.
  8. Mods are transactions — never direct block-array writes.
  9. Contracts change by ADR only.

What it buys, what it costs

Buys: world scale bounded by disk/hashes; no state loading screens (fast-forwarding centuries is a hash-and-flag update); near-zero storage for untouched terrain; a visibly aged world without per-entity pathfinding; every asset expressible as text; verifiable multiplayer in 32 bytes.

Costs (each tracked as an open question, not a footnote): traditional redstone-style sequential logic is unsolved (OQ-02); distant causality needs a mechanism nobody has proven (OQ-01 — the spike that can invalidate the design); SDF raymarching costs fill-rate and lives or dies on culling discipline; and the world gives up exact mid-simulation history in exchange for endpoint correctness.

Clone this wiki locally