![\"DOOMFORMER:](\"https://github.com/mottopanikeiku/doomformer/releases/download/v0.4.0/banner_wide.png\")
Neural networks computed by voodoo dolls inside DOOM maps.
\nEvery value is read back and checked against NumPy. Tolerance 0.
![\"tests\"](\"https://github.com/mottopanikeiku/doomformer/actions/workflows/tests.yml/badge.svg\"){kind=icon}
Quick start · Walk a digit · The museum · How it works · What is checked · Films · Docs
\n| 10,000 / 10,000 | \n1,355 | \n0 | \n4 | \n
|---|---|---|---|
| MNIST test digits exact | \nvoodoo dolls in one MNIST map | \nmismatches in 20,000 fuzzed nets | \nother DOOM engines run the museum exactly | \n
![\"A](\"https://github.com/mottopanikeiku/doomformer/releases/download/v0.4.0/ladder.png\")
doomformer doctor checks your setup. It builds ACC, the ACS compiler, if it is missing. That needs git, cmake and a C compiler. On Fedora: sudo dnf install git cmake gcc gcc-c++ make.
Tip
\nNo install needed for the Colab notebook. Draw a digit in your browser and DOOM reads it.
\n![\"DrawPad:](\"https://github.com/mottopanikeiku/doomformer/releases/download/v0.1.0/drawpad.gif\")
The marine holds FIRE and inks the floor. Then he presses READ.
\n1,355 voodoo dolls in the same map run an MNIST network. The winning digit's doll crosses a line. That line lights the digit on the display.
\n ▄▄▄▄▄▄▄▄▄▄▄▄▄▄\n ▄████████████████\n ████▀▀ ▀████▀\n ▀▀▀ ▄███▀\n ████\n ███\n ███\n ███\n ████\n ███▀\n ████\n ▀███\n\nDOOM reads: 7 (right) -- the winner's doll lit it on the 7-segment display\nEXACT: all 248 values DOOM computed [...] equal the NumPy integer reference (tolerance 0)\nREAD pass: 273 game tics = 8 s of real-time DOOM at 35 tics/s, 3 s wall [...]\nPython reads back 248 values and checks every one. With --digit, Python presses the keys for you. Without it, you walk and draw yourself. Full output
Note
\nEXACT means DOOM got the same numbers as the integer network. It does not mean the digit is right.
\n| run | \nright | \nexact | \n
|---|---|---|
| first 100 MNIST test digits | \n99 | \n100 | \n
| 1,000 sampled test digits, one map each | \n966 | \n1,000 | \n
| all 10,000 test digits, tile maps | \n9,716 (97.16 %) | \n10,000 | \n
The float model scores 97.58 %. The network also trained on the strokes the scripted marine walks. Details · Film
\n![\"eight](\"https://github.com/mottopanikeiku/doomformer/releases/download/v0.1.0/mnist.png\")
![\"Two](\"https://github.com/mottopanikeiku/doomformer/releases/download/v0.7.1/museum_mutate.png\")
Tip
\nPlay it without Python. Download museum.wad (sha256) and the free Freedoom IWAD. Then run gzdoom -iwad freedoom2.wad -file museum.wad.
Step on seven floor pads to light a digit. Press READ. 136 voodoo dolls run a tiny network and light the answer.
\nPress MUTATE and the level rewires one connection while it runs. The same 7 now reads as 1. You can watch it happen: one doll stops at its gate.
\n\n; ; \n; ; \n; ; \nA self-test version runs exactly in GZDoom, LZDoom, UZDoom and ZDoom 2.8.1. Details
\nEvery part of a network becomes a part of the map:
\n| in a neural network | \nin the DOOM map | \n
|---|---|
| a value of 5 | \n5 voodoo dolls | \n
| a weight | \na line on the floor; each doll that crosses it adds the weight | \n
| a sum | \na sector's light level or floor height | \n
| an activation (ReLU) | \na staircase of gates the dolls must climb | \n
| attention | \ndolls squeezing under ceilings that another value lowered | \n
| a lesion | \na closed door | \n
One layer, from dolls to dolls:
\nflowchart LR\n A["input value<br/>= a crowd of dolls"] --> B["weight lines<br/>each crossing adds w"]\n B --> C["the sum<br/>= a light level or height"]\n C --> D["staircase of gates<br/>= the activation"]\n D --> E["next layer's dolls"]\nLoading
\nThe engine has sharp edges, and the compiler works around them:
\ndoomformer facts checks these in about 10 s. Engine facts · Engine features it needs · Other ports
Computers in DOOM maps are not new. counter.wad counts with voodoo dolls, conway.wad runs Game of Life, and Danny Spencer's calculator adds numbers. New here: a compiler for neural networks, and an exact check on every value. Related work
\n![\"Pipeline:](\"https://github.com/mottopanikeiku/doomformer/releases/download/v0.4.0/pipeline.png\")
Every run compares each value the map exposes with NumPy. That proves the inputs that ran, nothing more. So the repo also attacks its own check:
\n| attack | \nresult | \n
|---|---|
| Tamper with one weight line | \nthe check fails on exactly the inputs that cross it | \n
| Fuzz 20,000 random nets at the range limits | \n0 mismatches; CI fuzzes a fresh seed on every push | \n
| Mutate one line of a map, 1,004 times | \n297 caught; no survivor is proven harmless | \n
| Extract the weights back out of the map, without DOOM | \nequal to the source net | \n
| Guard every readout page with a poison value | \na page that never runs cannot pass old values | \n
The MNIST map exposes 248 values. It does not expose its 903 staircase counts and 1,351 gate comparisons. Those are checked only through the sums they feed. Fuzzing and tests found four bugs in the compiler. All are fixed. Verification
\nWho computes what
\n| run | \nPython | \nvoodoo dolls | \n
|---|---|---|
mnist, df.compile | \nwrites the inputs, waits, reads | \nevery sum, activation, comparison and the choice | \n
demo, ask (tile maps) | \nwrites tokens, copies values between maps, samples letters | \nevery sum and activation | \n
draw, --loop, the marine's brain, the fly | \nonly advances the clock and reads | \neverything, including the choice | \n
machine | \nloads the program, then advances the clock and reads | \nprogram counter and registers | \n
museum, played in GZDoom | \nnothing | \nevery sum, comparison and the choice | \n
ACS level scripts move gates, rewind the dolls, sense the world and copy results out. Two do more. df.Agent takes an argmax in ACS. --opt 3 copies each layer's values into the next layer with a script. Per demo
The maps need ZDoom (UDMF and ACS). This repo runs ViZDoom 1.3.2 with Freedoom assets.
\n| Command | \nWhat DOOM does | \nTime | \nSkill level | \n
|---|---|---|---|
doomformer hello | \na small MLP, 5 random inputs | \n2 s | \nI'm too young to die | \n
doomformer draw --digit 7 | \nthe marine walks a 7, the level reads it | \n15 s | \nHey, not too rough | \n
doomformer museum build | \na playable map that reads a digit | \n1 s | \nHey, not too rough | \n
doomformer mnist | \nreads 4 test digits, or your own image | \n1.5 to 3 min | \nHurt me plenty | \n
doomformer demo | \na transformer writes a level name | \n15 to 60 s | \nHurt me plenty | \n
doomformer machine subleq all | \na tiny computer runs three programs | \nabout 5 min | \nUltra-Violence | \n
doomformer learn digits --classes 4 --steps 300 | \na blank brain learns digits inside the map | \nabout 5 min | \nUltra-Violence | \n
doomformer ask "what does iddqd do" | \nanswers from 189 DOOM facts | \nabout 11 min | \nUltra-Violence | \n
doomformer demo --nightmare | \nthe 2-layer model, 106 tile maps | \n3.5 to 7 min | \nNightmare! | \n
Times are from a 16-core arm64 Linux machine. Every command
\nSome outputs are picked. DEMON CANYON, the name --nightmare writes, is one hand-picked sample. ask gets 94.7 % of its training questions right, and 35.4 % of new wordings.
![\"His](\"https://github.com/mottopanikeiku/doomformer/releases/download/v0.1.0/hero.gif\")
His brain is the level. The level senses the nearest demon. 1,345 voodoo dolls of the marine run his brain and pick an action. The level turns him and fires. Python only steps the clock and reads. 50 of 50 decisions are exact. Film · Code
\nWarning
\nHe is not playable. One decision takes 22 s of game time, and the demons are frozen while he thinks. With the demons awake (--live), he dies in 5.5 s without a kill. Live demons
| run it from a clone | \nwhat you see | \n
|---|---|
python -m demos.brainlevel | \nhis brain is the level | \n
python -m demos.brainlevel --live | \nthe same brain against awake demons | \n
python -m demos.brainlevel --lesion-when near | \nthe level closes neuron doors when a demon gets close | \n
python -m demos.aimlearn | \na perceptron learns to aim inside one game | \n
python -m demos.flyloop | \na fruit-fly circuit drives the marine | \n
python -m demos.lobotomy | \nlesions that turn him into a pacifist | \n
All demos, numbers and picked seeds
\nCompile a network into a map. Let its outputs open doors, flash lights or shove the marine. This runs as pasted:
\n\n\n\n# 2 inputs -> [a AND b, a OR b] -> 2 outputs, all integers\n = \n\n \n # computed by voodoo dolls; raises df.MismatchError on any difference from net.reference\n \n # film the dolls doing it\ndf.MLP.from_torch converts a PyTorch model (example 02). The world and actions hooks wire outputs to doors, lights and thrusts (example 03). Guide · 12 examples · Show and tell
One map runs in one game, on one core. df.run_many spreads inputs over many games, or over a Ray cluster. A network can also be split into tile maps, one per layer. Then Python copies values between them.
| run | \ndigits | \nright | \nexact | \ntime | \n
|---|---|---|---|---|
| one map, 14 games | \n1,000 | \n966 | \n1,000 | \n2 h | \n
| 4 tile maps, 6 games | \n10,000 | \n9,716 | \n10,000 | \n23 min | \n
\nBudget one core and 1.3 GB of RAM per game. Scaling
\n| what | \ntry | \nread | \n
|---|---|---|
| Faster schedules: MNIST in one map from 5,696 to 272 tics | \n--opt 3 | \nscheduling | \n
| A counter machine: 7 × 9 = 63 in 464 checked steps | \ndoomformer machine multiply 7 9 | \nmachine | \n
| A SUBLEQ machine with self-modifying code | \ndoomformer machine subleq all | \nmachine | \n
| A blank brain learns digits in the map: 71 % held-out | \ndoomformer learn digits | \nlearning | \n
| PyTorch import with BatchNorm, pooling and QAT | \nMLP.from_torch | \ninterop | \n
| A transformer that learned induction, exact in DOOM | \npython -m demos.induction | \ninduction | \n
| Patching, lesions and steering, checked in DOOM | \nintref.forward(interventions=...) | \ninterventions | \n
| Speed per pass and throughput | \ndoomformer bench | \nscaling | \n
Important
\n| Path | \nWhat it holds | \n
|---|---|
doomformer/ | \nthe toolkit: map compiler, DOOM runtime, exact checks, CLI | \n
demos/ | \nresearch code: the marine's brain, the level generator, the fly circuit, the learning arena | \n
training/ | \ntraining scripts for every model, with the data and sources | \n
models/ | \nevery trained model with its training log and evaluation | \n
examples/ | \ntwelve one-file examples, most under 15 s | \n
tests/ | \n496 tests; CI runs them against real headless DOOM on Linux and macOS | \n
docs/ | \nhow it works, every demo with its numbers, the engine facts, the guide, every command | \n
CHANGELOG.md | \nwhat each release added | \n
Code and docs: MIT. Data keeps its own licence (THIRD_PARTY.md). The level-name lists come from the Doom Wiki (CC BY-SA 4.0) and id Software's source (GPL-2.0). The 100 sample MNIST digits are CC BY-SA 3.0. The fruit-fly circuits in models/fly come from the FlyWire connectome (CC BY-NC 4.0, non-commercial). Freedoom graphics are BSD-licensed. DOOM is a trademark of id Software / ZeniMax. This project is not affiliated with them.