200 lines
11 KiB
Markdown
200 lines
11 KiB
Markdown
# 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.
|
|
|
|
```mermaid
|
|
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.
|
|
|
|
```mermaid
|
|
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](../adr/0042-local-voxel-contract.md) and the
|
|
[local voxel contract](../world/LOCAL_VOXEL_CONTRACT.md) 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](../adr/0043-chunk-layout.md) 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](../adr/0044-abiotic-generation.md) and the
|
|
[base generation contract](../world/BASE_GENERATION.md) 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](../adr/0045-bounded-chunk-ownership.md) adds compact immutable cells and a
|
|
fixed-slot, byte-budgeted local store. [The contract](../world/CHUNK_OWNERSHIP.md)
|
|
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](../adr/0046-transactional-excavation.md) 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](../world/TERRAIN_EDITS.md) 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](../world/WORLD_CODEC.md) 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.
|
|
|
|
M5.8 validates the local stack through separate prepare/compact/verify processes; see
|
|
[bounded world proof and measurements](../engineering/WORLD_PROOF.md). This adds no
|
|
production ownership or biological resource conversion contract.
|
|
|
|
## M6.1 environmental coupling boundary
|
|
|
|
[ADR-0050](../adr/0050-environmental-units-and-coupling.md) scopes a one-voxel,
|
|
axis-aligned habitat with explicit micrometre depth. The
|
|
[units contract](../world/ENVIRONMENTAL_UNITS.md) defines finite extensive stocks,
|
|
derived concentrations/moisture, dimensional examples, closed/open accounting,
|
|
rate residual ownership and rejection of unsupported terrain mass conversions.
|
|
The implemented helpers are pure computations. Inventory pages, reservations,
|
|
ownership enforcement, transfer commits and persistence follow in M6.2-6.4.
|
|
|
|
## M6.2 optional field storage
|
|
|
|
[ADR-0051](../adr/0051-optional-environmental-fields.md) implements a separate
|
|
bounded [FieldStore](../world/ENVIRONMENTAL_FIELDS.md). It owns fixed habitat sites,
|
|
explicit finite inventories, property-only material defaults and optional uniform/
|
|
sparse scalar pages. Its versioned codec retains all field state and local transfer
|
|
watermark, without relying on procedural resource regeneration. M5 LocalWorldFiles
|
|
still publishes only terrain state: integrated terrain/fields/biology recovery must
|
|
use a later version bundle. No cross-store biological transfer is authorized here.
|
|
|
|
## M6.3 environment reads
|
|
|
|
[ADR-0052](../adr/0052-read-only-environment-views.md) adds
|
|
[environment views](../world/ENVIRONMENT_VIEWS.md) across a bounded voxel footprint.
|
|
Samples carry exact typed field quantities, habitat volume, terrain chunk revision
|
|
and an explicit host tick. Queries never load chunks or mutate inventories. A
|
|
separate validator rejects stale ticks, field watermarks, foreign store instances
|
|
and stale sampled chunk tokens. Coherent store pairing and single-owner scheduling
|
|
remain host obligations; M6.4 must validate and commit in one ownership phase.
|
|
|
|
## M6.4 coordinated resource ownership
|
|
|
|
[ADR-0053](../adr/0053-atomic-environmental-transfers.md) and the
|
|
[transfer contract](../world/ENVIRONMENTAL_TRANSFERS.md) define one owner of field
|
|
stocks, terrain binding and tagged organism resource accounts. Fresh views authorize
|
|
only staged transfers; both endpoints and the retry receipt publish together after
|
|
validation and allocation. Accounts are resource endpoints; biological lifecycle
|
|
integration follows in M6.5. Field-only snapshots cannot recover a coupled owner.
|
|
|
|
M6.5a now provides [coupled resource snapshots](../../schemas/coupled-resources.md)
|
|
under accepted ADR-0054. This is a detached, bounded buffer codec; M7 still owns
|
|
file publication and durable acknowledgment. M6.5c must extend persistence to
|
|
source-rate and biological progress before enabling the corresponding simulation.
|