211 lines
10 KiB
Markdown
211 lines
10 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.
|
|
|
|
## Dev session protocol (M9.6)
|
|
|
|
Opt-in and separate from headless targets. Prepare the pinned TLS library, then
|
|
build and test:
|
|
|
|
```sh
|
|
cmake -P tools/prepare-mbedtls.cmake
|
|
cmake --preset network
|
|
cmake --build --preset network
|
|
ctest --preset network
|
|
```
|
|
|
|
See [DEV_SESSION_PROTOCOL](docs/networking/DEV_SESSION_PROTOCOL.md) and ADR-0082.
|
|
M9.7 connects `evo-client` (preset `client-network`) to a dev region running
|
|
`evo-server --session-listen ...`; see [DEV_SESSION_OPERATIONS](docs/networking/DEV_SESSION_OPERATIONS.md).
|
|
Windows: `tools/windows-check.ps1 -Preset network -Action check`.
|
|
|
|
|
|
M9.8a engineering UI compatibility probe (does not change evo-client yet):
|
|
|
|
```sh
|
|
cmake -P tools/prepare-sdl3.cmake
|
|
cmake -P tools/prepare-imgui.cmake
|
|
cmake --preset client-probe -DEVO_BUILD_UI_PROBE=ON
|
|
cmake --build build/client-probe --target evo-ui-probe
|
|
ctest --test-dir build/client-probe -R ui-probe --output-on-failure
|
|
```
|
|
|
|
Use an MSVC developer shell on Windows. See ADR-0084 and
|
|
[the M9.8 plan](docs/engineering/M9_8_DELIVERY_PLAN.md) for the remaining UI,
|
|
local Windows packaging and low-spec qualification work.
|