Files
aevolution/README.md
T
dingoandClaude Opus 5.5 9bb147de82 Implement M9.5 biology-derived organism rendering and inspector
Add OrganismPresentation cells derived via biology::derive_phenotype with
no controller, owner or level fields (pinned by test), so identical
biology renders identically for players and NPCs. OrganismLayer reuses
the ADR-0080 ordering/freshness semantics; death is a remnant state and
removal is absence. Rendering takes an explicit rectangle budget, falls
back to body-only detail and marks truncation instead of dropping data.
An opt-in rectangle-only hover inspector shows phenotype gauges; ImGui is
not adopted. ADR-0081 records the decision; evidence in VALIDATION.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 18:21:53 -04:00

179 lines
9.1 KiB
Markdown

# Aeternalis Evolution
A custom-engine persistent evolutionary MMO. The world retains its biological
history; each player life begins as a primitive cell and ends permanently.
This repository starts with architecture and a headless engineering proof:
deterministic synthetic particles, component lifecycle, explicit PRNG streams,
canonical snapshots and restored execution. It contains no gameplay, renderer,
network service. Dev verification manifests are separate from the simulation.
## Start here
- [Project vision and locked requirements](docs/PROJECT_VISION.md)
- [System overview and module boundaries](docs/architecture/SYSTEM_OVERVIEW.md)
- [Engineering constitution](docs/engineering/ENGINEERING_CONSTITUTION.md)
- [Architecture decisions and proposals](docs/adr/README.md)
- [Actionable milestones 0–4 and later gates](docs/ROADMAP.md)
- [Open design questions](docs/architecture/OPEN_QUESTIONS.md)
- [World snapshots and edit journals](docs/world/WORLD_CODEC.md)
- [Local file publication manifest](schemas/local-world-manifest.md)
- [Transactional terrain excavation](docs/world/TERRAIN_EDITS.md)
- [Bounded chunk ownership](docs/world/CHUNK_OWNERSHIP.md)
- [Versioned abiotic base generation](docs/world/BASE_GENERATION.md)
- [Actual validation results](docs/engineering/VALIDATION.md)
- [Current delivery status and next steps](docs/STATUS.md)
- [Region durability and state-closure contract](docs/architecture/REGION_DURABILITY.md)
- [Bounded environmental intervals and resume](docs/architecture/ENVIRONMENTAL_SCHEDULING.md)
- [Opt-in ECS evaluation and measurements](docs/engineering/ECS_EVALUATION.md)
- [Sequential command scheduling and recovery](docs/architecture/SCHEDULER_CONTRACT.md)
- [Local periodic spatial queries](docs/architecture/SPATIAL_CONTRACT.md)
- [Energy/matter model and implemented ledger boundary](docs/biology/ENERGY_MODEL.md)
- [Environmental units and habitat coupling](docs/world/ENVIRONMENTAL_UNITS.md)
- [Optional finite environmental fields and snapshot format](docs/world/ENVIRONMENTAL_FIELDS.md)
- [Read-only environment footprints and freshness](docs/world/ENVIRONMENT_VIEWS.md)
- [Genome model and implemented v1 record](docs/biology/GENOME_MODEL.md)
Read [AGENTS.md](AGENTS.md) before changing code. Architecture and contracts are
authoritative over implementation. No external runtime library is needed for
the initial proof. C++23 support is checked during configuration.
## Build and run
Requires CMake 3.28+, Ninja and a C++23 compiler/standard library supporting
`std::expected`. GCC 14 is the initial Linux CI target; MSVC 19.44 or newer is
the Windows target. Detailed verified tool versions are in the validation report.
```sh
cmake --preset debug
cmake --build --preset debug
ctest --preset debug
./build/debug/evo-sim --seed 123456 --entities 8 --ticks 1000 --verify-replay
```
On Windows use a Visual Studio x64 developer shell, or the repository's
`tools/windows-check.ps1` helper. Executables have `.exe` suffix on Windows.
```sh
./build/debug/evo-sim --seed 123456 --entities 8 --ticks 500 --save state.evo
./build/debug/evo-sim --load state.evo --ticks 500 --output results.json
```
```sh
./build/release/evo-sim --ecosystem --seed 0 --episodes 3000
```
Ecosystem mode measures seeded bounded episodes of the synthetic feeding community
and reports ticks, births, both mortality paths, extinctions and a fingerprint. It
shares no state, snapshot or particle metric with the proof run, and its strategy
constants are measurement inputs rather than simulation rules. See
[ADR-0029](docs/adr/0029-ecosystem-driver-and-episodes.md) for scope.
```sh
./build/release/evo-sim --ensemble --seed 0 --seeds-per-cell 4 --strategies 3 --tick-limit 400
```
Ensemble mode derives strategies from genomes instead of writing them, then runs
them on that same driver over a resource and temperature gradient. Each cell's
seeds are split in half and both halves are reported separately and never merged,
so a difference that appears in one half only is visible as the seed artifact it
is. Options belong to exactly one mode: `--episodes` counts episodes and is
rejected here, `--seeds-per-cell` counts seeds and is rejected in ecosystem mode.
A cell's numbers are not fitness, adaptation or balance, and the resource axis is
deliberately not monotonic. Lifetimes are censored: an organism still alive when
an episode stops is reported as a survivor with the time it was watched, never as
a death, so `lived_ticks` and `observed_ticks` answer different questions. See
[ADR-0035](docs/adr/0035-genome-ecology-ensembles.md) for scope and for why.
The second command continues saved PRNG/component state. `--verify-replay`
compares an uninterrupted run to a midpoint serialization/restore run. JSON
reports the seed, ticks, active entities and canonical state hash. Snapshots
are bounded local test files; they are not crash-consistent production storage.
## Checks and measurements
```sh
cmake --build --preset debug --target format-check
cmake --preset analysis
cmake --build --preset analysis
cmake --preset asan
cmake --build --preset asan
ctest --preset asan
cmake --preset release
cmake --build --preset release
ctest --preset release
./build/release/evo-benchmark
./build/release/evo-spatial-benchmark
./build/release/evo-resolution-benchmark
./build/release/evo-chunk-layout
```
ASan uses UBSan too on supported Linux compilers. TSan has a separate `tsan`
preset and is never combined with ASan. clang-format/tidy major 19 is the initial
analysis baseline. The optional Clang libFuzzer target exercises snapshot
restore. See [testing strategy](docs/engineering/TEST_STRATEGY.md) and
[deployment scaffold](deploy/README.md) for scope and commands.
## Repository boundaries
`include/evo` exposes core values and the headless simulation API.
`src/simulation` implements component state, tick ordering and local snapshot
codec. `src/accounting` provides the independent finite-inventory ledger;
it is not yet part of particle snapshots. `src/processes` holds the synthetic
producer, feeding, reproduction and episode fixtures built on that ledger; they
are bounded experiments, not organism biology. `src/biology` holds the immutable
genome record, the deterministic development that derives a phenotype from it and
the metabolic budgets that give capability a cost, and the seeded mutation
catalog that proposes successors and the archive that keeps them. No fixture reads
a genome yet.
`apps/evo-sim` owns CLI/file I/O
and reporting. `tests` holds contract,
fuzz and measurement programs. Future biology, world, networking and persistence
modules are documented boundaries; they are added when they have real behavior.
World0 is persistent state. No normal configure, build, test or CI job may create,
reset, deploy to or delete it. Gitea builds the proof image for Harbor; a bounded
dev verification Job and manual Argo templates are in [deploy/](deploy/README.md).
Persistent-world deployment still requires storage, ownership and backup gates.
The project license has not been selected. Do not infer an open-source license
from a public dependency's license.
M4.6 reproduction, measurements and limits: [aggregate budget report](docs/engineering/AGGREGATE_BUDGET.md).
M5.1 local voxel/address API and scope: [local voxel contract](docs/world/LOCAL_VOXEL_CONTRACT.md).
M5.8 process restart proof and measured costs: [world proof](docs/engineering/WORLD_PROOF.md).
M6.4: [atomic environmental transfers](docs/world/ENVIRONMENTAL_TRANSFERS.md)
own finite field and organism resource compartments together. Biology integration
is next (M6.5); coupled snapshot/recovery remains M6.8.
M6.5c: [persisted producer/consumer fixture](docs/biology/ENVIRONMENTAL_PROCESS.md),
with finite source capture, tagged growth/feeding and complete rate/lifecycle snapshots.
It is a library/test fixture; existing CLI modes and M2/M3 rules are unchanged.
For the M6.5 boundary/seeded suite and local cost report, run
`build/release/evo-environmental-qualification --long` (add `.exe` on Windows).
See [environmental qualification](docs/engineering/ENVIRONMENTAL_QUALIFICATION.md)
for parameters, coverage and limitations. The shorter suite runs through CTest.
## PostgreSQL bootstrap (M7.2)
See [PostgreSQL setup](docs/infrastructure/POSTGRESQL.md) for the optional Linux
adapter, isolated integration checks and Kubernetes Secret/migration instructions.
The default simulation build does not require PostgreSQL.
## Native client dependency probe (M9.1)
The optional SDL3 probe is separate from the headless targets. See
[client dependency preparation and checks](docs/engineering/CLIENT_DEPENDENCIES.md).
M9.2 supplies the [native engineering client](docs/engineering/CLIENT.md), with
an immutable frame boundary and tested window/resource lifecycle.
M9.3 adds [camera navigation and input intentions](docs/engineering/CAMERA_INPUT.md),
with explicit UI capture and no authoritative movement or network connection.
M9.4 renders [revision-tagged environment views](docs/engineering/ENVIRONMENT_RENDERING.md)
with explicit missing/stale presentation from a local in-memory fixture authority.
M9.5 adds [biology-derived organism rendering](docs/engineering/ORGANISM_RENDERING.md)
with no player/NPC labels and an opt-in engineering inspector.