digital-AL

An Agent-Based Artificial Life Simulation built in Rust. It utilizes a strict Data-Oriented Design (DOD) via Bevy ECS to simulate thousands of biological entities evolving inside a highly optimized environment.

Architecture & Biology

For complete technical details, biological specifications, and system architecture, please read the Official Documentation or jump straight to specific topics:

• Getting Started & Installation
• Distributed UDP Architecture & Toroidal Space
• Digital Biology (Genetics, Neural Networks, Mutations, Biology of Death)

---

Quick Start

1. The Headless Trainer (UDP Server)

Executes the simulation at maximum CPU speed to train Neural Networks via evolutionary algorithms. The Trainer runs purely in memory and broadcasts the universe state over a highly compressed UDP Bincode stream.

# Run in Uncapped CPU Mode (Max Speed)
cargo run --release --bin al_trainer -- --uncapped-mode

# Run with custom parameters
cargo run --release --bin al_trainer -- --target-tps 120 --spawn 500

Advanced Flags

• -u, --uncapped-mode: Run without a TPS limit (Maximum CPU load).
• -t, --target-tps <NUM>: Set a specific TPS limit to prevent thermal throttling (Default: 60).
• -s, --spawn <NUM>: Set the number of initial entities to spawn. Required if starting a new universe (no saves/checkpoint.bin is present). If a checkpoint is found, this flag is ignored.
• -i, --island-manager: Enable Rapier2D's automatic island manager for multithreading.
• --toroidal: Enable Toroidal Space (Pac-Man effect) where entities wrap around the screen edges. This uses $O(\log N)$ Ghost Entities mapping.
• --mass-cap <FLOAT>: Set a maximum limit for Entity Mass/Radius. 0.0 means infinite (Default: 0.0).
• --width <FLOAT>: Set a custom space width for the simulation boundaries (Default: 800.0).
• --height <FLOAT>: Set a custom space height for the simulation boundaries (Default: 600.0).

Warning

Data Loss Risk: While the trainer is running, you must press Ctrl+C to gracefully stop it. This triggers The Big Crunch, saving the entire ECS world state to saves/checkpoint.bin. Force-closing the window will permanently destroy evolutionary progress.

2. The Visualizer (UDP Thin-Client)

The visualizer acts as a Thin-Client. It listens to 127.0.0.1:8888 and decodes the UDP Bincode stream in real-time, rendering the environment at 60 FPS using Macroquad.

cargo run --release --bin al_visualizer

Thin-Client Controls:

• WASD or Arrow Keys: Pan the camera viewport.
• Mouse Drag (Middle or Right Mouse Button): Pan the camera viewport dynamically.
• Mouse Scroll Wheel: Smoothly zoom the viewport centered on your cursor coordinates.
• God Mode Physical Intervention: Check "Enable Physical Intervention (God Mode)" in the HUD window, then Left-click and Drag any cell or food orb to move it. Release to fling it under active physics!

Tip

Distributed Ready: Because they communicate over UDP, you can run al_trainer and al_visualizer completely independently, even simultaneously on the same machine without any I/O collisions, or on entirely different machines across a Local Area Network.

---

Environmental Constraints & Security

The Sandbox

Entities are designed to "consume" and corrupt binary files, simulating digestion and entropy. This occurs entirely within the host system's sandbox_env/ folder and is strictly containerized using absolute path resolution to prevent Path Traversal Attacks.

Biology of Death (The Prion Penalty)

When an AL dies of old age, it drops a highly energetic DOM Particle (Dissolved Organic Matter). Scavenging these particles yields massive calories but heavily corrupts the offspring's DNA (prion_load), triggering up to a 50% mutation penalty in future generations.

The Great Extinction Event

If all food is wiped out (e.g., an Antivirus clears the Sandbox), the ecosystem enters an Extinction Event. All organisms receive an instant $100%$ Adrenaline spike, forcing them into a state of panic, rapid movement, and desperate reproduction (Parthenogenesis) to ensure survival of the fittest before starvation consumes the universe.