8.2 KiB
World architecture
Status: locked sparse, persistent, editable-world requirements; recommended contracts below; planetary topology, resolution and solvers remain experiments. These are future boundaries, not implemented environmental systems in M0.
flowchart TD
P[Planet seed and generation version] --> C[Planetary aggregate cells]
C --> R[Regions with leased authority]
R --> M[2D microscopic habitats]
R --> V[Sparse 3D environmental chunks]
V --> F[Derived fine detail and mesh caches]
M <--> L[Conservative ecological transfer ledger]
V <--> L
B[Immutable procedural base] --> V
D[Persisted modifications and snapshots] --> V
Region, terrain-chunk and ecological-cell boundaries need not coincide. A world mapping contract resolves them; assigning another process never changes durable addresses. Every lineage ultimately refers to a player-influenced founder; base generation supplies geology, chemistry and energy, never implicit wildlife.
Coordinates and contracts
Recommend a planet-centered right-handed reference frame for interchange, bounded region-local right-handed frames (+Z up) for active simulation and stable integer chunk addresses. Persist frame transforms, resolution, origin, units and versions. A microscopic habitat defines two metric axes and effective depth; 2D area never implicitly becomes 3D biomass. Render origin shifts do not move authoritative state. Use coarse addresses plus local offsets, not global hot entity floats. Final spherical indexing, radius, region/chunk sizes and precision remain open. M5 starts with a small local test volume.
| Logical contract | Inputs / outputs and invariant |
|---|---|
| GenerateBaseChunk | seed, generator/material versions, address → deterministic samples; no I/O clock |
| ReadEnvironment | footprint, requested fields, view → units, resolution, valid tick and error bound |
| ProposeEnvironmentalTransfer | action ID, owners, quantities → reserved inventory or insufficiency |
| CommitEnvironmentalTransfer | reservation, epoch → exactly one debit/credit; retry returns prior outcome |
| ApplyTerrainEdit | command ID, expected revision, geometry, matter destinations → new chunk revision |
| BuildSurface | immutable samples, neighbor revisions, mesher/LOD versions → disposable mesh/collision cache |
Representation and storage
See ADR-0019. Evaluate palette material IDs, quantized geometry, constant uniform channels, sparse varying field pages and coarser chemistry grids. Material tables hold shared coefficients. Allocate only relevant changing fields. Concentration derives from inventory/volume; temperature derives from thermal energy and heat capacity. A material ID does not imply unlimited extractable nutrients.
Quantization defines units, range, rounding and residuals. Refinement partitions existing inventory; coarsening sums extensive quantities before deriving intensive ones. Fine detail cannot contribute consumable matter without a parent budget. Benchmarks include geometry, fields, indexes, halos, dirty journals and caches; stress uniform, heterogeneous and heavily excavated worlds, including deep edits.
sequenceDiagram
participant W as Worker
participant G as Versioned generator
participant S as Object store
participant J as Durable manifest and journal
W->>J: Read committed manifest / covered sequence
W->>S: Read verified compacted payload if present
W->>G: Otherwise generate exact recorded base version
W->>J: Read complete committed edits after covered sequence
W->>W: Replay edits and validate inventory
W->>S: Upload immutable compacted candidate and verify
W->>J: Atomically publish new manifest / covered sequence
Keep generator versions required by existing territory. Never regenerate old chunks under new geology implicitly. Compaction records base/version/address, revision, covered sequence and digest. Upload alone is not a commit; deletion waits for clone/backup references and retention. Neighbor halos are read-only, revision-tagged state. Stale mesh work is discarded. Collision revision gating requires a later gameplay ADR; visually completed edits cannot bypass physics.
Ecological coupling and fidelity
2D organisms/cohorts debit biomass through a transfer ledger to 3D plankton density. Corpses debit organic matter to decomposition/nutrient reservoirs. Domains do not share literal physics. Each inventory has exactly one owner; active detail reserves a disjoint share of its aggregate. Transfers record ID, source/destination, epochs, logical interval, composition, amount and causal event.
Across regions, durably escrow the source before idempotent destination credit. Recovery retries or cancels using durable transfer state; elapsed time cannot authorize another credit. In-transit inventory remains in conservation totals. Edits displace mass to soil, carried resources, debris/fluid or an explicit sink. Excavation cannot simply delete matter.
Solver intervals are explicit integer multiples of world ticks. Use committed boundary views and apply integrated fluxes once. Catch-up is bounded and measured; never silently drop intervals. Hydrology, atmospheric chemistry, erosion, boundary conditions and acceptable numerical residuals remain experiments. M6 uses light, moisture and one or two nutrients, not global CFD.
Required tests: address round trips and seams; generator golden versions; duplicate edit idempotency; crash at every compaction boundary; oscillating LOD without resource gain; stale halo invalidation; stalled transfer escrow; corrupt objects/full disk rejection. No planet topology or smooth mesher is accepted until its comparison demonstrates precision, seam correctness and bounded cost.
Implemented M5.1 boundary
ADR-0042 and the
local voxel contract implement pure signed
address mapping, logical ordinal enumeration, metric corners and cell-fill
validation in evo::world. The 1m pitch and bounded local domain are experiments;
8/16/32/64-cell chunk edges remain comparison candidates, not a selected layout.
No data allocation, terrain generation, material table, mass transfer, persistence,
meshing or planet mapping is implemented by this contract. M5.2 measured storage; ADR-0043 selects
16-cube uniform/palette/dense geometry for the bounded M5 implementation. Production
chunk ownership/allocation limits remain M5.4; optional chemistry pages remain M6.
Implemented M5.3 generation boundary
ADR-0044 and the base generation contract add pure versioned point and 16-cube queries. Synthetic abiotic strata use global integer addresses and create no life. Unsupported versions fail explicitly. Temporary logical output is not resident storage; bounded chunk ownership/eviction is M5.4. There is no persistence or mesher.
Implemented M5.4 ownership boundary
ADR-0045 adds compact immutable cells and a fixed-slot, byte-budgeted local store. The contract specifies construction scratch accounting, current-revision read tokens, regeneration and dirty eviction refusal. No database, distributed lease or durable acknowledgement is implied. Cell edits remain M5.5 and persistence M5.6/5.7.
Implemented M5.5 edit boundary
ADR-0046 implements bounded single-store atomic excavation, per-material occupied-volume transfer to debris, current revisions, request digest plus full-payload retry identity, and bounded history with a command high-water mark. The contract specifies failure semantics. No mass/density model or persistence is implied. Debris/retry state must accompany geometry in M5.6/5.7 recovery, and M6 must reconcile volume with chemical inventories.
Implemented M5.6 snapshot/replay boundary
The world codec preserves loaded membership, dirty cells, versions, revisions, finite debris and retry history in one validated snapshot. Journal replay uses the existing excavation transaction on a detached store. Dirty chunks remain pinned; encoding does not acknowledge durability. M5.7 supplies local file publication and compaction; no production persistence dependency was added.