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>
106 lines
5.6 KiB
Markdown
106 lines
5.6 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.
|