Files
aevolution/README.md
T

89 lines
3.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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)
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.