diff --git a/docs/NEST-BUILDING.md b/docs/NEST-BUILDING.md new file mode 100644 index 0000000..300c846 --- /dev/null +++ b/docs/NEST-BUILDING.md @@ -0,0 +1,244 @@ +NEST BUILDING AND COLONY ARCHITECTURE +====================================== + +research notes for informing ant farm simulation behavior. +sources cited inline. + + +INITIAL NEST FOUNDING +--------------------- + +after a mating flight, a queen sheds her wings, finds a suitable spot, and +digs a "founding chamber" -- a small cavity just big enough to tend eggs and +larvae. she seals the entrance and doesn't leave until the first workers emerge. +she feeds larvae with trophic (unfertilized) eggs laid specifically as food. + +founding chamber size: ~24 cm^2 in Camponotus fellah studies. + +what triggers digging location: queens prefer softer, more humid soil. in +shaded habitats (less dense, more humid soil), queen establishment was greater, +nest depth was greater, and excavated volume was greater. soil density and +humidity are the primary abiotic factors. + +[eLife: colony demographics shape nest construction] +[Wiley: soil density and humidity in leaf-cutting ant queens] + + +TUNNEL ARCHITECTURE +------------------- + +shape transition: ants first excavate a circular chamber. once it reaches a +critical area, buds appear along the chamber wall and tunnels branch off. this +is a density-driven phase transition: + + high ant density along wall = uniform digging (chamber grows) + low ant density per unit wall = localized instabilities = tunnels branch + +this is the key insight from Toffin et al. (PNAS 2009). + +tunnel descent angle: ants dig at roughly the angle of repose of the substrate +(~40 degrees for typical sand). they don't exceed this -- "if I'm a digger, my +digging technique is going to align with the laws of physics, otherwise my +tunnels collapse and I die." (Caltech/PNAS 2021) + +branching complexity increases with population size. new tunnels branch from +existing tunnel walls, not just from chambers. + +moisture influence: tunnels extend vertically until hitting either the surface +or a soil layer with sharply increasing water content. ants excavate more in +moist soil but stop ~12mm above water-saturated layers. + +gravity's role: gravity promotes vertical motion and accounts for the formation +of ellipsoidal chambers and vertical tunnels. it acts as a "template" for +tunnel direction. + +[PNAS: shape transition during nest digging in ants (Toffin 2009)] +[PLOS ONE: role of colony size on tunnel branching] +[PNAS: unearthing real-time 3D ant tunneling mechanics (2021)] +[Nature Sci Reports: ant nest architecture shaped by temperature] +[PMC: soil moisture and excavation behaviour] + + +DIGGING MECHANICS +----------------- + +ants carry particles one at a time in their mandibles. they prefer smaller +grains. most effective excavation occurs when grains are small enough to carry. + +why tunnels don't collapse: intergranular forces decrease around ant tunnels +due to "granular arching" -- force chains in the soil redistribute around the +tunnel, forming natural arches. any grain an ant picks from the tunnel face is +already under low stress due to this force relaxation. ants achieve stability +without reinforcements purely by benefiting from physics. the arch structures +have a greater diameter than the tunnel itself. + +digging pattern: piecewise linear tunnel segments. ants dig in short straight +stretches, then change direction slightly. + +excavated material deposition: ants carry grains to the surface and deposit +them near the nest entrance, forming a mound/midden. in Pheidole oxyops, the +pile forms a crescent shape ~13cm from the entrance. 82% of grains stay where +dropped; 18% roll downhill. in leaf-cutter ants, soil pellets are transported +sequentially over 2m involving up to 12 workers in a relay chain. + +[PNAS: ants make efficient excavators] +[ResearchGate: sand pile formation in Dorymyrmex ants] +[PLOS ONE: sequential soil transport in leaf-cutting ants] + + +DIVISION OF LABOR IN CONSTRUCTION +---------------------------------- + +age polyethism: young ants do most of the digging. older ants forage more. + +young vs old digging style: young ants dig slanted tunnels. old ants dig +straight down. this is a form of age polyethism where age dictates not just +task likelihood but task execution style. + +emergency override: after a nest catastrophe (collapse, flooding), all ants +dig regardless of age to restore lost nest volume. + +queen's role: digs only during founding. once first workers emerge, she never +digs again. focuses exclusively on reproduction. her pheromones influence +colony-wide behavior including construction coordination. + +coordination: no central planning. workers follow chemical markers ("building +pheromone") on substrate indicating active construction zones. substrate +vibrations may also coordinate digging underground. + +[eLife: colony demographics shape nest construction] +[Springer: task allocation in ant colonies] +[Knowable Magazine: evolution of division of labor] + + +COLONY GROWTH AND NEST EXPANSION +--------------------------------- + +scaling: nest volume grows logistically to a saturation volume that scales +linearly with population size. larger colony = proportionally larger nest. + +timing: population increase is followed ~15 days later by an increase in +excavated area. nest expansion lags population growth by roughly one week. +the nest is excavated in discrete digging episodes triggered by population +increases. + +expansion pattern: three simultaneous processes: + 1. nest deepening (main shaft extends) + 2. chamber magnification (existing chambers enlarge) + 3. creation of new vertical chamber sequences (new branches) + +trigger: population crowding. track (colony population) / (excavated area). +when this exceeds a threshold, digging episode begins. + +[eLife: colony demographics shape nest construction] +[bioRxiv: colony demographics shape nest construction (preprint)] + + +ANT FARM (2D) SPECIFICS +------------------------ + +the formicarium was invented by Charles Janet (French entomologist) -- reducing +3D nest architecture to virtual 2D between two panes of glass. + +the gap between panes should match the diameter of the species' typical burrow, +so no soil layer sticks to the glass. forces all tunneling to be visible. + +climbing on glass: ants CAN walk on vertical glass surfaces. they use adhesive +pads (arolia) on legs above their center of mass (pulling) and dense tarsal +hair arrays on legs below center of mass (pushing). anti-escape coatings (PTFE, +petroleum jelly) are used on formicarium rims specifically because ants climb +glass easily. + +gravity in 2D: ants walk on the glass surface while digging in substrate +between the panes. sand/soil is subject to gravity and will collapse if not +supported. the angle-of-repose constraint still applies. + +behavioral differences: ants exhibit the same chamber-first-then-tunnel +transition, same density-driven branching, same age-based digging allocation +in 2D as 3D. the main difference is the architecture is forced planar. + +[Wikipedia: formicarium] +[AntKeepers: classic ant farm] +[PLOS ONE: on heels and toes -- how ants climb] + + +WITHOUT A QUEEN +--------------- + +survival: 3-4 months typical, up to 12 months in good conditions. + +behavioral changes: workers search for the missing queen. stress increases. +aggression increases (queen pheromones normally maintain harmony). social +organization deteriorates. + +still dig? yes. workers continue to excavate, reinforce, and maintain the nest. + +reproduction: some workers begin laying unfertilized eggs (males only). in +some species, workers engage in dominance tournaments and winners become +"pseudoqueens" with dramatically increased lifespans (7 months to 4 years). + +no new workers: colony cannot produce workers without a queen. slow decline. +no larvae also means nutrition problems since larvae help digest solid food +for the colony. + +[MisfitAnimals: how long do ants live without a queen] +[BestAntsUK: ant farm essentials -- how crucial is a queen] +[NYU: dueling ants vying to become replacement queen] + + +EMERGENT PATTERNS AND STIGMERGY +-------------------------------- + +stigmergy: indirect coordination through environmental modification. an ant's +action changes the environment, which stimulates the next ant's action. no +direct communication needed. coined by Grasse (1959) studying termites. + +building pheromone: ants deposit a pheromone on building material/substrate. +this has a limited lifetime, creating a spatially heterogeneous "topochemical +landscape." areas with fresh pheromone attract more building/digging activity. +without pheromone dynamics, no coherent structure can be built in simulations. +(Khuong et al., PNAS 2016) + +pheromone lifetime is key: controls the growth and form of nest architecture. + short lifetime = more localized construction (tight tunnels) + long lifetime = more diffuse construction + +template + stigmergy hybrid: two interactions coordinate building: + 1. stigmergic: building pheromone on substrate + 2. template-based: ants use body size as cue to control tunnel/chamber + dimensions (e.g. roof height) + +density-driven transitions (restated): high local ant density = chamber +expansion. low local density = tunnel formation. the chamber-to-tunnel +transition emerges from this simple density rule. + +simple rules produce complex nests. the combination of: + a. building pheromone deposition/decay + b. local density sensing + c. gravity alignment + d. body-size templates +produces the full range of observed nest architectures. no ant has a blueprint. + +[PNAS: stigmergic construction and topochemical information (Khuong 2016)] +[Wikipedia: stigmergy] +[PNAS: shape transition during nest digging (Toffin 2009)] +[eLife/PMC: emergent regulation of ant foraging] + + +SIMULATION PARAMETERS (DISTILLED) +---------------------------------- + +key values that map to tunable config/uniforms: + + tunnel descent angle ~40 degrees (angle of repose of substrate) + chamber-tunnel transition ant density per unit wall drops below threshold + building pheromone decay controls architecture compactness + nest volume / population linear scaling, ~24 cm^2 per founding queen + young ant digging bias slanted tunnels vs vertical (age polyethism) + material deposit location near surface entrance, biased away from it + grain removal rate one grain per trip, prefer lighter grains + expansion trigger population / excavated area exceeds threshold + moisture preference dig toward moist, stop before saturated + +the ant presence texture (already exists as stub) combined with a digging +pheromone channel would give us the chamber-then-tunnel transition for free. diff --git a/docs/plans/2026-03-11-ant-behavior-overhaul-design.md b/docs/plans/2026-03-11-ant-behavior-overhaul-design.md new file mode 100644 index 0000000..7d31140 --- /dev/null +++ b/docs/plans/2026-03-11-ant-behavior-overhaul-design.md @@ -0,0 +1,155 @@ +Ant Behavior Overhaul — Design +=============================== + +goal: fix broken ant physics, add gravity and surface movement, unify the +brush tool so everything (including ants) is droppable, establish a behavioral +priority stack, and lay groundwork for emergent nest architecture. + +reference: docs/NEST-BUILDING.md (research on real ant nest construction) + + +1. Ant Physics — Gravity and Surface Movement +---------------------------------------------- + +problem: ants float through air with no physics. they walk through sand and +rise upward forever when carrying. + +two physical rules added to antsCompute.frag: + +GRAVITY: if the cell below an ant is air, the ant falls one cell downward. +falling ants don't steer — they just drop. this makes dropped ants tumble +from wherever you place them. + +SURFACE CONSTRAINT: ants can only walk (apply their steering angle) when +they're adjacent to a solid material cell. "adjacent" means any of the 4 +cardinal neighbors is non-air. if an ant is on top of sand, next to a tunnel +wall, or on the world boundary — it can walk. if it's in open air with nothing +nearby, it falls. + +ANT-SAND COLLISION: sand physics runs first (pass 1), ants compute runs later +(pass 4). if falling sand fills an ant's cell between frames, the ant gets +displaced to the nearest air cell (check up first, then sideways). sand always +wins, ants get squeezed out. this prevents deadlock where an ant and a grain +occupy the same cell. + +MOVEMENT THROUGH MATERIALS: ants treat all non-air materials as solid walls +they can't walk into, UNLESS they're actively digging (picking up a powder +cell they're facing). walking into rock, food, or home blocks movement. + + +2. Unified Brush — Everything is Droppable +------------------------------------------- + +problem: ants are created at init time only. materials and ants use separate +systems. want Sandboxels-style "pick element, drop it." + +the brush palette becomes a single list of elements: erase, sand, dirt, rock, +food, home, ants. all use the same brush size slider. brush size = number of +cells filled per click/drag frame. + +FOR MATERIALS (sand, dirt, rock, food, home, erase): works like today. +draw.frag writes the material ID into world cells within the brush radius. + +FOR ANTS: clicking writes to a separate "ant spawn" buffer — a small queue of +(x, y) positions. each frame, the ant compute pass checks this buffer and +activates inactive ants (those still at pos == vec2(0)) at those positions. +brush size N = activate N ants at/near the click position, randomly scattered +within the brush radius. + +ANT BUDGET: a config value antBudget (default 512) sets the texture size. the +starting count antsStartCount (default 4) determines how many activate on init. +drawing ants activates more from the pool. if the pool is full, drawing does +nothing. + +GUI CHANGES: +- material palette gets an "ants" entry with keybind (A) +- brush radius slider controls all elements +- antsStartCount replaces the 2^N slider — plain number (0-64) +- antBudget is not in the main GUI (advanced/hidden config) + +SEED TOGGLE: a checkbox "seed home + food" (default on). when on, world init +places one home and one food at random surface positions. when off, blank sand +and sky. lives in GUI under world section. + + +3. Ant Brain — Behavioral Drives +---------------------------------- + +PHASE A (this implementation): + +each ant has a priority stack, evaluated top to bottom each frame: + +1. FALLING — if no solid neighbor below, fall. skip all other logic. +2. CARRYING, DEPOSIT — if carrying food and at home, drop it. if carrying + sand/dirt and on the surface (air above, solid below), drop it. +3. CARRYING, NAVIGATE — if carrying food, follow toHome pheromone. if carrying + sand/dirt, bias upward toward surface. +4. NOT CARRYING, FORAGE — if food scent detected, follow toFood pheromone. +5. NOT CARRYING, DIG — if adjacent to diggable powder below the surface, pick + it up. prefer digging downward at roughly the angle of repose (~40 degrees). +6. NOT CARRYING, WANDER — random walk along surfaces. the fallback. + +SUPPRESSORS (every drive has a reason NOT to fire): +- digging suppresses when on the surface or material is too hard +- foraging suppresses when no food scent in sample range +- deposit suppresses when no solid ground below drop point +- wandering is the fallback — only fires when nothing else triggers + +WHAT GIVES ANTS PURPOSE WITHOUT A QUEEN: home marker acts as anchor. ants +forage food back to home. ants dig near home to create shelter. the home +pheromone radiates outward and gives ants a "come back here" signal. without +a home marker, ants just wander and react to whatever they're near. + +PHASE B (future — digging pheromone): +ants deposit a "dig here" scent when excavating, attracting other ants to dig +nearby. this creates the density-driven chamber-to-tunnel transition from +the nest-building research. the repellent pheromone channel (A channel) could +be repurposed or a 5th channel added. pheromone decay rate controls tunnel +compactness: short lifetime = tight tunnels, long lifetime = diffuse. + +PHASE C (future — colony dynamics): +age parameter on ants (personality field in texture 1 repurposed or extended). +young ants dig more, old ants forage more. colony growth = activating new ants +from the budget when food-delivered count exceeds a threshold. nest expansion +triggered when population/excavated-area ratio exceeds threshold. emergency +"all hands dig" mode when nest area drops below expected-per-population. + + +4. Sand Color Variation +------------------------ + +problem: sand looks flat — every cell is the same color. + +in screenWorld.frag, when rendering a non-air material, hash the cell's grid +position to produce a small color offset: + + vec3 baseColor = materialColorLookup(materialId); + float noise = hash(ivec2(gl_FragCoord.xy)) * 0.08 - 0.04; // +/-4% + baseColor += noise; + +spatial and deterministic (same cell always looks the same). no flickering. +works for all materials automatically — dirt gets subtle variation, rock gets +speckle. + + +5. Config and Persistence +-------------------------- + +new/changed config defaults: + + antsStartCount 4 slider 0-64, plain number. replaces antsCount. + antBudget 512 hidden. texture size = ceil(sqrt(antBudget)). + seedWorld true checkbox. "seed home + food" toggle. + brushElement "sand" palette buttons. replaces brushMaterial. + includes "ants" as an option. + +REMOVED: antsCount (the 2^N exponent). + +TEXTURE SIZING: antBudget determines the ant texture dimensions. +512 -> sqrt(512) ~ 23 -> 23x23 = 529 slots. ants at index >= antBudget stay +at (0,0) and never activate. starting ants (0 to antsStartCount-1) get +initialized on first frame. drawing ants activates the next available slot. + +LOCAL STORAGE: same pattern as today — only non-default values saved. +antsStartCount and seedWorld persist. antBudget probably shouldn't persist +(changing it requires re-creating textures on reload).