ants/CLAUDE.md

ants-simulation

GPU-accelerated ant colony simulation. ants navigate via pheromone trails, all computed in GLSL fragment shaders rendered to offscreen textures. uses WebGL2 features (MRT, GLSL3).

stack

• three.js (0.173) — WebGL2 renderer, render targets, MRT, shader materials
• lil-gui — runtime parameter tweaking
• vite — dev server and build
• biome — lint + format
• bun — runtime, test runner, package manager
• typescript

commands

• just check — lint, typecheck, test (the gate for all work)
• bun run dev — start dev server
• bun run build — production build to build/
• bun test — run tests

architecture

all simulation logic runs on the GPU via ping-pong render targets. no JS-side simulation loop — Renderer.ts orchestrates render passes and manages all WebGLRenderTargets.

render pipeline (per frame)

1. WorldBlurScene — diffuse + decay pheromones (3 channels: toHome, toFood, repellent, each with independent blur radius and decay rate)
2. clear antsPresenceRenderTarget (ant-ant spatial queries, stub)
3. AntsComputeScene — per-ant state via MRT (writes 2 textures simultaneously)
4. AntsDiscretizeScene — maps continuous ant positions to discrete world grid cells
5. WorldComputeScene — merges ant deposits into world pheromone grid
6. ColonyStats — CPU readback of ant texture, computes aggregate stats (foragerRatio), feeds back as uniforms
7. DrawScene — user painting (food, home, obstacles, erase)
8. ScreenScene — final composited output with camera controls

GPU textures

ant state — 2 RGBA Float32 textures per ping-pong target (MRT, count: 2):

• texture 0: [pos.x, pos.y, angle, packed(storage << 1 | isCarrying)]
• texture 1: [personality, cargoQuality, pathIntDx, pathIntDy]

world state — RGBA Float32 (worldSize x worldSize):

• R: packed cell metadata (bits 0-2: food/home/obstacle, bits 3-5: terrain type, bits 6-13: food quality)
• G: scentToHome
• B: scentToFood
• A: repellent pheromone

discrete ants — RGBA UnsignedByte (worldSize x worldSize):

• R: carrying ant scent deposit, G: non-carrying ant scent deposit, B: cell cleared flag, A: 1

ant presence — RGBA Float32 (worldSize x worldSize), cleared each frame. stub for future ant-ant spatial interaction.

bit layout (world.R)

defined in src/constants.ts, shared between TS and GLSL via defines:

• bits 0-2: cell flags (food, home, obstacle)
• bits 3-5: terrain type (0-7, reserved for substrate-dependent decay)
• bits 6-13: food quality (0-255, reserved for quality-dependent pheromone modulation)

key files

• src/Renderer.ts — render target creation, pass orchestration, MRT setup, colony stats readback
• src/Config.ts — simulation parameters (per-channel pheromone configs)
• src/constants.ts — cell metadata bit layout (single source of truth for TS + GLSL)
• src/ColonyStats.ts — CPU readback of ant texture for colony-level aggregate stats
• src/shaders/antsCompute.frag — ant behavior + MRT output (2 render targets via layout qualifiers)
• src/shaders/worldBlur.frag — per-channel pheromone diffusion/decay
• src/shaders/world.frag — cell metadata bit preservation + pheromone merging

planning docs

• REALISM-IDEAS.md — research-backed features for more realistic ant behavior
• INFRASTRUCTURE.md — data structure analysis mapping features to GPU infrastructure layers

shader files

in src/shaders/. each scene has a matched .vert/.frag pair. loaded as raw strings by the vite glsl plugin in vite.config.ts. all shaders use GLSL3 (#version 300 es via three.js glslVersion: THREE.GLSL3).

textures

in public/textures/ — ant.png and food.png sprites.