From 2269f26f9fa80b95d7486182bf2650550f564663 Mon Sep 17 00:00:00 2001 From: Jared Miller Date: Wed, 11 Mar 2026 17:49:22 -0400 Subject: [PATCH] Update CLAUDE.md with sand physics architecture --- CLAUDE.md | 62 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 43 insertions(+), 19 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 34ddbb5..50c1cb2 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). +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. ## stack @@ -24,23 +24,24 @@ all simulation logic runs on the GPU via ping-pong render targets. no JS-side si ### 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 +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 +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) ### 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]` +- texture 1: `[personality, cargoMaterialId, 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) +- R: material ID (0-255), maps to MaterialRegistry entry - G: scentToHome - B: scentToFood - A: repellent pheromone @@ -50,27 +51,50 @@ all simulation logic runs on the GPU via ping-pong render targets. no JS-side si **ant presence** — RGBA Float32 (worldSize x worldSize), cleared each frame. stub for future ant-ant spatial interaction. -### bit layout (world.R) +### material system -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) +`src/materials/` defines a data-driven material registry. adding a new material requires only a registry entry — no shader changes needed. + +- `MaterialRegistry` — 6 built-in materials (ids 0-5): air, sand, dirt, rock, food, home +- behavior types: `BEHAVIOR_POWDER` (0), `BEHAVIOR_LIQUID` (1), `BEHAVIOR_GAS` (2), `BEHAVIOR_SOLID` (3) +- each material has: id, name, behavior, density, hardness, angleOfRepose, color +- lookup textures (256x1 Float RGBA) uploaded as uniforms to shaders: + - properties texture: `[behavior, density, hardness, angleOfRepose]` per row + - colors texture: `[r, g, b, a]` per row +- material IDs defined in `src/constants.ts` (MAT_AIR through MAT_HOME) + +### sand physics + +Margolus neighborhood cellular automata runs as the first render pass each frame. + +- world is divided into 2x2 blocks; block offset alternates each frame between (0,0) and (1,1) +- within each block, cells with `BEHAVIOR_POWDER` fall downward and slide diagonally, swapping with lighter materials +- 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) ### 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/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/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/worldBlur.frag` — per-channel pheromone diffusion/decay -- `src/shaders/world.frag` — cell metadata bit preservation + pheromone merging +- `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 ## planning docs - `REALISM-IDEAS.md` — research-backed features for more realistic ant behavior - `INFRASTRUCTURE.md` — data structure analysis mapping features to GPU infrastructure layers +- `docs/plans/2026-03-11-ant-farm-sand-physics-design.md` — sand physics design +- `docs/plans/2026-03-11-ant-farm-implementation.md` — ant farm implementation plan ## shader files