Repository files navigation

Anthill

Anthill is a grain-scale, voxel-based simulation of an ant colony, implemented in Godot 4.2+. The model is inspired by the biology and chemistry of Lasius niger (black garden ant): discrete-time colony dynamics, recruitment pheromone trails, cuticular hydrocarbon (CHC) footprint fields, Dufour gland / alarm–like signaling, nest excavation in granular substrate, brood development, and worker polyethism. The program is intended as a research-oriented executable model: observers inspect emergent behavior through a scientific HUD, optional pheromone overlays, and validation CSV export—not as an interactive game with player-directed ants.

Scope and limitations. This is a simplified, algorithmic representation. Parameters are tuned for stability and interpretability; they should not be read as species-wide empirical constants. Comparative validation against field or laboratory data is out of scope unless you add it. See docs/reference/technical_specification.txt for the modeling narrative, docs/reference/briefing.txt for foraging feedback logic, docs/reference/architecture_of_emergence.txt for the integrated feedback narrative (and the mapping below), and CHANGELOG.md for implementation history.

Architecture of Emergence (reference mapping)

The note docs/reference/architecture_of_emergence.txt describes positive and negative feedback in ant spatial networks (stigmergy, footprint hydrocarbons, species contrasts). The simulation is Lasius niger–inspired, not a full replication of every mechanism in that text. The following summarizes what is reflected in code versus what is not (at a high level):

Theme (document)In this repository
Positive feedback / mass recruitment — trail deposition reinforces later visitsYes. Recruitment pheromone grid with deposit-on-return behavior, diffusion, evaporation (pheromone_field.gd, colony_ants.gd).
Stigmergy — environment carries the signalYes. Trail and footprint fields are sampled from the substrate; workers do not share a central map.
Stronger marking near foodYes (tunable). On the return path, workers still lay trail pheromone only where they walk (stigmergy); each allowed spot deposit is multiplied by an exponential falloff in horizontal distance to the remembered patch (RECRUIT_TRAIL_BEACON_* in SimParams, defaults in constants.gd), not by return-trip time. That tends to build a brighter trail end near the source after many trips—it is not a separate field applied without ants.
Higher food quality → more markingPartially. Food sources differ by type and supply; pickup and deposit logic does not implement every biological detail of “feed faster → more pheromone” from the literature.
Negative feedback / footprint hydrocarbons — avoid over-searched substrateYes.CHC footprint field: passive deposit while walking, slow decay, repellent / exploration weights (footprint_field.gd, tropotaxis and scout steps in colony_ants.gd).
Trail vs footprint at bifurcations (ratio-style balance)Yes. Recruit tropotaxis uses a ratio form with trail in the numerator and footprint (and crowding) in the denominator (TROPOTAXIS_* in SimParams).
Crowding / overshoot-style reliefPartially.Feeder crowding reduces pickup when many workers are near a patch; there is no explicit “depleted patch” overshoot model beyond finite food and rot.
Alarm / Dufour gland / undecanePartially. An alarm field exists and is framed as Dufour-type; it is not a chemical identity model for undecane.
Monomorium pharaoniscontrast (polydomy, sting dragging, volatile repellent half-life, etc.)No. The executable does not simulate a second species or M. pharaonis trail rules.
Physical “interaction mechanism” at forks (experienced ant steers naive nestmate)No. No pairwise ant–ant steering at bifurcations; only field-based movement.
Visual landmarksNo.
Explicit ABM benchmark (pheromone-only vs dual-signal efficiency)No. The program does not ship a built-in A/B toggle for that comparison; you would compare runs or fork behavior externally.

Nest excavation (granular substrate, procedural blueprint galleries, dig scoring) implements spatial nest expansion described elsewhere in the repo; the Architecture of Emergence text is mainly about foraging networks, not the nest voxel model.

What the simulation contains

  • Substrate: A chunked heightmap-style world in which one voxel represents one sand grain in the fiction (~3 mm; see game/anthill/scripts/constants.gd); loose sand undergoes gravity-driven updates each physics tick.
  • Colony: Founding queen lifecycle (flight, search, claustral phase), brood (egg / larva / pupa durations in ant-days), nanitic and worker emergence, trophallaxis-style feeding from colony stores to the queen, task allocation (foraging, digging, brood care, nest maintenance).
  • Chemical fields (2D grids aligned to the nest plane):recruitment trail (positive feedback, diffusion + evaporation), CHC footprint (traffic-dependent deposit, slow decay), nest-construction pheromone, and an alarm field with deposits tied to colony nutritional stress.
  • Workers: State-based movement (scout vs recruit tropotaxis, substrate-dependent zigzag and stop sampling, memory of food patches, round-trip–scaled recruitment marking, crowding-aware patch choice).
  • Instrumentation: Optional user:// CSV logs when validation flags are enabled in code; optional PerfTrace autoload for frame-cost logging (see CHANGELOG).

Reference materials

PDFs (articles and thesis), briefing notes, architecture of emergence narrative, the technical specification text, and a pheromone reference table (CSV) live under docs/reference/. See docs/reference/README.md. The intro video source file (MP4) and the Ogg Theora asset used at startup are under game/anthill/assets/intro/ (Godot’s built-in player supports .ogv only; regenerate intro.ogv from the MP4 with ffmpeg if you replace the clip).

Running the simulation

Open the Godot project under game/anthill (see game/anthill/README.md for controls and UI), or:

godot --path game/anthill

System install (anthill launcher)

Runtime dependency: Godot 4 on PATH as godot4 or godot. If needed:

sudo ./scripts/install-godot4.sh

That installs /usr/local/bin/godot4 (override: sudo GODOT_VERSION=4.3.0 ./scripts/install-godot4.sh). Alternatively use a distribution package.

From the repository root:

sudo ./scripts/install-anthill.sh

This copies game/anthill to /usr/local/share/anthill/game/anthill and installs /usr/local/bin/anthill, which invokes Godot with the project path. Override install prefix: sudo PREFIX=/opt/anthill ./scripts/install-anthill.sh. One-shot custom binary: GODOT_BIN=/path/to/Godot_v4.x_linux.x86_64 anthill.

PATH conflict: If anthill opens an unrelated engine (e.g. a Luanti binary in ~/.local/bin), rename that binary or call /usr/local/bin/anthill explicitly.

Repository layout

The Ogg Theora intro (game/anthill/assets/intro/intro.ogv) is tracked in Git under GitHub’s per-file size limit. The MP4 source for transcoding is not committed (see game/anthill/.gitignore); place a copy locally if you need to re-encode. Full-resolution download (same clip as the intro): Isolating_the_Negative_Feedback_Loop_in_Ant_Foraging.mp4 on hromp.com.

PathRole
game/anthill/Godot project: scenes, scripts, packaged assets/ (splash, intro media); pre-run simulation_settings.tscn edits autoload SimParams.
docs/reference/Bibliography, specification text, briefing, CSV tables (not loaded at runtime).
docs/cursor-agent-shell.mdNotes if the Cursor agent shell misbehaves.
CHANGELOG.mdVersioned list of code and asset changes.
releases/Standalone Linux .x86_64, Windows .exe, Linux .AppImage (see releases/README.md), repo-relative anthill launcher.
scripts/install-godot4.sh, scripts/install-anthill.sh, scripts/export-linux.sh, scripts/export-windows.sh, scripts/build-linux-appimage.sh, scripts/build-release-binaries.shInstall Godot, system anthill launcher, standalone exports, Linux AppImage, or all release artifacts.

Citation and reuse

If you use this software or its documentation in academic work, cite the repository and version (see game/anthill/project.godotconfig/version and CHANGELOG.md), and describe which commit or release you ran. Model assumptions belong in your methods section; point readers to docs/reference/technical_specification.txt and the CHANGELOG for the mapping from biology to code.

License

Anthill is free software, licensed under the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version (SPDX: GPL-3.0-or-later). See LICENSE in the repository root for the full license text.

Copyright © Anthill contributors.

About

Anthill simulator: pheromone-based ant colony prototype

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
Skip to content

Repository files navigation

Anthill

Anthill is a grain-scale, voxel-based simulation of an ant colony, implemented in Godot 4.2+. The model is inspired by the biology and chemistry of Lasius niger (black garden ant): discrete-time colony dynamics, recruitment pheromone trails, cuticular hydrocarbon (CHC) footprint fields, Dufour gland / alarm–like signaling, nest excavation in granular substrate, brood development, and worker polyethism. The program is intended as a research-oriented executable model: observers inspect emergent behavior through a scientific HUD, optional pheromone overlays, and validation CSV export—not as an interactive game with player-directed ants.

Scope and limitations. This is a simplified, algorithmic representation. Parameters are tuned for stability and interpretability; they should not be read as species-wide empirical constants. Comparative validation against field or laboratory data is out of scope unless you add it. See docs/reference/technical_specification.txt for the modeling narrative, docs/reference/briefing.txt for foraging feedback logic, docs/reference/architecture_of_emergence.txt for the integrated feedback narrative (and the mapping below), and CHANGELOG.md for implementation history.

Architecture of Emergence (reference mapping)

The note docs/reference/architecture_of_emergence.txt describes positive and negative feedback in ant spatial networks (stigmergy, footprint hydrocarbons, species contrasts). The simulation is Lasius niger–inspired, not a full replication of every mechanism in that text. The following summarizes what is reflected in code versus what is not (at a high level):

Theme (document)In this repository
Positive feedback / mass recruitment — trail deposition reinforces later visitsYes. Recruitment pheromone grid with deposit-on-return behavior, diffusion, evaporation (pheromone_field.gd, colony_ants.gd).
Stigmergy — environment carries the signalYes. Trail and footprint fields are sampled from the substrate; workers do not share a central map.
Stronger marking near foodYes (tunable). On the return path, workers still lay trail pheromone only where they walk (stigmergy); each allowed spot deposit is multiplied by an exponential falloff in horizontal distance to the remembered patch (RECRUIT_TRAIL_BEACON_* in SimParams, defaults in constants.gd), not by return-trip time. That tends to build a brighter trail end near the source after many trips—it is not a separate field applied without ants.
Higher food quality → more markingPartially. Food sources differ by type and supply; pickup and deposit logic does not implement every biological detail of “feed faster → more pheromone” from the literature.
Negative feedback / footprint hydrocarbons — avoid over-searched substrateYes.CHC footprint field: passive deposit while walking, slow decay, repellent / exploration weights (footprint_field.gd, tropotaxis and scout steps in colony_ants.gd).
Trail vs footprint at bifurcations (ratio-style balance)Yes. Recruit tropotaxis uses a ratio form with trail in the numerator and footprint (and crowding) in the denominator (TROPOTAXIS_* in SimParams).
Crowding / overshoot-style reliefPartially.Feeder crowding reduces pickup when many workers are near a patch; there is no explicit “depleted patch” overshoot model beyond finite food and rot.
Alarm / Dufour gland / undecanePartially. An alarm field exists and is framed as Dufour-type; it is not a chemical identity model for undecane.
Monomorium pharaoniscontrast (polydomy, sting dragging, volatile repellent half-life, etc.)No. The executable does not simulate a second species or M. pharaonis trail rules.
Physical “interaction mechanism” at forks (experienced ant steers naive nestmate)No. No pairwise ant–ant steering at bifurcations; only field-based movement.
Visual landmarksNo.
Explicit ABM benchmark (pheromone-only vs dual-signal efficiency)No. The program does not ship a built-in A/B toggle for that comparison; you would compare runs or fork behavior externally.

Nest excavation (granular substrate, procedural blueprint galleries, dig scoring) implements spatial nest expansion described elsewhere in the repo; the Architecture of Emergence text is mainly about foraging networks, not the nest voxel model.

What the simulation contains

  • Substrate: A chunked heightmap-style world in which one voxel represents one sand grain in the fiction (~3 mm; see game/anthill/scripts/constants.gd); loose sand undergoes gravity-driven updates each physics tick.
  • Colony: Founding queen lifecycle (flight, search, claustral phase), brood (egg / larva / pupa durations in ant-days), nanitic and worker emergence, trophallaxis-style feeding from colony stores to the queen, task allocation (foraging, digging, brood care, nest maintenance).
  • Chemical fields (2D grids aligned to the nest plane):recruitment trail (positive feedback, diffusion + evaporation), CHC footprint (traffic-dependent deposit, slow decay), nest-construction pheromone, and an alarm field with deposits tied to colony nutritional stress.
  • Workers: State-based movement (scout vs recruit tropotaxis, substrate-dependent zigzag and stop sampling, memory of food patches, round-trip–scaled recruitment marking, crowding-aware patch choice).
  • Instrumentation: Optional user:// CSV logs when validation flags are enabled in code; optional PerfTrace autoload for frame-cost logging (see CHANGELOG).

Reference materials

PDFs (articles and thesis), briefing notes, architecture of emergence narrative, the technical specification text, and a pheromone reference table (CSV) live under docs/reference/. See docs/reference/README.md. The intro video source file (MP4) and the Ogg Theora asset used at startup are under game/anthill/assets/intro/ (Godot’s built-in player supports .ogv only; regenerate intro.ogv from the MP4 with ffmpeg if you replace the clip).

Running the simulation

Open the Godot project under game/anthill (see game/anthill/README.md for controls and UI), or:

godot --path game/anthill

System install (anthill launcher)

Runtime dependency: Godot 4 on PATH as godot4 or godot. If needed:

sudo ./scripts/install-godot4.sh

That installs /usr/local/bin/godot4 (override: sudo GODOT_VERSION=4.3.0 ./scripts/install-godot4.sh). Alternatively use a distribution package.

From the repository root:

sudo ./scripts/install-anthill.sh

This copies game/anthill to /usr/local/share/anthill/game/anthill and installs /usr/local/bin/anthill, which invokes Godot with the project path. Override install prefix: sudo PREFIX=/opt/anthill ./scripts/install-anthill.sh. One-shot custom binary: GODOT_BIN=/path/to/Godot_v4.x_linux.x86_64 anthill.

PATH conflict: If anthill opens an unrelated engine (e.g. a Luanti binary in ~/.local/bin), rename that binary or call /usr/local/bin/anthill explicitly.

Repository layout

The Ogg Theora intro (game/anthill/assets/intro/intro.ogv) is tracked in Git under GitHub’s per-file size limit. The MP4 source for transcoding is not committed (see game/anthill/.gitignore); place a copy locally if you need to re-encode. Full-resolution download (same clip as the intro): Isolating_the_Negative_Feedback_Loop_in_Ant_Foraging.mp4 on hromp.com.

PathRole
game/anthill/Godot project: scenes, scripts, packaged assets/ (splash, intro media); pre-run simulation_settings.tscn edits autoload SimParams.
docs/reference/Bibliography, specification text, briefing, CSV tables (not loaded at runtime).
docs/cursor-agent-shell.mdNotes if the Cursor agent shell misbehaves.
CHANGELOG.mdVersioned list of code and asset changes.
releases/Standalone Linux .x86_64, Windows .exe, Linux .AppImage (see releases/README.md), repo-relative anthill launcher.
scripts/install-godot4.sh, scripts/install-anthill.sh, scripts/export-linux.sh, scripts/export-windows.sh, scripts/build-linux-appimage.sh, scripts/build-release-binaries.shInstall Godot, system anthill launcher, standalone exports, Linux AppImage, or all release artifacts.

Citation and reuse

If you use this software or its documentation in academic work, cite the repository and version (see game/anthill/project.godotconfig/version and CHANGELOG.md), and describe which commit or release you ran. Model assumptions belong in your methods section; point readers to docs/reference/technical_specification.txt and the CHANGELOG for the mapping from biology to code.

License

Anthill is free software, licensed under the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version (SPDX: GPL-3.0-or-later). See LICENSE in the repository root for the full license text.

Copyright © Anthill contributors.

About

Anthill simulator: pheromone-based ant colony prototype

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Force GitHub README to respect dark mode (function() { var style = document.createElement('style'); style.textContent = ' .markdown-body { color-scheme: dark light; } .markdown-body pre { background: #161b22 !important; } .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; } .markdown-body table th, .markdown-body table td { border-color: #30363d !important; } .markdown-body img { background: #0d1117; } .markdown-body blockquote { border-left-color: #8b949e; } .markdown-body hr { border-color: #30363d; } '; document.head.appendChild(style); })(); } } catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content

Repository files navigation

Anthill

Anthill is a grain-scale, voxel-based simulation of an ant colony, implemented in Godot 4.2+. The model is inspired by the biology and chemistry of Lasius niger (black garden ant): discrete-time colony dynamics, recruitment pheromone trails, cuticular hydrocarbon (CHC) footprint fields, Dufour gland / alarm–like signaling, nest excavation in granular substrate, brood development, and worker polyethism. The program is intended as a research-oriented executable model: observers inspect emergent behavior through a scientific HUD, optional pheromone overlays, and validation CSV export—not as an interactive game with player-directed ants.

Scope and limitations. This is a simplified, algorithmic representation. Parameters are tuned for stability and interpretability; they should not be read as species-wide empirical constants. Comparative validation against field or laboratory data is out of scope unless you add it. See docs/reference/technical_specification.txt for the modeling narrative, docs/reference/briefing.txt for foraging feedback logic, docs/reference/architecture_of_emergence.txt for the integrated feedback narrative (and the mapping below), and CHANGELOG.md for implementation history.

Architecture of Emergence (reference mapping)

The note docs/reference/architecture_of_emergence.txt describes positive and negative feedback in ant spatial networks (stigmergy, footprint hydrocarbons, species contrasts). The simulation is Lasius niger–inspired, not a full replication of every mechanism in that text. The following summarizes what is reflected in code versus what is not (at a high level):

Theme (document)In this repository
Positive feedback / mass recruitment — trail deposition reinforces later visitsYes. Recruitment pheromone grid with deposit-on-return behavior, diffusion, evaporation (pheromone_field.gd, colony_ants.gd).
Stigmergy — environment carries the signalYes. Trail and footprint fields are sampled from the substrate; workers do not share a central map.
Stronger marking near foodYes (tunable). On the return path, workers still lay trail pheromone only where they walk (stigmergy); each allowed spot deposit is multiplied by an exponential falloff in horizontal distance to the remembered patch (RECRUIT_TRAIL_BEACON_* in SimParams, defaults in constants.gd), not by return-trip time. That tends to build a brighter trail end near the source after many trips—it is not a separate field applied without ants.
Higher food quality → more markingPartially. Food sources differ by type and supply; pickup and deposit logic does not implement every biological detail of “feed faster → more pheromone” from the literature.
Negative feedback / footprint hydrocarbons — avoid over-searched substrateYes.CHC footprint field: passive deposit while walking, slow decay, repellent / exploration weights (footprint_field.gd, tropotaxis and scout steps in colony_ants.gd).
Trail vs footprint at bifurcations (ratio-style balance)Yes. Recruit tropotaxis uses a ratio form with trail in the numerator and footprint (and crowding) in the denominator (TROPOTAXIS_* in SimParams).
Crowding / overshoot-style reliefPartially.Feeder crowding reduces pickup when many workers are near a patch; there is no explicit “depleted patch” overshoot model beyond finite food and rot.
Alarm / Dufour gland / undecanePartially. An alarm field exists and is framed as Dufour-type; it is not a chemical identity model for undecane.
Monomorium pharaoniscontrast (polydomy, sting dragging, volatile repellent half-life, etc.)No. The executable does not simulate a second species or M. pharaonis trail rules.
Physical “interaction mechanism” at forks (experienced ant steers naive nestmate)No. No pairwise ant–ant steering at bifurcations; only field-based movement.
Visual landmarksNo.
Explicit ABM benchmark (pheromone-only vs dual-signal efficiency)No. The program does not ship a built-in A/B toggle for that comparison; you would compare runs or fork behavior externally.

Nest excavation (granular substrate, procedural blueprint galleries, dig scoring) implements spatial nest expansion described elsewhere in the repo; the Architecture of Emergence text is mainly about foraging networks, not the nest voxel model.

What the simulation contains

  • Substrate: A chunked heightmap-style world in which one voxel represents one sand grain in the fiction (~3 mm; see game/anthill/scripts/constants.gd); loose sand undergoes gravity-driven updates each physics tick.
  • Colony: Founding queen lifecycle (flight, search, claustral phase), brood (egg / larva / pupa durations in ant-days), nanitic and worker emergence, trophallaxis-style feeding from colony stores to the queen, task allocation (foraging, digging, brood care, nest maintenance).
  • Chemical fields (2D grids aligned to the nest plane):recruitment trail (positive feedback, diffusion + evaporation), CHC footprint (traffic-dependent deposit, slow decay), nest-construction pheromone, and an alarm field with deposits tied to colony nutritional stress.
  • Workers: State-based movement (scout vs recruit tropotaxis, substrate-dependent zigzag and stop sampling, memory of food patches, round-trip–scaled recruitment marking, crowding-aware patch choice).
  • Instrumentation: Optional user:// CSV logs when validation flags are enabled in code; optional PerfTrace autoload for frame-cost logging (see CHANGELOG).

Reference materials

PDFs (articles and thesis), briefing notes, architecture of emergence narrative, the technical specification text, and a pheromone reference table (CSV) live under docs/reference/. See docs/reference/README.md. The intro video source file (MP4) and the Ogg Theora asset used at startup are under game/anthill/assets/intro/ (Godot’s built-in player supports .ogv only; regenerate intro.ogv from the MP4 with ffmpeg if you replace the clip).

Running the simulation

Open the Godot project under game/anthill (see game/anthill/README.md for controls and UI), or:

godot --path game/anthill

System install (anthill launcher)

Runtime dependency: Godot 4 on PATH as godot4 or godot. If needed:

sudo ./scripts/install-godot4.sh

That installs /usr/local/bin/godot4 (override: sudo GODOT_VERSION=4.3.0 ./scripts/install-godot4.sh). Alternatively use a distribution package.

From the repository root:

sudo ./scripts/install-anthill.sh

This copies game/anthill to /usr/local/share/anthill/game/anthill and installs /usr/local/bin/anthill, which invokes Godot with the project path. Override install prefix: sudo PREFIX=/opt/anthill ./scripts/install-anthill.sh. One-shot custom binary: GODOT_BIN=/path/to/Godot_v4.x_linux.x86_64 anthill.

PATH conflict: If anthill opens an unrelated engine (e.g. a Luanti binary in ~/.local/bin), rename that binary or call /usr/local/bin/anthill explicitly.

Repository layout

The Ogg Theora intro (game/anthill/assets/intro/intro.ogv) is tracked in Git under GitHub’s per-file size limit. The MP4 source for transcoding is not committed (see game/anthill/.gitignore); place a copy locally if you need to re-encode. Full-resolution download (same clip as the intro): Isolating_the_Negative_Feedback_Loop_in_Ant_Foraging.mp4 on hromp.com.

PathRole
game/anthill/Godot project: scenes, scripts, packaged assets/ (splash, intro media); pre-run simulation_settings.tscn edits autoload SimParams.
docs/reference/Bibliography, specification text, briefing, CSV tables (not loaded at runtime).
docs/cursor-agent-shell.mdNotes if the Cursor agent shell misbehaves.
CHANGELOG.mdVersioned list of code and asset changes.
releases/Standalone Linux .x86_64, Windows .exe, Linux .AppImage (see releases/README.md), repo-relative anthill launcher.
scripts/install-godot4.sh, scripts/install-anthill.sh, scripts/export-linux.sh, scripts/export-windows.sh, scripts/build-linux-appimage.sh, scripts/build-release-binaries.shInstall Godot, system anthill launcher, standalone exports, Linux AppImage, or all release artifacts.

Citation and reuse

If you use this software or its documentation in academic work, cite the repository and version (see game/anthill/project.godotconfig/version and CHANGELOG.md), and describe which commit or release you ran. Model assumptions belong in your methods section; point readers to docs/reference/technical_specification.txt and the CHANGELOG for the mapping from biology to code.

License

Anthill is free software, licensed under the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version (SPDX: GPL-3.0-or-later). See LICENSE in the repository root for the full license text.

Copyright © Anthill contributors.

About

Anthill simulator: pheromone-based ant colony prototype

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Highlight search terms from Google/DuckDuckGo/Bing referrer (function() { var ref = document.referrer; var terms = []; if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) { var url = new URL(ref); var q = url.searchParams.get('q') || url.searchParams.get('p'); if (q) { terms = q.split(/\s+/).filter(function(t) { return t.length > 2; }); } } if (terms.length === 0) return; var style = document.createElement('style'); style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }'; document.head.appendChild(style); function highlight(node) { if (node.nodeType === 3) { // text node var text = node.textContent; var found = false; terms.forEach(function(term) { var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi'); if (regex.test(text)) { found = true; var frag = document.createDocumentFragment(); var parts = text.split(regex); parts.forEach(function(part, i) { if (i % 2 === 0) { frag.appendChild(document.createTextNode(part)); } else { var span = document.createElement('span'); span.className = 'userscript-highlight'; span.textContent = part; frag.appendChild(span); } }); node.parentNode.replaceChild(frag, node); } }); } else if (node.nodeType === 1 && node.childNodes) { // element var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT']; if (!skipTags.includes(node.tagName)) { Array.from(node.childNodes).forEach(highlight); } } } highlight(document.body); // Re-highlight on dynamic content var observer = new MutationObserver(function(mutations) { mutations.forEach(function(m) { m.addedNodes.forEach(function(node) { if (node.nodeType === 1 || node.nodeType === 3) highlight(node); }); }); }); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content

Repository files navigation

Anthill

Anthill is a grain-scale, voxel-based simulation of an ant colony, implemented in Godot 4.2+. The model is inspired by the biology and chemistry of Lasius niger (black garden ant): discrete-time colony dynamics, recruitment pheromone trails, cuticular hydrocarbon (CHC) footprint fields, Dufour gland / alarm–like signaling, nest excavation in granular substrate, brood development, and worker polyethism. The program is intended as a research-oriented executable model: observers inspect emergent behavior through a scientific HUD, optional pheromone overlays, and validation CSV export—not as an interactive game with player-directed ants.

Scope and limitations. This is a simplified, algorithmic representation. Parameters are tuned for stability and interpretability; they should not be read as species-wide empirical constants. Comparative validation against field or laboratory data is out of scope unless you add it. See docs/reference/technical_specification.txt for the modeling narrative, docs/reference/briefing.txt for foraging feedback logic, docs/reference/architecture_of_emergence.txt for the integrated feedback narrative (and the mapping below), and CHANGELOG.md for implementation history.

Architecture of Emergence (reference mapping)

The note docs/reference/architecture_of_emergence.txt describes positive and negative feedback in ant spatial networks (stigmergy, footprint hydrocarbons, species contrasts). The simulation is Lasius niger–inspired, not a full replication of every mechanism in that text. The following summarizes what is reflected in code versus what is not (at a high level):

Theme (document)In this repository
Positive feedback / mass recruitment — trail deposition reinforces later visitsYes. Recruitment pheromone grid with deposit-on-return behavior, diffusion, evaporation (pheromone_field.gd, colony_ants.gd).
Stigmergy — environment carries the signalYes. Trail and footprint fields are sampled from the substrate; workers do not share a central map.
Stronger marking near foodYes (tunable). On the return path, workers still lay trail pheromone only where they walk (stigmergy); each allowed spot deposit is multiplied by an exponential falloff in horizontal distance to the remembered patch (RECRUIT_TRAIL_BEACON_* in SimParams, defaults in constants.gd), not by return-trip time. That tends to build a brighter trail end near the source after many trips—it is not a separate field applied without ants.
Higher food quality → more markingPartially. Food sources differ by type and supply; pickup and deposit logic does not implement every biological detail of “feed faster → more pheromone” from the literature.
Negative feedback / footprint hydrocarbons — avoid over-searched substrateYes.CHC footprint field: passive deposit while walking, slow decay, repellent / exploration weights (footprint_field.gd, tropotaxis and scout steps in colony_ants.gd).
Trail vs footprint at bifurcations (ratio-style balance)Yes. Recruit tropotaxis uses a ratio form with trail in the numerator and footprint (and crowding) in the denominator (TROPOTAXIS_* in SimParams).
Crowding / overshoot-style reliefPartially.Feeder crowding reduces pickup when many workers are near a patch; there is no explicit “depleted patch” overshoot model beyond finite food and rot.
Alarm / Dufour gland / undecanePartially. An alarm field exists and is framed as Dufour-type; it is not a chemical identity model for undecane.
Monomorium pharaoniscontrast (polydomy, sting dragging, volatile repellent half-life, etc.)No. The executable does not simulate a second species or M. pharaonis trail rules.
Physical “interaction mechanism” at forks (experienced ant steers naive nestmate)No. No pairwise ant–ant steering at bifurcations; only field-based movement.
Visual landmarksNo.
Explicit ABM benchmark (pheromone-only vs dual-signal efficiency)No. The program does not ship a built-in A/B toggle for that comparison; you would compare runs or fork behavior externally.

Nest excavation (granular substrate, procedural blueprint galleries, dig scoring) implements spatial nest expansion described elsewhere in the repo; the Architecture of Emergence text is mainly about foraging networks, not the nest voxel model.

What the simulation contains

  • Substrate: A chunked heightmap-style world in which one voxel represents one sand grain in the fiction (~3 mm; see game/anthill/scripts/constants.gd); loose sand undergoes gravity-driven updates each physics tick.
  • Colony: Founding queen lifecycle (flight, search, claustral phase), brood (egg / larva / pupa durations in ant-days), nanitic and worker emergence, trophallaxis-style feeding from colony stores to the queen, task allocation (foraging, digging, brood care, nest maintenance).
  • Chemical fields (2D grids aligned to the nest plane):recruitment trail (positive feedback, diffusion + evaporation), CHC footprint (traffic-dependent deposit, slow decay), nest-construction pheromone, and an alarm field with deposits tied to colony nutritional stress.
  • Workers: State-based movement (scout vs recruit tropotaxis, substrate-dependent zigzag and stop sampling, memory of food patches, round-trip–scaled recruitment marking, crowding-aware patch choice).
  • Instrumentation: Optional user:// CSV logs when validation flags are enabled in code; optional PerfTrace autoload for frame-cost logging (see CHANGELOG).

Reference materials

PDFs (articles and thesis), briefing notes, architecture of emergence narrative, the technical specification text, and a pheromone reference table (CSV) live under docs/reference/. See docs/reference/README.md. The intro video source file (MP4) and the Ogg Theora asset used at startup are under game/anthill/assets/intro/ (Godot’s built-in player supports .ogv only; regenerate intro.ogv from the MP4 with ffmpeg if you replace the clip).

Running the simulation

Open the Godot project under game/anthill (see game/anthill/README.md for controls and UI), or:

godot --path game/anthill

System install (anthill launcher)

Runtime dependency: Godot 4 on PATH as godot4 or godot. If needed:

sudo ./scripts/install-godot4.sh

That installs /usr/local/bin/godot4 (override: sudo GODOT_VERSION=4.3.0 ./scripts/install-godot4.sh). Alternatively use a distribution package.

From the repository root:

sudo ./scripts/install-anthill.sh

This copies game/anthill to /usr/local/share/anthill/game/anthill and installs /usr/local/bin/anthill, which invokes Godot with the project path. Override install prefix: sudo PREFIX=/opt/anthill ./scripts/install-anthill.sh. One-shot custom binary: GODOT_BIN=/path/to/Godot_v4.x_linux.x86_64 anthill.

PATH conflict: If anthill opens an unrelated engine (e.g. a Luanti binary in ~/.local/bin), rename that binary or call /usr/local/bin/anthill explicitly.

Repository layout

The Ogg Theora intro (game/anthill/assets/intro/intro.ogv) is tracked in Git under GitHub’s per-file size limit. The MP4 source for transcoding is not committed (see game/anthill/.gitignore); place a copy locally if you need to re-encode. Full-resolution download (same clip as the intro): Isolating_the_Negative_Feedback_Loop_in_Ant_Foraging.mp4 on hromp.com.

PathRole
game/anthill/Godot project: scenes, scripts, packaged assets/ (splash, intro media); pre-run simulation_settings.tscn edits autoload SimParams.
docs/reference/Bibliography, specification text, briefing, CSV tables (not loaded at runtime).
docs/cursor-agent-shell.mdNotes if the Cursor agent shell misbehaves.
CHANGELOG.mdVersioned list of code and asset changes.
releases/Standalone Linux .x86_64, Windows .exe, Linux .AppImage (see releases/README.md), repo-relative anthill launcher.
scripts/install-godot4.sh, scripts/install-anthill.sh, scripts/export-linux.sh, scripts/export-windows.sh, scripts/build-linux-appimage.sh, scripts/build-release-binaries.shInstall Godot, system anthill launcher, standalone exports, Linux AppImage, or all release artifacts.

Citation and reuse

If you use this software or its documentation in academic work, cite the repository and version (see game/anthill/project.godotconfig/version and CHANGELOG.md), and describe which commit or release you ran. Model assumptions belong in your methods section; point readers to docs/reference/technical_specification.txt and the CHANGELOG for the mapping from biology to code.

License

Anthill is free software, licensed under the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version (SPDX: GPL-3.0-or-later). See LICENSE in the repository root for the full license text.

Copyright © Anthill contributors.

About

Anthill simulator: pheromone-based ant colony prototype

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Strip utm_, fbclid, gclid, etc. from all links on page (function() { var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid', 'ref', 'ref_src', 'source', 'medium', 'campaign']; function cleanUrl(url) { try { var u = new URL(url, window.location.origin); var changed = false; trackingParams.forEach(function(p) { if (u.searchParams.has(p)) { u.searchParams.delete(p); changed = true; } }); return changed ? u.toString() : url; } catch (e) { return url; } } function cleanLinks() { document.querySelectorAll('a[href]').forEach(function(a) { var clean = cleanUrl(a.href); if (clean !== a.href) a.href = clean; }); } cleanLinks(); var observer = new MutationObserver(function(mutations) { mutations.forEach(function(m) { m.addedNodes.forEach(function(node) { if (node.nodeType === 1) { if (node.tagName === 'A') cleanLinks(); node.querySelectorAll('a[href]').forEach(function(a) { var clean = cleanUrl(a.href); if (clean !== a.href) a.href = clean; }); } }); }); }); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); } })(); (function(){ try { var __m = "youtube.com"; var __re = new RegExp('^' + "youtube\\.com" + '
Skip to content

Repository files navigation

Anthill

Anthill is a grain-scale, voxel-based simulation of an ant colony, implemented in Godot 4.2+. The model is inspired by the biology and chemistry of Lasius niger (black garden ant): discrete-time colony dynamics, recruitment pheromone trails, cuticular hydrocarbon (CHC) footprint fields, Dufour gland / alarm–like signaling, nest excavation in granular substrate, brood development, and worker polyethism. The program is intended as a research-oriented executable model: observers inspect emergent behavior through a scientific HUD, optional pheromone overlays, and validation CSV export—not as an interactive game with player-directed ants.

Scope and limitations. This is a simplified, algorithmic representation. Parameters are tuned for stability and interpretability; they should not be read as species-wide empirical constants. Comparative validation against field or laboratory data is out of scope unless you add it. See docs/reference/technical_specification.txt for the modeling narrative, docs/reference/briefing.txt for foraging feedback logic, docs/reference/architecture_of_emergence.txt for the integrated feedback narrative (and the mapping below), and CHANGELOG.md for implementation history.

Architecture of Emergence (reference mapping)

The note docs/reference/architecture_of_emergence.txt describes positive and negative feedback in ant spatial networks (stigmergy, footprint hydrocarbons, species contrasts). The simulation is Lasius niger–inspired, not a full replication of every mechanism in that text. The following summarizes what is reflected in code versus what is not (at a high level):

Theme (document)In this repository
Positive feedback / mass recruitment — trail deposition reinforces later visitsYes. Recruitment pheromone grid with deposit-on-return behavior, diffusion, evaporation (pheromone_field.gd, colony_ants.gd).
Stigmergy — environment carries the signalYes. Trail and footprint fields are sampled from the substrate; workers do not share a central map.
Stronger marking near foodYes (tunable). On the return path, workers still lay trail pheromone only where they walk (stigmergy); each allowed spot deposit is multiplied by an exponential falloff in horizontal distance to the remembered patch (RECRUIT_TRAIL_BEACON_* in SimParams, defaults in constants.gd), not by return-trip time. That tends to build a brighter trail end near the source after many trips—it is not a separate field applied without ants.
Higher food quality → more markingPartially. Food sources differ by type and supply; pickup and deposit logic does not implement every biological detail of “feed faster → more pheromone” from the literature.
Negative feedback / footprint hydrocarbons — avoid over-searched substrateYes.CHC footprint field: passive deposit while walking, slow decay, repellent / exploration weights (footprint_field.gd, tropotaxis and scout steps in colony_ants.gd).
Trail vs footprint at bifurcations (ratio-style balance)Yes. Recruit tropotaxis uses a ratio form with trail in the numerator and footprint (and crowding) in the denominator (TROPOTAXIS_* in SimParams).
Crowding / overshoot-style reliefPartially.Feeder crowding reduces pickup when many workers are near a patch; there is no explicit “depleted patch” overshoot model beyond finite food and rot.
Alarm / Dufour gland / undecanePartially. An alarm field exists and is framed as Dufour-type; it is not a chemical identity model for undecane.
Monomorium pharaoniscontrast (polydomy, sting dragging, volatile repellent half-life, etc.)No. The executable does not simulate a second species or M. pharaonis trail rules.
Physical “interaction mechanism” at forks (experienced ant steers naive nestmate)No. No pairwise ant–ant steering at bifurcations; only field-based movement.
Visual landmarksNo.
Explicit ABM benchmark (pheromone-only vs dual-signal efficiency)No. The program does not ship a built-in A/B toggle for that comparison; you would compare runs or fork behavior externally.

Nest excavation (granular substrate, procedural blueprint galleries, dig scoring) implements spatial nest expansion described elsewhere in the repo; the Architecture of Emergence text is mainly about foraging networks, not the nest voxel model.

What the simulation contains

  • Substrate: A chunked heightmap-style world in which one voxel represents one sand grain in the fiction (~3 mm; see game/anthill/scripts/constants.gd); loose sand undergoes gravity-driven updates each physics tick.
  • Colony: Founding queen lifecycle (flight, search, claustral phase), brood (egg / larva / pupa durations in ant-days), nanitic and worker emergence, trophallaxis-style feeding from colony stores to the queen, task allocation (foraging, digging, brood care, nest maintenance).
  • Chemical fields (2D grids aligned to the nest plane):recruitment trail (positive feedback, diffusion + evaporation), CHC footprint (traffic-dependent deposit, slow decay), nest-construction pheromone, and an alarm field with deposits tied to colony nutritional stress.
  • Workers: State-based movement (scout vs recruit tropotaxis, substrate-dependent zigzag and stop sampling, memory of food patches, round-trip–scaled recruitment marking, crowding-aware patch choice).
  • Instrumentation: Optional user:// CSV logs when validation flags are enabled in code; optional PerfTrace autoload for frame-cost logging (see CHANGELOG).

Reference materials

PDFs (articles and thesis), briefing notes, architecture of emergence narrative, the technical specification text, and a pheromone reference table (CSV) live under docs/reference/. See docs/reference/README.md. The intro video source file (MP4) and the Ogg Theora asset used at startup are under game/anthill/assets/intro/ (Godot’s built-in player supports .ogv only; regenerate intro.ogv from the MP4 with ffmpeg if you replace the clip).

Running the simulation

Open the Godot project under game/anthill (see game/anthill/README.md for controls and UI), or:

godot --path game/anthill

System install (anthill launcher)

Runtime dependency: Godot 4 on PATH as godot4 or godot. If needed:

sudo ./scripts/install-godot4.sh

That installs /usr/local/bin/godot4 (override: sudo GODOT_VERSION=4.3.0 ./scripts/install-godot4.sh). Alternatively use a distribution package.

From the repository root:

sudo ./scripts/install-anthill.sh

This copies game/anthill to /usr/local/share/anthill/game/anthill and installs /usr/local/bin/anthill, which invokes Godot with the project path. Override install prefix: sudo PREFIX=/opt/anthill ./scripts/install-anthill.sh. One-shot custom binary: GODOT_BIN=/path/to/Godot_v4.x_linux.x86_64 anthill.

PATH conflict: If anthill opens an unrelated engine (e.g. a Luanti binary in ~/.local/bin), rename that binary or call /usr/local/bin/anthill explicitly.

Repository layout

The Ogg Theora intro (game/anthill/assets/intro/intro.ogv) is tracked in Git under GitHub’s per-file size limit. The MP4 source for transcoding is not committed (see game/anthill/.gitignore); place a copy locally if you need to re-encode. Full-resolution download (same clip as the intro): Isolating_the_Negative_Feedback_Loop_in_Ant_Foraging.mp4 on hromp.com.

PathRole
game/anthill/Godot project: scenes, scripts, packaged assets/ (splash, intro media); pre-run simulation_settings.tscn edits autoload SimParams.
docs/reference/Bibliography, specification text, briefing, CSV tables (not loaded at runtime).
docs/cursor-agent-shell.mdNotes if the Cursor agent shell misbehaves.
CHANGELOG.mdVersioned list of code and asset changes.
releases/Standalone Linux .x86_64, Windows .exe, Linux .AppImage (see releases/README.md), repo-relative anthill launcher.
scripts/install-godot4.sh, scripts/install-anthill.sh, scripts/export-linux.sh, scripts/export-windows.sh, scripts/build-linux-appimage.sh, scripts/build-release-binaries.shInstall Godot, system anthill launcher, standalone exports, Linux AppImage, or all release artifacts.

Citation and reuse

If you use this software or its documentation in academic work, cite the repository and version (see game/anthill/project.godotconfig/version and CHANGELOG.md), and describe which commit or release you ran. Model assumptions belong in your methods section; point readers to docs/reference/technical_specification.txt and the CHANGELOG for the mapping from biology to code.

License

Anthill is free software, licensed under the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version (SPDX: GPL-3.0-or-later). See LICENSE in the repository root for the full license text.

Copyright © Anthill contributors.

About

Anthill simulator: pheromone-based ant colony prototype

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Auto-enable theater mode on YouTube (function() { function tryTheater() { var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]'); if (btn && !btn.classList.contains('activated')) { btn.click(); } } // Try immediately tryTheater(); // Try after navigation (SPA) var lastUrl = location.href; setInterval(function() { if (location.href !== lastUrl) { lastUrl = location.href; setTimeout(tryTheater, 500); } }, 1000); // Also try on player load var observer = new MutationObserver(tryTheater); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content

Repository files navigation

Anthill

Anthill is a grain-scale, voxel-based simulation of an ant colony, implemented in Godot 4.2+. The model is inspired by the biology and chemistry of Lasius niger (black garden ant): discrete-time colony dynamics, recruitment pheromone trails, cuticular hydrocarbon (CHC) footprint fields, Dufour gland / alarm–like signaling, nest excavation in granular substrate, brood development, and worker polyethism. The program is intended as a research-oriented executable model: observers inspect emergent behavior through a scientific HUD, optional pheromone overlays, and validation CSV export—not as an interactive game with player-directed ants.

Scope and limitations. This is a simplified, algorithmic representation. Parameters are tuned for stability and interpretability; they should not be read as species-wide empirical constants. Comparative validation against field or laboratory data is out of scope unless you add it. See docs/reference/technical_specification.txt for the modeling narrative, docs/reference/briefing.txt for foraging feedback logic, docs/reference/architecture_of_emergence.txt for the integrated feedback narrative (and the mapping below), and CHANGELOG.md for implementation history.

Architecture of Emergence (reference mapping)

The note docs/reference/architecture_of_emergence.txt describes positive and negative feedback in ant spatial networks (stigmergy, footprint hydrocarbons, species contrasts). The simulation is Lasius niger–inspired, not a full replication of every mechanism in that text. The following summarizes what is reflected in code versus what is not (at a high level):

Theme (document)In this repository
Positive feedback / mass recruitment — trail deposition reinforces later visitsYes. Recruitment pheromone grid with deposit-on-return behavior, diffusion, evaporation (pheromone_field.gd, colony_ants.gd).
Stigmergy — environment carries the signalYes. Trail and footprint fields are sampled from the substrate; workers do not share a central map.
Stronger marking near foodYes (tunable). On the return path, workers still lay trail pheromone only where they walk (stigmergy); each allowed spot deposit is multiplied by an exponential falloff in horizontal distance to the remembered patch (RECRUIT_TRAIL_BEACON_* in SimParams, defaults in constants.gd), not by return-trip time. That tends to build a brighter trail end near the source after many trips—it is not a separate field applied without ants.
Higher food quality → more markingPartially. Food sources differ by type and supply; pickup and deposit logic does not implement every biological detail of “feed faster → more pheromone” from the literature.
Negative feedback / footprint hydrocarbons — avoid over-searched substrateYes.CHC footprint field: passive deposit while walking, slow decay, repellent / exploration weights (footprint_field.gd, tropotaxis and scout steps in colony_ants.gd).
Trail vs footprint at bifurcations (ratio-style balance)Yes. Recruit tropotaxis uses a ratio form with trail in the numerator and footprint (and crowding) in the denominator (TROPOTAXIS_* in SimParams).
Crowding / overshoot-style reliefPartially.Feeder crowding reduces pickup when many workers are near a patch; there is no explicit “depleted patch” overshoot model beyond finite food and rot.
Alarm / Dufour gland / undecanePartially. An alarm field exists and is framed as Dufour-type; it is not a chemical identity model for undecane.
Monomorium pharaoniscontrast (polydomy, sting dragging, volatile repellent half-life, etc.)No. The executable does not simulate a second species or M. pharaonis trail rules.
Physical “interaction mechanism” at forks (experienced ant steers naive nestmate)No. No pairwise ant–ant steering at bifurcations; only field-based movement.
Visual landmarksNo.
Explicit ABM benchmark (pheromone-only vs dual-signal efficiency)No. The program does not ship a built-in A/B toggle for that comparison; you would compare runs or fork behavior externally.

Nest excavation (granular substrate, procedural blueprint galleries, dig scoring) implements spatial nest expansion described elsewhere in the repo; the Architecture of Emergence text is mainly about foraging networks, not the nest voxel model.

What the simulation contains

  • Substrate: A chunked heightmap-style world in which one voxel represents one sand grain in the fiction (~3 mm; see game/anthill/scripts/constants.gd); loose sand undergoes gravity-driven updates each physics tick.
  • Colony: Founding queen lifecycle (flight, search, claustral phase), brood (egg / larva / pupa durations in ant-days), nanitic and worker emergence, trophallaxis-style feeding from colony stores to the queen, task allocation (foraging, digging, brood care, nest maintenance).
  • Chemical fields (2D grids aligned to the nest plane):recruitment trail (positive feedback, diffusion + evaporation), CHC footprint (traffic-dependent deposit, slow decay), nest-construction pheromone, and an alarm field with deposits tied to colony nutritional stress.
  • Workers: State-based movement (scout vs recruit tropotaxis, substrate-dependent zigzag and stop sampling, memory of food patches, round-trip–scaled recruitment marking, crowding-aware patch choice).
  • Instrumentation: Optional user:// CSV logs when validation flags are enabled in code; optional PerfTrace autoload for frame-cost logging (see CHANGELOG).

Reference materials

PDFs (articles and thesis), briefing notes, architecture of emergence narrative, the technical specification text, and a pheromone reference table (CSV) live under docs/reference/. See docs/reference/README.md. The intro video source file (MP4) and the Ogg Theora asset used at startup are under game/anthill/assets/intro/ (Godot’s built-in player supports .ogv only; regenerate intro.ogv from the MP4 with ffmpeg if you replace the clip).

Running the simulation

Open the Godot project under game/anthill (see game/anthill/README.md for controls and UI), or:

godot --path game/anthill

System install (anthill launcher)

Runtime dependency: Godot 4 on PATH as godot4 or godot. If needed:

sudo ./scripts/install-godot4.sh

That installs /usr/local/bin/godot4 (override: sudo GODOT_VERSION=4.3.0 ./scripts/install-godot4.sh). Alternatively use a distribution package.

From the repository root:

sudo ./scripts/install-anthill.sh

This copies game/anthill to /usr/local/share/anthill/game/anthill and installs /usr/local/bin/anthill, which invokes Godot with the project path. Override install prefix: sudo PREFIX=/opt/anthill ./scripts/install-anthill.sh. One-shot custom binary: GODOT_BIN=/path/to/Godot_v4.x_linux.x86_64 anthill.

PATH conflict: If anthill opens an unrelated engine (e.g. a Luanti binary in ~/.local/bin), rename that binary or call /usr/local/bin/anthill explicitly.

Repository layout

The Ogg Theora intro (game/anthill/assets/intro/intro.ogv) is tracked in Git under GitHub’s per-file size limit. The MP4 source for transcoding is not committed (see game/anthill/.gitignore); place a copy locally if you need to re-encode. Full-resolution download (same clip as the intro): Isolating_the_Negative_Feedback_Loop_in_Ant_Foraging.mp4 on hromp.com.

PathRole
game/anthill/Godot project: scenes, scripts, packaged assets/ (splash, intro media); pre-run simulation_settings.tscn edits autoload SimParams.
docs/reference/Bibliography, specification text, briefing, CSV tables (not loaded at runtime).
docs/cursor-agent-shell.mdNotes if the Cursor agent shell misbehaves.
CHANGELOG.mdVersioned list of code and asset changes.
releases/Standalone Linux .x86_64, Windows .exe, Linux .AppImage (see releases/README.md), repo-relative anthill launcher.
scripts/install-godot4.sh, scripts/install-anthill.sh, scripts/export-linux.sh, scripts/export-windows.sh, scripts/build-linux-appimage.sh, scripts/build-release-binaries.shInstall Godot, system anthill launcher, standalone exports, Linux AppImage, or all release artifacts.

Citation and reuse

If you use this software or its documentation in academic work, cite the repository and version (see game/anthill/project.godotconfig/version and CHANGELOG.md), and describe which commit or release you ran. Model assumptions belong in your methods section; point readers to docs/reference/technical_specification.txt and the CHANGELOG for the mapping from biology to code.

License

Anthill is free software, licensed under the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version (SPDX: GPL-3.0-or-later). See LICENSE in the repository root for the full license text.

Copyright © Anthill contributors.

About

Anthill simulator: pheromone-based ant colony prototype

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Remove or un-stick sticky/fixed headers that block content (function() { function unstick() { document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) { if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') { el.style.position = 'static'; el.style.top = 'auto'; el.style.zIndex = 'auto'; } }); } unstick(); var observer = new MutationObserver(unstick); observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] }); })(); } } catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content

Repository files navigation

Anthill

Anthill is a grain-scale, voxel-based simulation of an ant colony, implemented in Godot 4.2+. The model is inspired by the biology and chemistry of Lasius niger (black garden ant): discrete-time colony dynamics, recruitment pheromone trails, cuticular hydrocarbon (CHC) footprint fields, Dufour gland / alarm–like signaling, nest excavation in granular substrate, brood development, and worker polyethism. The program is intended as a research-oriented executable model: observers inspect emergent behavior through a scientific HUD, optional pheromone overlays, and validation CSV export—not as an interactive game with player-directed ants.

Scope and limitations. This is a simplified, algorithmic representation. Parameters are tuned for stability and interpretability; they should not be read as species-wide empirical constants. Comparative validation against field or laboratory data is out of scope unless you add it. See docs/reference/technical_specification.txt for the modeling narrative, docs/reference/briefing.txt for foraging feedback logic, docs/reference/architecture_of_emergence.txt for the integrated feedback narrative (and the mapping below), and CHANGELOG.md for implementation history.

Architecture of Emergence (reference mapping)

The note docs/reference/architecture_of_emergence.txt describes positive and negative feedback in ant spatial networks (stigmergy, footprint hydrocarbons, species contrasts). The simulation is Lasius niger–inspired, not a full replication of every mechanism in that text. The following summarizes what is reflected in code versus what is not (at a high level):

Theme (document)In this repository
Positive feedback / mass recruitment — trail deposition reinforces later visitsYes. Recruitment pheromone grid with deposit-on-return behavior, diffusion, evaporation (pheromone_field.gd, colony_ants.gd).
Stigmergy — environment carries the signalYes. Trail and footprint fields are sampled from the substrate; workers do not share a central map.
Stronger marking near foodYes (tunable). On the return path, workers still lay trail pheromone only where they walk (stigmergy); each allowed spot deposit is multiplied by an exponential falloff in horizontal distance to the remembered patch (RECRUIT_TRAIL_BEACON_* in SimParams, defaults in constants.gd), not by return-trip time. That tends to build a brighter trail end near the source after many trips—it is not a separate field applied without ants.
Higher food quality → more markingPartially. Food sources differ by type and supply; pickup and deposit logic does not implement every biological detail of “feed faster → more pheromone” from the literature.
Negative feedback / footprint hydrocarbons — avoid over-searched substrateYes.CHC footprint field: passive deposit while walking, slow decay, repellent / exploration weights (footprint_field.gd, tropotaxis and scout steps in colony_ants.gd).
Trail vs footprint at bifurcations (ratio-style balance)Yes. Recruit tropotaxis uses a ratio form with trail in the numerator and footprint (and crowding) in the denominator (TROPOTAXIS_* in SimParams).
Crowding / overshoot-style reliefPartially.Feeder crowding reduces pickup when many workers are near a patch; there is no explicit “depleted patch” overshoot model beyond finite food and rot.
Alarm / Dufour gland / undecanePartially. An alarm field exists and is framed as Dufour-type; it is not a chemical identity model for undecane.
Monomorium pharaoniscontrast (polydomy, sting dragging, volatile repellent half-life, etc.)No. The executable does not simulate a second species or M. pharaonis trail rules.
Physical “interaction mechanism” at forks (experienced ant steers naive nestmate)No. No pairwise ant–ant steering at bifurcations; only field-based movement.
Visual landmarksNo.
Explicit ABM benchmark (pheromone-only vs dual-signal efficiency)No. The program does not ship a built-in A/B toggle for that comparison; you would compare runs or fork behavior externally.

Nest excavation (granular substrate, procedural blueprint galleries, dig scoring) implements spatial nest expansion described elsewhere in the repo; the Architecture of Emergence text is mainly about foraging networks, not the nest voxel model.

What the simulation contains

  • Substrate: A chunked heightmap-style world in which one voxel represents one sand grain in the fiction (~3 mm; see game/anthill/scripts/constants.gd); loose sand undergoes gravity-driven updates each physics tick.
  • Colony: Founding queen lifecycle (flight, search, claustral phase), brood (egg / larva / pupa durations in ant-days), nanitic and worker emergence, trophallaxis-style feeding from colony stores to the queen, task allocation (foraging, digging, brood care, nest maintenance).
  • Chemical fields (2D grids aligned to the nest plane):recruitment trail (positive feedback, diffusion + evaporation), CHC footprint (traffic-dependent deposit, slow decay), nest-construction pheromone, and an alarm field with deposits tied to colony nutritional stress.
  • Workers: State-based movement (scout vs recruit tropotaxis, substrate-dependent zigzag and stop sampling, memory of food patches, round-trip–scaled recruitment marking, crowding-aware patch choice).
  • Instrumentation: Optional user:// CSV logs when validation flags are enabled in code; optional PerfTrace autoload for frame-cost logging (see CHANGELOG).

Reference materials

PDFs (articles and thesis), briefing notes, architecture of emergence narrative, the technical specification text, and a pheromone reference table (CSV) live under docs/reference/. See docs/reference/README.md. The intro video source file (MP4) and the Ogg Theora asset used at startup are under game/anthill/assets/intro/ (Godot’s built-in player supports .ogv only; regenerate intro.ogv from the MP4 with ffmpeg if you replace the clip).

Running the simulation

Open the Godot project under game/anthill (see game/anthill/README.md for controls and UI), or:

godot --path game/anthill

System install (anthill launcher)

Runtime dependency: Godot 4 on PATH as godot4 or godot. If needed:

sudo ./scripts/install-godot4.sh

That installs /usr/local/bin/godot4 (override: sudo GODOT_VERSION=4.3.0 ./scripts/install-godot4.sh). Alternatively use a distribution package.

From the repository root:

sudo ./scripts/install-anthill.sh

This copies game/anthill to /usr/local/share/anthill/game/anthill and installs /usr/local/bin/anthill, which invokes Godot with the project path. Override install prefix: sudo PREFIX=/opt/anthill ./scripts/install-anthill.sh. One-shot custom binary: GODOT_BIN=/path/to/Godot_v4.x_linux.x86_64 anthill.

PATH conflict: If anthill opens an unrelated engine (e.g. a Luanti binary in ~/.local/bin), rename that binary or call /usr/local/bin/anthill explicitly.

Repository layout

The Ogg Theora intro (game/anthill/assets/intro/intro.ogv) is tracked in Git under GitHub’s per-file size limit. The MP4 source for transcoding is not committed (see game/anthill/.gitignore); place a copy locally if you need to re-encode. Full-resolution download (same clip as the intro): Isolating_the_Negative_Feedback_Loop_in_Ant_Foraging.mp4 on hromp.com.

PathRole
game/anthill/Godot project: scenes, scripts, packaged assets/ (splash, intro media); pre-run simulation_settings.tscn edits autoload SimParams.
docs/reference/Bibliography, specification text, briefing, CSV tables (not loaded at runtime).
docs/cursor-agent-shell.mdNotes if the Cursor agent shell misbehaves.
CHANGELOG.mdVersioned list of code and asset changes.
releases/Standalone Linux .x86_64, Windows .exe, Linux .AppImage (see releases/README.md), repo-relative anthill launcher.
scripts/install-godot4.sh, scripts/install-anthill.sh, scripts/export-linux.sh, scripts/export-windows.sh, scripts/build-linux-appimage.sh, scripts/build-release-binaries.shInstall Godot, system anthill launcher, standalone exports, Linux AppImage, or all release artifacts.

Citation and reuse

If you use this software or its documentation in academic work, cite the repository and version (see game/anthill/project.godotconfig/version and CHANGELOG.md), and describe which commit or release you ran. Model assumptions belong in your methods section; point readers to docs/reference/technical_specification.txt and the CHANGELOG for the mapping from biology to code.

License

Anthill is free software, licensed under the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version (SPDX: GPL-3.0-or-later). See LICENSE in the repository root for the full license text.

Copyright © Anthill contributors.

About

Anthill simulator: pheromone-based ant colony prototype

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

, 'i'); if (__m === '*' || __re.test(location.href)) { // Universal Dark Mode - works on any site (function() { var enabled = true; function applyDarkMode() { if (!enabled) return; // Create style element if it doesn't exist var style = document.getElementById('universal-dark-mode-style'); if (!style) { style = document.createElement('style'); style.id = 'universal-dark-mode-style'; document.head.appendChild(style); } // Dark mode CSS - inverts colors but preserves images/video style.textContent = ' /* Invert everything except media */ html { filter: invert(1) hue-rotate(180deg) !important; background: #1a1a2e !important; } /* Restore images, videos, iframes, canvas */ img, video, iframe, canvas, svg, picture, [style*="background-image"] { filter: invert(1) hue-rotate(180deg) !important; } /* Preserve specific elements that should not be inverted */ .no-dark-mode, .no-dark-mode *, [data-theme="light"], [data-theme="light"], .ace_editor, .ace_editor *, .CodeMirror, .CodeMirror *, .monaco-editor, .monaco-editor *, .markdown-body pre, .markdown-body pre *, .highlight, .highlight *, pre code, pre code * { filter: none !important; } /* Fix common UI elements */ .modal, .popup, .dropdown-menu, .tooltip, .popover { filter: invert(1) hue-rotate(180deg) !important; background: #2d2d44 !important; border-color: #444 !important; } /* Scrollbars */ ::-webkit-scrollbar { background: #1a1a2e !important; } ::-webkit-scrollbar-thumb { background: #444 !important; } ::-webkit-scrollbar-thumb:hover { background: #555 !important; } /* Selection */ ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; } ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; } '; } function removeDarkMode() { var style = document.getElementById('universal-dark-mode-style'); if (style) style.remove(); } // Toggle with Alt+Shift+D document.addEventListener('keydown', function(e) { if (e.altKey && e.shiftKey && e.key === 'D') { e.preventDefault(); enabled = !enabled; if (enabled) { applyDarkMode(); console.log('[Universal Dark Mode] Enabled'); } else { removeDarkMode(); console.log('[Universal Dark Mode] Disabled'); } } }); // Apply on load applyDarkMode(); // Re-apply on dynamic content var observer = new MutationObserver(function(mutations) { if (enabled && !document.getElementById('universal-dark-mode-style')) { applyDarkMode(); } }); observer.observe(document.head, { childList: true }); console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle'); })(); } } catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); } })(); })();
Skip to content

Repository files navigation

Anthill

Anthill is a grain-scale, voxel-based simulation of an ant colony, implemented in Godot 4.2+. The model is inspired by the biology and chemistry of Lasius niger (black garden ant): discrete-time colony dynamics, recruitment pheromone trails, cuticular hydrocarbon (CHC) footprint fields, Dufour gland / alarm–like signaling, nest excavation in granular substrate, brood development, and worker polyethism. The program is intended as a research-oriented executable model: observers inspect emergent behavior through a scientific HUD, optional pheromone overlays, and validation CSV export—not as an interactive game with player-directed ants.

Scope and limitations. This is a simplified, algorithmic representation. Parameters are tuned for stability and interpretability; they should not be read as species-wide empirical constants. Comparative validation against field or laboratory data is out of scope unless you add it. See docs/reference/technical_specification.txt for the modeling narrative, docs/reference/briefing.txt for foraging feedback logic, docs/reference/architecture_of_emergence.txt for the integrated feedback narrative (and the mapping below), and CHANGELOG.md for implementation history.

Architecture of Emergence (reference mapping)

The note docs/reference/architecture_of_emergence.txt describes positive and negative feedback in ant spatial networks (stigmergy, footprint hydrocarbons, species contrasts). The simulation is Lasius niger–inspired, not a full replication of every mechanism in that text. The following summarizes what is reflected in code versus what is not (at a high level):

Theme (document)In this repository
Positive feedback / mass recruitment — trail deposition reinforces later visitsYes. Recruitment pheromone grid with deposit-on-return behavior, diffusion, evaporation (pheromone_field.gd, colony_ants.gd).
Stigmergy — environment carries the signalYes. Trail and footprint fields are sampled from the substrate; workers do not share a central map.
Stronger marking near foodYes (tunable). On the return path, workers still lay trail pheromone only where they walk (stigmergy); each allowed spot deposit is multiplied by an exponential falloff in horizontal distance to the remembered patch (RECRUIT_TRAIL_BEACON_* in SimParams, defaults in constants.gd), not by return-trip time. That tends to build a brighter trail end near the source after many trips—it is not a separate field applied without ants.
Higher food quality → more markingPartially. Food sources differ by type and supply; pickup and deposit logic does not implement every biological detail of “feed faster → more pheromone” from the literature.
Negative feedback / footprint hydrocarbons — avoid over-searched substrateYes.CHC footprint field: passive deposit while walking, slow decay, repellent / exploration weights (footprint_field.gd, tropotaxis and scout steps in colony_ants.gd).
Trail vs footprint at bifurcations (ratio-style balance)Yes. Recruit tropotaxis uses a ratio form with trail in the numerator and footprint (and crowding) in the denominator (TROPOTAXIS_* in SimParams).
Crowding / overshoot-style reliefPartially.Feeder crowding reduces pickup when many workers are near a patch; there is no explicit “depleted patch” overshoot model beyond finite food and rot.
Alarm / Dufour gland / undecanePartially. An alarm field exists and is framed as Dufour-type; it is not a chemical identity model for undecane.
Monomorium pharaoniscontrast (polydomy, sting dragging, volatile repellent half-life, etc.)No. The executable does not simulate a second species or M. pharaonis trail rules.
Physical “interaction mechanism” at forks (experienced ant steers naive nestmate)No. No pairwise ant–ant steering at bifurcations; only field-based movement.
Visual landmarksNo.
Explicit ABM benchmark (pheromone-only vs dual-signal efficiency)No. The program does not ship a built-in A/B toggle for that comparison; you would compare runs or fork behavior externally.

Nest excavation (granular substrate, procedural blueprint galleries, dig scoring) implements spatial nest expansion described elsewhere in the repo; the Architecture of Emergence text is mainly about foraging networks, not the nest voxel model.

What the simulation contains

  • Substrate: A chunked heightmap-style world in which one voxel represents one sand grain in the fiction (~3 mm; see game/anthill/scripts/constants.gd); loose sand undergoes gravity-driven updates each physics tick.
  • Colony: Founding queen lifecycle (flight, search, claustral phase), brood (egg / larva / pupa durations in ant-days), nanitic and worker emergence, trophallaxis-style feeding from colony stores to the queen, task allocation (foraging, digging, brood care, nest maintenance).
  • Chemical fields (2D grids aligned to the nest plane):recruitment trail (positive feedback, diffusion + evaporation), CHC footprint (traffic-dependent deposit, slow decay), nest-construction pheromone, and an alarm field with deposits tied to colony nutritional stress.
  • Workers: State-based movement (scout vs recruit tropotaxis, substrate-dependent zigzag and stop sampling, memory of food patches, round-trip–scaled recruitment marking, crowding-aware patch choice).
  • Instrumentation: Optional user:// CSV logs when validation flags are enabled in code; optional PerfTrace autoload for frame-cost logging (see CHANGELOG).

Reference materials

PDFs (articles and thesis), briefing notes, architecture of emergence narrative, the technical specification text, and a pheromone reference table (CSV) live under docs/reference/. See docs/reference/README.md. The intro video source file (MP4) and the Ogg Theora asset used at startup are under game/anthill/assets/intro/ (Godot’s built-in player supports .ogv only; regenerate intro.ogv from the MP4 with ffmpeg if you replace the clip).

Running the simulation

Open the Godot project under game/anthill (see game/anthill/README.md for controls and UI), or:

godot --path game/anthill

System install (anthill launcher)

Runtime dependency: Godot 4 on PATH as godot4 or godot. If needed:

sudo ./scripts/install-godot4.sh

That installs /usr/local/bin/godot4 (override: sudo GODOT_VERSION=4.3.0 ./scripts/install-godot4.sh). Alternatively use a distribution package.

From the repository root:

sudo ./scripts/install-anthill.sh

This copies game/anthill to /usr/local/share/anthill/game/anthill and installs /usr/local/bin/anthill, which invokes Godot with the project path. Override install prefix: sudo PREFIX=/opt/anthill ./scripts/install-anthill.sh. One-shot custom binary: GODOT_BIN=/path/to/Godot_v4.x_linux.x86_64 anthill.

PATH conflict: If anthill opens an unrelated engine (e.g. a Luanti binary in ~/.local/bin), rename that binary or call /usr/local/bin/anthill explicitly.

Repository layout

The Ogg Theora intro (game/anthill/assets/intro/intro.ogv) is tracked in Git under GitHub’s per-file size limit. The MP4 source for transcoding is not committed (see game/anthill/.gitignore); place a copy locally if you need to re-encode. Full-resolution download (same clip as the intro): Isolating_the_Negative_Feedback_Loop_in_Ant_Foraging.mp4 on hromp.com.

PathRole
game/anthill/Godot project: scenes, scripts, packaged assets/ (splash, intro media); pre-run simulation_settings.tscn edits autoload SimParams.
docs/reference/Bibliography, specification text, briefing, CSV tables (not loaded at runtime).
docs/cursor-agent-shell.mdNotes if the Cursor agent shell misbehaves.
CHANGELOG.mdVersioned list of code and asset changes.
releases/Standalone Linux .x86_64, Windows .exe, Linux .AppImage (see releases/README.md), repo-relative anthill launcher.
scripts/install-godot4.sh, scripts/install-anthill.sh, scripts/export-linux.sh, scripts/export-windows.sh, scripts/build-linux-appimage.sh, scripts/build-release-binaries.shInstall Godot, system anthill launcher, standalone exports, Linux AppImage, or all release artifacts.

Citation and reuse

If you use this software or its documentation in academic work, cite the repository and version (see game/anthill/project.godotconfig/version and CHANGELOG.md), and describe which commit or release you ran. Model assumptions belong in your methods section; point readers to docs/reference/technical_specification.txt and the CHANGELOG for the mapping from biology to code.

License

Anthill is free software, licensed under the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version (SPDX: GPL-3.0-or-later). See LICENSE in the repository root for the full license text.

Copyright © Anthill contributors.

About

Anthill simulator: pheromone-based ant colony prototype

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages