Eidolon-Engine — 3D ECS Simulation Engine in Rust

A real-time 3D agent simulation built with Rust and Bevy 0.15, focused on utility AI, deterministic systems, and observability.

What Is This?

Eidolon-Engine is a technical portfolio project, not a game. It demonstrates how to structure a small real-time simulation around Bevy ECS, deterministic fixed-step updates, utility-based agent decisions, and inspection tooling.

The current simulation focuses on a stable behavioral loop:

Perceive -> Forage -> Harvest cargo -> Deliver to village store -> Feed/rest -> Explore

Agents do not follow scripted behavior trees. They score possible actions from local state, needs, nearby entities, and lightweight memory, then act through ECS systems that apply movement, resource harvesting, delivery, recovery, and population rules.

Current Status

The project is currently in a demo-ready simulation-core state:

Area	Status
ECS architecture	Implemented with separated engine, simulation, AI, scenarios, and observability modules
Agent lifecycle	Implemented: spawning, needs, movement, death, low-population recovery
Utility AI	Implemented: forage, deliver, rest, explore, collect fallback, idle
Resource loop	Implemented: harvest food, carry cargo, deliver to village store, feed agents from stores
Agent memory	Implemented for remembered food and return/rest locations
Scenarios	Implemented via RON scenario files and hotkey presets
Observability	Implemented: HUD, inspector, timeline, overlays, behavior log, replay scaffolding
Tests	Implemented: unit and integration regression coverage for movement, perception, foraging, population, scenarios, and deterministic RNG

Known limits:

• Pathfinding is direct steering, not navmesh/path planning.
• Non-food resources are placeholders.
• Replay and observability systems are useful, but not yet polished as a full product workflow.
• Scenario balance still needs a final tuning pass for presentation-quality demos.

Key Features

Feature	Description
ECS Architecture	Components and systems are split by domain boundaries
Utility AI	Agents rank actions dynamically from needs, perception, memory, and role bias
Stable Foraging Loop	Agents forage, harvest cargo, deliver to stores, then feed/rest
Determinism	Seeded simulation RNG and fixed timestep update flow
Scenario System	RON-backed presets for equilibrium, scarcity, island, overpopulation, and stress tests
Observability	Live inspector, event timeline, overlays, behavior logging, and replay-oriented data
Regression Tests	Focused tests lock down core behavioral loops

Quick Start

git clone https://github.com/yourname/Eidolon-Engine
cd Eidolon-Engine
cargo run --release

Controls:

• WASD + mouse: orbit camera
• Left Click: inspect entity
• F1 or I: toggle Entity Inspector
• F2 or T: toggle Event Timeline
• F3 or O: toggle Debug Overlays
• Space: pause/resume simulation
• R: restart with same seed
• N: new seed
• Number keys: switch scenario presets

Testing

cargo fmt --all -- --check
cargo test --all-features
cargo clippy --all-targets --all-features -- -D warnings

Targeted checks:

cargo test --test foraging_regression
cargo test --test movement_regression
cargo test determinism --verbose

Project Structure

Eidolon-Engine/
├── src/
│   ├── main.rs
│   ├── lib.rs
│   ├── engine/          # Window, camera, render setup, input, fixed simulation time
│   ├── simulation/      # Agents, resources, world rules, events, spatial grid
│   ├── ai/              # Utility scoring, decisions, memory, action definitions
│   ├── observability/   # HUD, inspector, timeline, behavior log, overlays, replay
│   └── scenarios/       # RON scenario loading, presets, world spawning
├── assets/
│   ├── scenarios/       # Scenario definitions
│   └── config/          # AI and simulation config
├── tests/               # Integration and regression tests
└── .agent/              # Architecture and design notes

Portfolio Context

This project is scoped to demonstrate engineering depth over feature breadth. The interesting parts are the ECS boundaries, deterministic simulation loop, observable AI decisions, and regression-tested agent behavior.

It is intended for game systems, simulation, and real-time Rust portfolio review.

Requirements

• Rust 1.78+
• Bevy 0.15
• macOS, Linux, or Windows

License

MIT. See LICENSE.