71 lines
3 KiB
Markdown
71 lines
3 KiB
Markdown
# ants-simulation
|
|
|
|
GPU-accelerated ant colony simulation built with three.js and GLSL shaders. All simulation logic runs entirely on the GPU — no JavaScript-side physics loop.
|
|
|
|
**[Live demo](https://strandedkitty.github.io/ants-simulation/)**
|
|
|
|
|
|
|
|
## How it works
|
|
|
|
Ants emit two types of pheromones: **to-home** (left by ants searching for food) and **to-food** (left by ants carrying food). Ants searching for food follow to-food trails; ants carrying food follow to-home trails.
|
|
|
|
Each ant carries a limited pheromone inventory. Picking up food or reaching home refills the inventory; each pheromone deposit drains it. This prevents ants that wandered too far from leaving misleading trails — their pheromone runs out, so their trails naturally fade.
|
|
|
|
Pheromone trails diffuse across neighboring cells and decay over time. The simulation also supports a **repellent pheromone** channel (independent decay rate and diffusion radius) for future use.
|
|
|
|
### Controls
|
|
|
|
- **Q** — paint home
|
|
- **W** — paint food
|
|
- **E** — paint obstacles
|
|
- **R** — erase
|
|
- **Mouse wheel** — zoom
|
|
- **Click + drag** — pan
|
|
|
|
## Architecture
|
|
|
|
The simulation runs as a chain of GPU render passes using ping-pong render targets:
|
|
|
|
1. **Pheromone blur/decay** — diffuse and evaporate all pheromone channels
|
|
2. **Ant compute** — update each ant's position, direction, and carrying state (MRT: writes primary + extended state simultaneously)
|
|
3. **Discretize** — map continuous ant positions onto the world grid
|
|
4. **World update** — merge ant deposits into the pheromone grid
|
|
5. **Colony stats** — CPU readback of aggregate colony state (forager ratio)
|
|
6. **Draw** — user painting input
|
|
7. **Screen** — final composited output
|
|
|
|
### Per-ant state (2 textures via MRT)
|
|
|
|
| Texture | R | G | B | A |
|
|
| -------- | ----------- | ------------ | --------- | --------------------------- |
|
|
| Primary | pos.x | pos.y | angle | packed(storage, isCarrying) |
|
|
| Extended | personality | cargoQuality | pathIntDx | pathIntDy |
|
|
|
|
### World state (RGBA Float32)
|
|
|
|
| Channel | Data |
|
|
| ------- | ----------------------------------------------------------------------------- |
|
|
| R | packed cell metadata (food/home/obstacle flags + terrain type + food quality) |
|
|
| G | to-home pheromone |
|
|
| B | to-food pheromone |
|
|
| A | repellent pheromone |
|
|
|
|
## Development
|
|
|
|
Requires [bun](https://bun.sh).
|
|
|
|
```sh
|
|
bun install
|
|
bun run dev # start dev server
|
|
just check # lint + typecheck + test
|
|
```
|
|
|
|
## References
|
|
|
|
- [Ant colony simulations (softology)](https://softologyblog.wordpress.com/2020/03/21/ant-colony-simulations/)
|
|
- [AntSimulator (johnBuffer)](https://github.com/johnBuffer/AntSimulator)
|
|
|
|
## License
|
|
|
|
MIT
|