Files
aevolution/docs/architecture/WORLD_ARCHITECTURE.md
T
dingoandClaude Opus 5 d5b4bd068e Initial commit: architecture docs and headless engineering proof
Aeternalis Evolution, a custom-engine persistent evolutionary MMO.

This first commit establishes the project skeleton:

- Architecture and design docs: project vision, system overview,
  engineering constitution, roadmap, 19 ADRs, and the simulation,
  world, network, persistence and infrastructure architectures.
- Headless engineering proof: deterministic synthetic particles,
  component lifecycle, explicit PRNG streams, canonical snapshots
  and restored execution.
- Build and tooling: CMake 3.28+ / Ninja presets, C++23 feature
  check, clang-format and clang-tidy config, format check script,
  Windows check script, and a Docker build context.
- Tests: unit tests, benchmarks, a snapshot fuzz target and CLI
  integration wiring.

No gameplay, renderer, network service or running deployment yet.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-14 15:44:41 -04:00

5.6 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.