Formicai

Formicai is a visual artificial-life laboratory for studying whether biologically constrained recurrent neural agents can evolve useful colony-scale behavior.

Combining deterministic simulation, neuroevolution, ecology, resource competition, contact-range war, reproduction, disease, weather, and an interactive Godot interface. Ants receive local sensory information rather than a global map or direct colony-wide commands.

Built with Codex + GPT-5.6

Codex using GPT-5.6. Codex helped turn the original concept into the C# and Godot architecture, implement and refactor the simulator, design the visual workspaces, build tests and validation tools, diagnose bugs, write documentation, and automate cross-platform releases. Every major direction and acceptance decision was guided and reviewed by the project owner.

Codex and GPT-5.6 are development tools, not runtime dependencies. The ants do not call a language model: their behavior comes from biologically constrained recurrent neural networks evolved and evaluated inside the deterministic simulation.

• Windows x64
• Linux x64
• macOS Universal

Extract the complete download and launch Formicai.exe on Windows, Formicai.x86_64 on Linux, or Formicai.app on macOS. Linux users may need to mark the binary executable. Because the macOS build is free and not Apple-notarized, first launch may require right-clicking the app and choosing Open.

All builds are self-contained and do not require separate .NET or Godot installations.

Formicai opens directly into a warm, minimal natural-history workstation:

1. Observe — watch surface foraging, queens, brood, weather, predators, excavation, disease, and reproduction. The former Sandbox is now an optional intervention drawer inside this workspace.
2. Inspect — select a worker and follow its recorded sensory evidence, body/recurrent context, neural action, and a clearly labeled behavioral interpretation.
3. Evolution — compare neural training, behavioral diversity, and long-horizon reproductive natural selection in one workspace.
4. Experiments — inspect paired multi-seed ablations, effect sizes, uncertainty, and honest conclusions.
5. Library — browse deterministic ecology, competition, combat, generalization, success, and failure records.

Press F1 for the field guide. Preferences include reduced motion, a high-contrast colony palette, and persistent window/UI scaling.

Preferences and sandbox saves are written under Godot's per-user application data directory, not beside the executable.

Requirements:

• .NET 8 SDK
• Godot 4.7.1 .NET/Mono
• Matching Godot 4.7.1 .NET export templates for packaging

dotnet build AntSim.sln -c Release
dotnet test AntSim.sln -c Release
dotnet format AntSim.sln --verify-no-changes --no-restore

# Regenerate long-horizon ecology, replay, manifest, save, and validation data.
dotnet run --project src/AntSim.Trainer -c Release -- product

# Run the reusable controlled study without regenerating the full product.
dotnet run --project src/AntSim.Trainer -c Release -- study

# Increase statistical power or limit laptop CPU use.
dotnet run --project src/AntSim.Trainer -c Release -- study seeds=24 parallel=4

# Run the Godot project.
godot --path src/AntSim.Viewer
godot --path src/AntSim.Viewer -- documentary
godot --path src/AntSim.Viewer -- showcase
godot --path src/AntSim.Viewer -- selection
godot --path src/AntSim.Viewer -- research

# Produce a local self-contained Windows ZIP.
.\scripts\package-windows.ps1

The current automated suite contains 56 passing tests. Product generation also performs ten end-to-end biological, deterministic, replay, reproduction, and research-artifact validations.

The study command evaluates the same evolved genome in the same randomized worlds under an intact control and several sensory or memory ablations. This paired design separates a real information-channel effect from differences in world difficulty.

It produces:

• pheromone-study.json for applications and future analysis
• pheromone-study.csv for spreadsheets, Python, R, or notebooks
• pheromone-study.md as a readable report
• Intact and pheromone-ablated replays from the most informative paired world

The current study evaluates pheromone sensing, food odor, landmarks, and recurrent memory across twelve deterministic held-out worlds. The bundled result finds recurrent memory essential for this policy; the measured pheromone effect is currently inconclusive rather than overstated.

• AntSim.Core — deterministic ant bodies, worlds, food, pheromones, combat, resource accounting, and state hashing.
• AntSim.Neural — versioned recurrent neural genomes, observations, mutation, inference, tracing, and migration.
• AntSim.Evolution — populations, parallel evaluation, selection, lineage, checkpoints, curriculum, and behavioral archives.
• AntSim.Ecology — colony lifecycle, brood, tasks, nests, climate, seasons, pathogens, predators, saves, replays, and reproductive evolution.
• AntSim.Experiments — reproducible scenarios, metrics, artifact generation, and validation.
• AntSim.Trainer — command-line experiment and product runner.
• AntSim.Viewer — Godot natural-history workstation with Observe, Inspect, Evolution, Experiments, and Library workspaces.

The development workflow included:

• Translating the ant-and-machine-learning concept into an incremental engineering and research plan
• Implementing the deterministic simulation, ecology, neuroevolution, experiment runner, and Godot interface
• Reviewing biological abstractions and documenting where the model remains simplified
• Creating automated tests, deterministic replay checks, product validation, and UI layout validation
• Iterating on the visual design from a game-like prototype into a restrained natural-history observatory
• Packaging and smoke-testing native Windows, Linux, and macOS releases through GitHub Actions

This repository keeps the resulting source, tests, experiment artifacts, and documentation inspectable. AI-generated implementation was not treated as proof of correctness; it was exercised through automated tests, deterministic state checks, visual review, and native release builds.

• Surface workers are individually simulated neural agents.
• Underground worker allocation, nursing, sanitation, trophallaxis, excavation, and brood care currently use an aggregate biological colony model layered over those individually simulated workers.
• A daughter colony is presently counted as a successful reproductive event; it is not yet spawned as a new physically simulated surface colony.
• Parameters are biologically inspired and recorded in the evidence ledger, but this is an artificial-life research model rather than a validated predictor of a particular wild colony.
• Determinism is guaranteed for the same build, configuration, artifacts, seed, and execution path.

Thank you for reading <3

• Finished product v1
• Project charter
• Architecture
• Biological model
• Parameter and evidence ledger
• Phase 11 visual laboratory

The project is released under the MIT License. All current artwork is original procedural rendering; third-party runtime notices are recorded in THIRD_PARTY_NOTICES.md.

Made by Mehmet Dedeler.