72 lines
4.1 KiB
Markdown
72 lines
4.1 KiB
Markdown
# M5.3 abiotic base contract
|
|
|
|
Implemented in `evo::world`, public header `evo/world/generation.hpp`.
|
|
[ADR-0044](../adr/0044-abiotic-generation.md) 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
|
|
|
|
```mermaid
|
|
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.
|