From 64d7bf64372f1bb65f6169993d8661b457724f89 Mon Sep 17 00:00:00 2001 From: Jared Miller Date: Wed, 11 Mar 2026 20:59:15 -0400 Subject: [PATCH] Update CLAUDE.md for ant behavior overhaul Documents the budget pool activation model, priority-stack brain, ant physics (gravity/collision/surface), unified brush spawning, new config keys (antsStartCount, antBudget, seedWorld), stats overlay active/budget format, worldInit test, and screenWorld.frag color variation. --- CLAUDE.md | 41 ++++++++++++++++++++++++++++++----------- 1 file changed, 30 insertions(+), 11 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 50c1cb2..ee5e59e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,6 @@ # 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). side-view ant farm with sand/powder physics and material-based world. +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). side-view ant farm with sand/powder physics and material-based world. ants use a fixed budget pool with probabilistic activation; behavior is driven by a priority-stack brain (fall → deposit → navigate → forage → dig → wander). ## stack @@ -27,16 +27,16 @@ all simulation logic runs on the GPU via ping-pong render targets. no JS-side si 1. `SandPhysicsScene` — Margolus block CA for sand/powder physics 2. `WorldBlurScene` — diffuse + decay pheromones (3 channels: toHome, toFood, repellent, blocked by solid cells) 3. clear `antsPresenceRenderTarget` (ant-ant spatial queries, stub) -4. `AntsComputeScene` — per-ant state via MRT (writes 2 textures simultaneously), material-aware digging +4. `AntsComputeScene` — per-ant state via MRT (writes 2 textures simultaneously); gravity pass runs first (ants fall through air), then priority-stack brain for active ants; handles collision displacement out of solid cells 5. `AntsDiscretizeScene` — maps continuous ant positions to discrete world grid cells 6. `WorldComputeScene` — merges ant deposits into world pheromone grid -7. `ColonyStats` — CPU readback of ant texture, computes aggregate stats (foragerRatio), feeds back as uniforms -8. `DrawScene` — user painting with material palette -9. `ScreenScene` — final composited output with side/top camera views (V to toggle) +7. `ColonyStats` — CPU readback of ant texture, computes aggregate stats (foragerRatio, active/budget counts), feeds back as uniforms +8. `DrawScene` — user painting with material palette; brush tool also spawns ants (key: A, `BRUSH_ANTS = 999` sentinel, `uAntSpawn` uniform) +9. `ScreenScene` — final composited output with side/top camera views (V to toggle); passes ant spawn position to AntsComputeScene ### GPU textures -**ant state** — 2 RGBA Float32 textures per ping-pong target (MRT, `count: 2`): +**ant state** — 2 RGBA Float32 textures per ping-pong target (MRT, `count: 2`). texture size is `Math.ceil(Math.sqrt(antBudget))` — a fixed pool. only `antsStartCount` ants activate on init; dormant slots sit at pos=(0,0). new ants can be activated via the brush tool (probabilistic activation per frame when spawn is requested): - texture 0: `[pos.x, pos.y, angle, packed(storage << 1 | isCarrying)]` - texture 1: `[personality, cargoMaterialId, pathIntDx, pathIntDy]` @@ -72,22 +72,41 @@ Margolus neighborhood cellular automata runs as the first render pass each frame - physics pass writes back to world ping-pong target before pheromone diffusion runs - `src/sand/margolus.ts` computes the per-frame block offset (JS side, passed as uniform) +### ant physics and brain + +ants run a gravity pass before the priority stack each frame: + +- **gravity**: ants in air cells fall downward. steering logic is skipped while falling (`!isFalling` guard). +- **collision displacement**: if an ant ends up inside a solid cell, it is pushed out. +- **surface constraint**: grounded ants follow surface contours. + +the priority stack resolves behavior in order, first match wins: + +1. **fall** — handled before stack; sets `isFalling`, skips steering +2. **deposit** — drop food at home tile, or deposit carried powder on surface +3. **navigate** — pheromone-following when carrying food; upward bias when carrying powder +4. **forage** — follow food scent when empty +5. **dig** — bias toward diggable powder below surface (side-view only) +6. **wander** — fallback random movement + ### 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` — material IDs (single source of truth for TS + GLSL) -- `src/ColonyStats.ts` — CPU readback of ant texture for colony-level aggregate stats -- `src/StatsOverlay.ts` — on-screen stats display (cursor position, TPS, colony info) +- `src/Config.ts` — simulation parameters (per-channel pheromone configs); ant keys: `antsStartCount` (default 4), `antBudget` (pool size, default 512), `seedWorld` (boolean) +- `src/constants.ts` — material IDs (single source of truth for TS + GLSL); `BRUSH_ANTS = 999` sentinel for ant-spawn brush +- `src/ColonyStats.ts` — CPU readback of ant texture for colony-level aggregate stats (reports active/budget) +- `src/StatsOverlay.ts` — on-screen stats display (cursor position, TPS, colony info); ant count shown as "active / budget" +- `src/__tests__/worldInit.test.ts` — tests for world seeding (home/food placement via mulberry32 PRNG) - `src/materials/types.ts` — Material interface and BehaviorType constants - `src/materials/registry.ts` — MaterialRegistry with 6 built-in materials - `src/materials/lookupTexture.ts` — builds GPU lookup textures from registry - `src/sand/margolus.ts` — Margolus block offset calculation - `src/scenes/SandPhysicsScene.ts` — sand physics render pass -- `src/shaders/antsCompute.frag` — ant behavior + MRT output (2 render targets via layout qualifiers) +- `src/shaders/antsCompute.frag` — ant behavior + MRT output (2 render targets via layout qualifiers); gravity, priority stack, spawn activation - `src/shaders/worldBlur.frag` — per-channel pheromone diffusion/decay (solid cells block diffusion) - `src/shaders/world.frag` — material ID preservation + pheromone merging - `src/shaders/sandPhysics.frag` — Margolus block CA for powder/sand movement +- `src/shaders/screenWorld.frag` — final composite; applies per-pixel hash noise (+/-4% brightness) to material colors ## planning docs