bones-ai · hellcatjack · Dec 8, 2025 · Dec 8, 2025 · Dec 8, 2025 · Dec 9, 2025
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,6 @@
+/target
+**/*.rs.bk
+*.pdb
+*.log
+.DS_Store
+.vscode/
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -22,3 +22,5 @@ rand = "0.8.5"
 bevy_pancam = "0.9.0"
 bevy_egui = "0.21.0"
 kd-tree = "0.5.1"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
diff --git a/README.md b/README.md
@@ -1,31 +1,81 @@
-# Ant Colony Simulation
-This is an ant colony simulation, it internally uses kdtree and query caching, it's able to handle about 5k ants on the cpu.
+# Rust Ant Colony Simulation
 
+A high-performance ant colony simulation written in Rust using the [Bevy](https://bevyengine.org/) engine. This simulation demonstrates emergent behavior where ants find optimal paths between their nest and food sources using pheromone trails.
 
-Built with [Rust](https://www.rust-lang.org/) and [Bevy](https://bevyengine.org/) game engine
+![screenshot](assets/demo.png)
 
-![screenshot](/screenshot.png)
+## Features
 
-# Demo
-Here's the entire timelapse of the AI learning to drive
+- **High Performance**: Capable of simulating thousands of ants efficiently using spatial hashing and KD-Trees.
+- **Emergent Behavior**: Ants follow simple local rules to form complex global pathfinding networks.
+- **Smart Navigation**: Ants utilize a multi-sensor array including a rear sensor to climb pheromone gradients accurately to find the source.
+- **Real-time Tuning**: Adjust simulation parameters on the fly without restarting.
+- **Interactive UI**: Control visuals and simulation settings via a GUI.
 
-[![youtube](https://img.youtube.com/vi/98pUSZAM_7M/0.jpg)](https://youtu.be/98pUSZAM_7M)
+## How to Run (Windows)
 
-# Timelapses with Approach 1
-[![youtube](https://img.youtube.com/vi/5xdfTJBMnwI/0.jpg)](https://youtu.be/5xdfTJBMnwI)
+**Recommended Method:**
+Use the provided PowerShell script to run the project. this avoids common "file in use" / locking errors during compilation on Windows by building in a temporary directory.
 
-
-## Usage
-- Clone the repo
-```bash
-git clone git@github.com:bones-ai/rust-ants-colony-simulation.git
-cd rust-ants-colony-simulation
+```powershell
+.\run_safe.ps1
 ```
-- Run the simulation
+
+**Standard Method:**
 ```bash
 cargo run --release
 ```
+*Note: If you encounter linking errors or "file used by another process" errors, please use the `run_safe.ps1` script.*
+
+## Controls & Shortcuts
+
+### Keyboard Shortcuts
+| Key | Action |
+| --- | --- |
+| **Space** | Pause/Resume Simulation |
+| **TAB** | Toggle Settings Menu (Open/Close UI) |
+| **H** | Toggle Home Pheromone Visibility |
+| **F** | Toggle Food Pheromone Visibility |
+| **P** | Toggle Debug Paths (Sensor lines & Radius) |
+| **A** | Toggle Ant Visibility |
+| **-** | Reduce Speed (Limit FPS: 60 -> 30) |
+| **=** | Increase Speed (Unlimited FPS) |
+| **ESC**| Exit Simulation |
+
+### Mouse Controls
+- **Left Click**: Use selected Editor Tool (Draw Wall, Place Food, etc.)
+- **Right / Middle Click + Drag**: Pan Camera
+
+### UI Parameters (Press TAB)
+You can tweak these values in real-time to see how they affect the colony's behavior:
+
+- **Env Ph Decay**: How fast pheromones on the ground evaporate.
+- **Ant Ph Decay**: How fast the pheromone strength carried by an ant decays.
+- **Sensor Dist**: How far ahead an ant looks for pheromones.
+- **Sensor Angle**: The width of the ant's sensing field.
+- **Randomness**: The amount of random jitter in ant movement.
+- **Update Interval**: How often ants make steering decisions.
+- **Max Pheromone**: Cap for pheromone accumulation. Determines when trails turn "Deep Red/Blue".
+
+### Map Editor (Toolbar at Bottom)
+The simulation includes a built-in map editor to interact with the environment:
+- **Draw Wall**: Paint obstacles that ants must navigate around. Supports continuous drawing.
+- **Eraser**: Remove walls. Supports continuous erasing.
+- **Place Food**: Click to spawn a food source. Each food source contains 1000 units of food.
+- **Remove Food**: Click near a food source to remove it.
+
+**Note:** The simulation starts with **No Food**. You must place food using the editor to start the foraging process.
+
+### Reset
+- **Reset Simulation**: Clears the map, respawns ants, and resets pheromones. Note that placed food and walls persist (or cleared? Check reset logic).
+
+## Configuration
+The initial static configuration constants are located in `src/configs.rs`. However, many of these can now be overridden at runtime via the UI.
+Settings can be saved to `user_config.json` via the "Save Config" button and are automatically loaded on startup.
+
+## Assets
+Original assets located in `assets/`.
+processed sprites sheets are in `assets/processed/`.
 
-## Configurations
-- The project config file is located at `src/configs.rs`
-- If all ants aren't forming a single trail even after a long time, try increasing `ANT_INITIAL_PH_STRENGTH` in the configs to a greater value (exmaple: `40.0`)
+## License
+MIT
diff --git a/assets/ant.png b/assets/ant.png
diff --git a/assets/ant_with_food.png b/assets/ant_with_food.png
diff --git a/assets/demo.png b/assets/demo.png
diff --git a/assets/food.png b/assets/food.png
diff --git a/assets/nest.png b/assets/nest.png
diff --git a/assets/processed/ant_sheet_centered.png b/assets/processed/ant_sheet_centered.png
diff --git a/assets/processed/ant_with_food_sheet_centered.png b/assets/processed/ant_with_food_sheet_centered.png
diff --git a/run_safe.ps1 b/run_safe.ps1
@@ -0,0 +1,3 @@
+$env:CARGO_TARGET_DIR = "$env:TEMP\rust-ants-colony-target"
+Write-Host "Building in temporary directory: $env:CARGO_TARGET_DIR"
+cargo run --release
diff --git a/screenshot.png b/screenshot.png