rusty_boids

Just an experimental boid simulation project to practice Rust, Bevy and using Claude Code. And because boids are fun!

Overview

This project does something similar to Craig Reynolds' boids algorithm for simulating flocking behavior. It consists of:

• boid_sim - Core simulation library with spatial indexing and parallel processing
• boid_graphics_2d - 2D visualization using Piston
• boid_graphics_bevy - 3D visualization using Bevy

Building

# Build all crates
cargo build

# Build in release mode (recommended for running simulations)
cargo build --release

Running

The main application provides an interactive menu to select the visualization mode:

cargo run --release

Use arrow keys to navigate, Enter to select, or press 1-2 for quick selection. Press q or Esc to quit.

Command-Line Options

You can skip the interactive menu by specifying the graphics mode directly:

# Run 2D visualization (Piston)
cargo run --release -- -G 2d

# Run 3D visualization (Bevy)
cargo run --release -- -G 3d

Option	Description
-G, --graphics <MODE>	Graphics mode: 2d (Piston) or 3d (Bevy)

Running Individual Crates

You can also run the visualization crates directly:

# Run 2D visualization
cargo run -p boid_graphics_2d --release

# Run 3D Bevy visualization
cargo run -p boid_graphics_bevy --release

3D Visualization Controls

Control	Action
W/S	Move camera forward/backward
A/D	Strafe camera left/right
Q/E	Move camera down/up
Right-click + drag	Rotate camera

The UI panel on the left allows you to adjust simulation parameters in real-time. The Display tab contains toggles for showing/hiding the map boundary wireframes.

Testing

# Run all tests
cargo test

# Run tests for a specific crate
cargo test -p boid_sim

Development Tools

Code Coverage

Install and run code coverage with cargo-llvm-cov:

# Install
cargo install cargo-llvm-cov

# Generate coverage report
cargo llvm-cov

# Generate HTML report
cargo llvm-cov --html
open target/llvm-cov/html/index.html

Benchmarks

The project uses Criterion for benchmarking.

# Run benchmarks
cargo bench -p boid_sim

# Benchmark reports are generated in target/criterion/

Flame Graphs

Generate flame graphs with cargo-flamegraph for performance profiling.

# Install
cargo install flamegraph

# Profile the benchmark
cargo flamegraph --bench simulation -p boid_sim -- "10000 boids, 100 ticks"

# Profile a binary (e.g., 2D visualization)
cargo flamegraph -p boid_graphics_2d

# Output is saved to flamegraph.svg in the current directory