# 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/)**

![ants collecting food](https://i.imgur.com/FeU3UvR.png)

## 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