Files
aevolution/docs/world/BASE_GENERATION.md
T

4.1 KiB

M5.3 abiotic base contract

Implemented in evo::world, public header evo/world/generation.hpp. ADR-0044 freezes the exact v1 integer algorithm. This is a bounded synthetic terrain fixture, not a geological planet model.

Inputs and output

BaseDescriptor contains uint64 seed and explicit coordinate/generator/material versions and edge. The supported tuple is (1,1,1,16); all seeds are valid. Versions are independent of biological simulation and snapshot format versions. Raw descriptor construction does not validate it. Each entry validates before address arithmetic or allocation, in coordinate/generator/material/edge order.

  • base_sample(descriptor, VoxelAddress) returns one validated CellSample.
  • generate_base_chunk(descriptor, ChunkAddress) returns exactly 4096 samples in X-fast, then Y, then Z order, equivalent to point queries at the chunk's cells.
  • material_name(table_version, MaterialId) resolves only v1 keys 0/1/2 to immutable static names void/rock/regolith. Unknown tables and keys return typed errors.

Coordinate bounds, cell pitch and fill retain ADR-0042 semantics. Invalid inputs return expected errors with no partially returned state. Standard allocation failure propagates to the host exception boundary. Functions perform no I/O, spawn no threads, use no clocks/global RNG and retain no mutable state; independent callers may execute concurrently. Every logical sample is void or fully filled inert material. There is no organism, lineage, biomass, nutrient or biological soil creation. Material identity is not an extractable resource inventory; M6 must define inventory accounting separately.

Boundaries and ownership

flowchart LR
  D[Seed + versions + chunk address] --> V[Validate request]
  V --> G[Pure global-address sample rule]
  G --> S[4096 logical staging samples]
  S --> C[M5.4 compact owned chunk]

Neighbor agreement means the same global cell has the same value, including when queried as a neighbor halo. Different neighboring cells need not match. The generator has no chunk-local seed or iteration-dependent state, so it cannot add chunk-border terrain discontinuities. Jagged per-column height changes are intentional v1 fixture behavior, not a smooth meshing claim. Z is up; surface lies in [-8,7]; three regolith cells lie below it, then rock. Cells at or above it are void.

Output is a temporary logical vector (4096 CellSample values), not compressed resident storage. M5.4 must account for staging and convert into ADR-0043's uniform/palette/dense layout. No world-wide cache or resident allocation grows here. The caller retains the descriptor, world/frame identity and address; raw vectors carry no durable identity or revision and must not be mistaken for authoritative stored chunks.

Compatibility and verification

Persist the complete descriptor, frame/world identity and address in M5.6. Reject unsupported versions without falling forward to current defaults. A future generator must keep v1 dispatch available for referenced worlds, or perform an explicit reviewed migration. Clones with the same descriptor/address intentionally regenerate the same base. Geometry regeneration is not an authorized terrain edit or matter transfer.

tools/world_generation_reference.py independently computes 12 frozen fingerprints for seeds 0, 123456 and UINT64_MAX and four signed chunks. Run it with Python 3; it prints reference rows without modifying tests. Fingerprints hash material u16 LE then fill u16 LE in X-fast order using FNV-1a. They are compatibility tests, not an adopted codec, security hash or justification for replacing a golden after a failure.

CTest world-generation-contracts checks those goldens in reversed and forward query orders, unrelated intervening generation, all 262144 samples in a 4x4x4 chunk volume, all-axis origin seams, independently located strata, material membership, coordinate corners/extremes and unsupported versions. Existing simulation goldens remain intact. Cross-platform integer agreement is the required contract; local Windows success alone is not evidence that Linux CI has run.