An evolution simulator where life emerges, adapts, competes, and speciates — all without programmer-designed species or behaviours.
Watch organisms evolve in real time. Each creature has its own neural network brain, inherited from its parents with mutations. Natural selection does the rest. Predators evolve claws. Prey evolves armor. Plants terraform the landscape. And sometimes an asteroid wipes the slate clean.
cargo run --releaseEach run gets a unique cosmic name (e.g. "pale-fading-shard"). Session data — chronicle log, screenshots, save files — lives in sessions/<name>/.
# Save: press F5 during gameplay. Export one creature: Inspect tab, "Export creature" writes sessions/<name>/<species>-t<tick>.json
cargo run --release -- --load sessions/pale-fading-shard # load a saved session
cargo run --release -- --seed-with vorax-t4567.json # add exported creatures to the founders (repeatable, several paths per flag; ignored with --load)
cargo run --release -- --seed 42 # seeded sim (reproducible headless; the GUI is wall-clock paced, see docs)
cargo run --release -- --species-threshold 1.0 # override the NEAT compatibility threshold (GUI or headless)
cargo run --release -- --script tours/demo.json # scripted tour with egui-aware screenshots
cargo run --release -- --screenshot # legacy fixed tour (camera only, no panels)
# Headless (no window). Ticks are relative to the starting tick, so --load + --headless resumes.
cargo run --release -- --headless 1000 --seed 42 # run 1000 ticks, print a summary at the end; same seed, same run
cargo run --release -- --headless 1000 --speed 20 # ticks per headless frame (default 10); runs as fast as the CPU allows regardless
cargo run --release -- --headless 1000 --save-as my-world # write sessions/my-world/save.json at the end
cargo run --release -- --headless 1000 --dump-history h.csv # 1 Hz population history for the whole run as CSV
scripts/attractor_audit.sh docs/audits/$(date +%F)-attractor-audit # 8 seeds x 2 runs x 15k ticks; summarise with scripts/attractor_audit_summary.py
cargo run --release -- --headless 1000 --species-threshold 1.5 # same override, applied identically in headless
# Tuning overrides, GUI or headless, each one SimConfig field: --bite-fraction F, --bite-reach R, --mouthless-bite B, --kill-transfer-animal K, --kill-transfer-plant K (--kill-transfer K sets both), --strike-cost W, --photo-drag D, --leaf-capacity C, --founder-diet-spread S,
# --animal-efficiency M (0 = nobody can live by hunting), --diet-exponent X (digestion curve exponent, at least 1, default 2), --max-energy E, --max-food-density D, --population-ceiling N,
# --water-vegetation M (multiplier on shallow-water vegetation capacity, default 0; above 0 shallow water is also a founding biome)
EXTRA_ARGS="--bite-fraction 0.2" scripts/attractor_audit.sh docs/audits/<dir> # audit with overrides, recorded in README.txtCLAU_WORKERS=<n> caps the compute thread pool (default 6) in both modes. --help prints every flag. An unknown flag, a missing or malformed value, or a repeated flag prints the usage and exits with status 2 before any window opens.
Requires Rust (the version pinned in rust-toolchain.toml, installed by rustup automatically) and a GPU with Metal / Vulkan / DX12 support.
scripts/setup.sh # install the git hooks (needs lefthook: brew install lefthook)
scripts/check.sh # queue and link checks, format check, clippy with warnings denied, tests; same gates as CI
scripts/smoke.sh # release build plus a short headless run, as CI runs itThe toolchain is pinned in rust-toolchain.toml; rustup installs it on first use. What is checked, where, and why is in docs/QUALITY.md.
| Key | Action |
|---|---|
| WASD / Arrows | Pan camera |
| Q / E or - / + or Scroll | Zoom |
| Right / middle drag, or Shift+left drag | Pan camera |
| Left click | Select organism (inspect panel) |
| F | Focus camera on selected organism |
| , / . | Cycle through living members of the selected organism's species |
| R | Select a random living organism |
| Space | Pause / unpause |
| [ / ] | Slow down / speed up (0.125× to 16×) |
| M | Cycle minimap mode (normal / heatmap / species range) |
| Shift+M | Hide / show minimap |
| T | Toggle trail for selected organism |
| X / I / V | Asteroid / Ice age / Volcano |
| B / N / J | Solar bloom / Nutrient rain / Cambrian spark |
| Shift+S | Screenshot |
| F5 | Save world |
| 1 to 6 | Jump to a right-panel tab |
The right-side panel has tabs for Inspect, Phylo, Graphs, Chronicle, Events, and Help.
- docs/FEATURES.md — one-liner list of everything the simulation does
- docs/ARCHITECTURE.md — how the code is organised, what runs when, where to find things
- docs/DECISIONS.md — the non-obvious design choices and their tradeoffs
- docs/ROADMAP.md — what's next, ongoing concerns, backlog
- docs/design/ — detailed design docs for bigger features
- TODO.md — concrete deferred work; review/ — code review ledgers and the review backlog. Process in docket/TODO_GUIDE.md and docket/CODE_REVIEW_GUIDE.md
Built collaboratively by Jonathan Hitchcock and Claude Code (Anthropic's Claude, various versions).
MIT