90 lines
3.9 KiB
Markdown
90 lines
3.9 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)
|
||
|
||
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
|
||
```
|
||
|
||
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
|
||
```
|
||
|
||
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. `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.
|