DOOMFLY: a fly connectome driving a live Doom arena

What DOOMFLY actually simulates, and for whom

DOOMFLY connects a fly connectome simulation to a live Doom-engine arena. Game frames stimulate modeled sensory neurons, activity propagates through the retained MaleCNS v1.0 wiring, and a fixed neuron-to-button interface turns, moves and fires. The README is direct about the status: live experimental training, not demonstrated learned survival, and the current v6 candidate failed its visual, conditioning and survival validation gates.

The audience is narrow and technical. Someone who wants a playable bot has the wrong project. Someone who wants to run a whole-graph spiking model, watch it respond to real game frames, and read the negative results alongside the implementation has an unusually complete artifact: the repository includes controls, modeling assumptions, provenance hashes and a documented list of what is engineered rather than reconstructed. The README states plainly that this is not a literal reconstructed living fly brain. The dynamics, retinal interface, artificial reinforcement and controller are models and engineering choices.

The loop: frames in, 25,582,938 connections, buttons out

The data flow has five stages, and the README numbers each one. Each actual ViZDoom frame drives 3,335 R1 to R6 brightness inputs and 811 R8 color inputs; pixel positions and color responses are inferred proxies. Approximate neural dynamics then run on 166,700 retained neurons and 25,582,938 directed connections from MaleCNS v1.0, with no circuit cropping or replacement game policy.

A fixed interface maps DNp20 right-minus-left activity to turning, and DNpe017 activity to movement and firing. The README calls these engineered controller assignments, not established natural motor functions, which is the honest framing: the output layer is a design decision, not a finding. Reinforcement is similarly synthetic. Nonfatal damage schedules a 200 ms artificial aversive input into two PPL101 dopamine cells, and KC plus dopamine activity drive an adapted plasticity rule on 4,184 existing KC to MBON11 connections. Everything outside that set stays fixed. Death starts a new arena round while neural state and memory persist, and all viewers watch the same experiment.

The scale is the constraint. The README warns the full graph needs several GB of RAM and downloaded data, and that it does not run inside a browser or an edge function. The spectator UI is a separate process reading telemetry from the Python server, not a place where any of this computation happens.

Installing DOOMFLY and starting a first training run

The README specifies Python 3.11 and a C++ compiler. Create the virtual environment and install the pinned neural requirements together with the Doom requirements, using the build constraint file:

python3.11 -m venv .venv-neural
source .venv-neural/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-neural.txt -r doom/requirements.txt \
  --build-constraint neural-build-constraints.txt

Next, download the three MaleCNS inputs listed in doom/datasets.json into connectome_data/malecns_v1/ using the exact registry filenames. The README provides a script that fetches missing files and checks every digest against data-provenance/malecns_v1/source.lock.json before import; it raises a checksum mismatch error if a file does not match. Then run the import and preparation commands in order:

python -m doom.connectome malecns_v1
python -m doom.prepare
python -m doom.audit_data
python -m doom.build_kernel

Starting the server without the explicit model and learning flags runs the fixed baseline. The README gives this invocation for the experimental v6 candidate, with checkpoints written every 300 seconds and resumed from the checkpoint directory:

python -m doom.server --model experimental-v6 --learning --port 8766 \
  --audit-dir outputs/doom/local-training \
  --checkpoint-dir outputs/doom/local-training/checkpoints \
  --checkpoint-seconds 300 --resume

For the viewer, use Node.js 22.13 or later. In doom-ui/, run npm ci, create a local .dev.vars containing DOOM_STREAM_ORIGIN pointing at the server, then run npm run dev. The README notes that configuration files containing real origins or credentials stay untracked. Numerical checks are available through pytest against tests/test_doom.py, tests/test_doom_reference.py and tests/test_doom_live_training.py; the README adds that passing software tests is not evidence of biological validity.

Why the failed v6 gates matter more than the demo

The most useful thing in this repository is the negative result. The README states that the v6 candidate failed its visual, conditioning and survival validation gates, and that changing weights and longer individual rounds do not establish learning. That sentence is a boundary, and it is repeated in the repository structure: doom_learning/ through doom_learning_v6/ hold conditioning and plasticity candidates, while docs/, outputs/ and data-provenance/ hold reviews, compact evidence and dataset hashes.

Treat the plasticity rule accordingly. It modifies 4,184 existing KC to MBON11 connections out of 25,582,938 directed connections, and the rest of the wiring and controller remain fixed. A reader who expects weight change anywhere in the graph will be disappointed; the scope is deliberately tiny, and the README's own framing is that this is an experiment with controls, not a learning system that works. The iteration history is published at doom-ui/public/learning-iterations.json, so the claim can be checked rather than taken on faith.

There is also an operational failure mode. The README warns against running many full-graph jobs concurrently on a small machine, which follows from the memory profile. And the viewer is not the simulation: hosting the viewer alone does not host the simulation, it needs an independently running Python worker and a configured read-only HTTPS origin, and a laptop must stay awake and connected. The prepared container in deploy/doomfly/ has not been certified for cloud operation or audience load, so a public stream is a capacity question before it is a scientific one.

How DOOMFLY differs from a trained game agent

The obvious alternative is a reinforcement-learning agent trained directly on ViZDoom observations, for example a policy network that maps pixels to actions and improves through reward. The difference is where the learning lives. A trained agent optimizes a controller; DOOMFLY keeps the controller fixed by construction, maps DNp20 and DNpe017 activity to buttons as engineered assignments, and restricts plasticity to a small set of existing KC to MBON11 connections driven by an artificial aversive input into two PPL101 dopamine cells. If your goal is a bot that survives, the RL route is the one with a demonstrated path to that outcome, and DOOMFLY's README does not claim otherwise.

The other alternative is a standard spiking neural network simulator, where you supply the topology and the training rule yourself. DOOMFLY's difference is the wiring source and the coupling: a biological reconstruction imported through doom/connectome.py with an exact input registry in doom/datasets.json, driven frame by frame by a live game engine rather than by a static dataset, with provenance locks so the graph can be verified. That combination is the reason to look at it. Neither alternative gives you the same artifact, and DOOMFLY does not try to win the bot benchmark.

Maintenance, upgrade cost and the licence boundary

The repository is not archived and the last push was on 2026-09-09, so the code is recent, but there are no retrieved releases. Upgrades are therefore snapshot-based: the README describes this as a fresh source snapshot with no private Git history, and notes that historical source hashes identify the original experimental artifacts while privacy-redacted files or rebuilt archives can have different byte hashes. Anyone comparing hashes across versions should expect that difference.

Operationally, the cost is in the graph. Several GB of RAM, downloaded connectome data, a C++ compiler and a built native kernel are prerequisites, and checkpoints are mutable state that the README excludes from the published snapshot. Re-running preparation after a data change means re-verifying digests; the checksum step is not optional if you care whether the import matches the lock file.

Licensing is split. Original DOOMFLY code is MIT licensed, but data, game artwork and copied components retain their own licenses, and the README points to THIRD_PARTY.md and the attribution section for scope. That is the boundary to read before redistributing anything from connectome_data/ or the viewer assets; the MIT grant covers the original code, not the upstream materials it consumes.

Editorial conclusion

DOOMFLY is for researchers and engineers who want to inspect a whole-graph connectome simulation coupled to a real game loop, including its failed validation gates, controls and provenance hashes. It is not for anyone who needs a working game-playing agent, a lightweight demo, or a hosted service: the README states the v6 candidate failed its visual, conditioning and survival gates, and that hosting the viewer alone does not host the simulation. Before adopting it, verify that the three MaleCNS files in doom/datasets.json match the digests in data-provenance/malecns_v1/source.lock.json, confirm you have several GB of RAM and a C++ compiler, and read docs/doom-neuroscience-review.md to see which parts are models rather than reconstruction.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. nftechie/doomfly on GitHub
4. README