Add ant behavior overhaul design and nest-building research
Design covers ant gravity/physics, unified brush tool, behavioral priority stack, sand color variation, and config changes. Research doc captures real ant nest construction patterns for informing simulation behavior.
This commit is contained in:
parent
2269f26f9f
commit
fe537218a3
GPG key ID:
22B5C6D66A38B06C
2 changed files with 399 additions and 0 deletions
244
docs/NEST-BUILDING.md
Normal file
244
docs/NEST-BUILDING.md
Normal file
|
|
@ -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.
|
||||||
155
docs/plans/2026-03-11-ant-behavior-overhaul-design.md
Normal file
155
docs/plans/2026-03-11-ant-behavior-overhaul-design.md
Normal file
|
|
@ -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).
|
||||||
Loading…
Reference in a new issue