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