evo-1

evo-1 is a Rust evolutionary simulation with two supported runtimes: a native headless runner for experiments and a WebAssembly browser app for interactive visualization.

It is the first project in the TRE evo series: a selection-field ecology sandbox for watching agents compete, feed, reproduce, and diverge under visible selection pressure.

What It Contains

• ECS-based simulation state using hecs.
• Spatial-grid lookups for nearby agents and resources.
• Genetic traits, reproduction, resource consumption, death, and predator/prey interactions.
• Native headless execution with Rayon-enabled resource updates.
• Browser execution with WebGPU rendering, WebGL/Canvas2D fallbacks, and optional wasm-bindgen-rayon worker-pool support.
• Graphviz architecture diagrams committed as source .dot files and rendered PNGs.

Quick Start

Prerequisites

• Rust stable for native builds and standard checks.
• wasm32-unknown-unknown for the stable WASM check.
• nightly-2024-08-02 with rust-src for the threaded WASM build.
• wasm-pack 0.13.1 for browser packages.
• Graphviz for diagram rendering.

rustup target add wasm32-unknown-unknown
rustup toolchain install nightly-2024-08-02 --component rust-src --target wasm32-unknown-unknown
cargo install wasm-pack --locked --version 0.13.1
# Install Graphviz with your package manager; on macOS:
brew install graphviz

Browser App

./scripts/build-wasm.sh
python3 server.py

Open http://127.0.0.1:8000.

server.py binds to 127.0.0.1 and sends the COOP/COEP headers required for SharedArrayBuffer and wasm-bindgen-rayon.

Cloudflare Pages

The intended production target is https://evo-1.tre.systems on a Cloudflare Pages project named evo-1.

Build the deployable static bundle:

./scripts/build-pages.sh

Deploy it directly with Wrangler:

npx wrangler pages deploy dist --project-name evo-1

For the Pages dashboard/Git integration, use ./scripts/build-pages.sh as the build command and dist as the build output directory.

Headless Runner

cargo run --release --locked --bin headless -- 2.0 20 500 500 3000 2000

The positional arguments are:

duration_minutes speed_multiplier initial_agents initial_resources max_agents max_resources [--seed seed]

Convenience scripts are available:

./run_simulation.sh
./run_simulation.sh 1.0 10 200 200 1000 800 202
./run_scenarios.sh
./run_scenarios.sh quick_test

run_scenarios.sh is the source of truth for the named scenario catalog. Named scenarios carry fixed seeds so ecology changes can be compared across runs.

Local Checks

Run the full local check suite before pushing code changes:

./scripts/check.sh

It runs formatting, clippy, tests, stable WASM checking, the pinned threaded-WASM check, and Graphviz diagram validation.

Refresh rendered diagrams after editing .dot files:

node scripts/render-diagrams.mjs
node scripts/check-diagrams.mjs

Documentation

• Architecture and Patterns - runtime boundaries, module map, frame pipeline, and recurring implementation patterns.
• Product Vision - original ambition, research notes, and iteration roadmap.
• API Reference - public Rust, WASM, and headless interfaces.
• Architecture Diagrams - Graphviz sources, rendered PNGs, conventions, and render commands.
• Deployment - Cloudflare Pages build, headers, and evo-1.tre.systems setup.
• Maintenance Notes - required checks, browser smoke test, and deployment status.
• Documentation Index - compact docs map.

Browser Requirements

The browser app needs a modern browser with WebAssembly and WebGPU. It falls back to WebGL or Canvas2D when WebGPU is unavailable. Web Workers and SharedArrayBuffer require cross-origin isolation; use python3 server.py locally so those headers are present.

License

MIT License. See LICENSE.