M3.3 turns a phenotype into the budgets a ledger can hold: body composition, maintenance, movement, the next construction step, the per-tick intake limit and the reproduction investment. metabolism is the single place the genome's description of capability becomes accounting quantities, so the record itself stays free of those types and M3.1's boundary is crossed once, explicitly. The named risk is reintroducing RPG modifiers, where a capability parameter becomes a flat percentage over every budget. Each budget is therefore derived from a different phenotype quantity: maintenance from mass plus membrane upkeep, movement from mass and speed, intake from surface, construction from the mass a growth step adds, investment from the body a parent already has. One parameter moves some budgets and not others, by different amounts. Doubling membrane thickness costs more matter to build, more energy to hold and more to haul, while leaving uptake, speed, assimilation and structural mass identical, and the mass and maintenance ratios differ, so no single multiplier could produce it. The test asserts that non-uniformity rather than describing it. Composition is declared per compartment, and membrane is the carbon-rich one, so a thicker membrane changes what a body is made of and not only how much. A split assigns the first three channels by share and gives the remainder to the last, so parts always sum back to the whole and a derived body can be spent through the ledger without a rounding leak. That is checked at four awkward masses where every share floors. processes::consumer_for is the first path from a genome into the M2 fixtures. Opening inventory stays the caller's: a genome says what an organism can do, never what it holds, and a derived config that invented an opening balance would create matter. A derived consumer is shown driving a real feeding tick with the ledger conserving exactly, and a bite one femtogram past the derived cap refused by the M2.3 contract. Every budget is asserted as a hand-calculated literal. The constants are chosen so budgets are of comparable magnitude, which is legibility for tests and not tuning. No existing fixture reads genomes, and no organism spends any budget: there is still no starvation, death or repair rule. Native Release, clang-tidy analysis, ASan and format checks pass 19/19; every existing golden and fingerprint is unchanged. Linux CI has not run. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
111 lines
5.1 KiB
Markdown
111 lines
5.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)
|
||
- [Actual validation results](docs/engineering/VALIDATION.md)
|
||
- [Current delivery status and next steps](docs/STATUS.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)
|
||
- [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.
|
||
|
||
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
|
||
```
|
||
|
||
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. 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.
|