DoomTape

KO | EN

gitlite — search

#nextjs #claude-code #html #python #automation #codex #swift #open-source #devops #redis

(★ 9)

Doom as weights: a bit-exact, differentiable Doom engine on a generic 34-op VM

File Explorer

ZIP Download

- doom_compilation.mp4
- first_frame.png
- compile_video.py
- make_aim_clips.py
- make_playthrough.py
- make_superpower_clips.py
- README.md
- run.lmp
.gitignore
COPYING
doom.npz
doom_music.py
doom_opl3.py
doom_opl3_fast.py
doom_tape.py
doom_tape_fast.py
FREEDOOM-LICENSE
lgpl-2.1.txt
NOTICE
NUKED-OPL3-LICENSE
README.md
requirements.txt
run_full.py

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Doom's engine, reimplemented so its entire computation runs as data. A fixed 34 op bytecode tensor VM executes the game; the VM contains no game logic, all of Doom lives in the weight tensors it reads. The representation is differentiable: one temperature parameter τ moves continuously between the exact discrete engine (τ=0) and a smooth surrogate (τ>0) that carries gradients, on the same weights.

[![DoomTape: gradient aim, rewritten physics, and nine forked games, all engine output](https://img.youtube.com/vi/cLeuiHb0sp8/sddefault.jpg)](https://www.youtube.com/watch?v=cLeuiHb0sp8)

**[Watch the full 45 second demo on YouTube](https://www.youtube.com/watch?v=cLeuiHb0sp8).** It shows gradient aim on four weapons, a physics rule rewritten in the tape, and forked game states. Every frame in it is engine output; [`video/`](video/README.md) rebuilds the whole thing from `doom.npz`, byte for byte.

## Motivation

This is the inverse of a learned world model. GameNGen (Valevski et al., 2024, arXiv:2408.14837) trains a diffusion model to predict Doom's frames; the result is approximate and drifts. Here the exact engine is compiled into weights instead: every frame is bit identical to the reference, and nothing is trained.

Ordinary code, branches and loops over mutable state, is opaque to both GPUs and optimizers. Expressed as tapes of weights over one recurring block, the same computation acquires the two properties of tensor programs: it batches, and it is differentiable. Doom is a demanding test case, a full real engine with a bit exact reference (Chocolate Doom) to check every frame against. The compilation was done by hand, for this one engine.

**Demonstrated here.** Control derived by gradient descent through the exact game: auto aim (worst residual 0.0026° over 12 targets, below the sine LUT's 0.044° resolution) and auto navigation, with no handwritten aiming or pathfinding. The τ dial is exact and differentiable on one set of weights.

**Enabled, not yet shown.** Batched rollouts of many game states for search or RL; objectives on rendered pixels backpropagated to inputs (needs more of the render path made differentiable, currently the discrete substrate); gradient based planning through the engine's own physics; execution on GPU or other tensor backends; exact replay and bit level verification from integer determinism. Open to demonstrating any of these.

## Run it

`doom.npz` (46 MB) is committed in this repository, so a plain clone is enough:

```bash
git clone https://github.com/OssiHarmaala/DoomTape.git
cd DoomTape && pip install -r requirements.txt
```

```bash
python run_full.py --play        # full game: title, menu, E1M1..E4M9, audio -- press B for gradient auto aim
python run_full.py --selftest    # headless; prints state and frame hashes
python run_full.py --gate-tau    # differentiability of the shipped VM (3300/3300 checks)
python run_full.py --diff        # τ on a real tape; one tic is ~9,400 differentiable value ops
python run_full.py --autoaim     # aim solved by gradient descent through the game
python run_full.py --autonav     # navigation, the same way
```

`numpy` and `numba` are needed by every entry point (the VM kernel is numba compiled); `pygame` additionally to play; `torch` only for the gradient demos. Runs on Windows x64, Linux, and macOS. Not Windows on ARM (no numba/llvmlite wheel).

## Rules and state are both arrays

A compiled engine hides both of the things a game is made of: its rules are spread through machine code, and its state is a heap graph. Here they are two plain int64 tensors, which is what the last third of the demo video shows.

* **A rule can be located and rewritten.** Friction is 4 cells of E1M1's 13,514 × 8 program tensor: the immediate operand of a `FIXMUL` at rows 6847, 6849, 7134, 7136 (x and y momentum, two call sites). Rewriting `0xE800` to `0xFAC8`, 20 bits out of the tensor's 6.9 million, turns the floor to ice, exactly and everywhere the rule applies.
* **A state can be forked.** The engine is a pure function of (state, input), so forking a game is copying an array. Six copies from one spawn give six exact rollouts of the same moment.
* **The program is invariant.** Nine simultaneous games are nine states over one unchanged tape.

## Verification

Bit exact against Chocolate Doom (reference C engine, skill 3), checked on every tic:

* 36/36 maps identical in position, angle, momentum, health, RNG, and weapon, about 3,000 tics per map, deaths and reborns included.
* Renderer: 448,000/448,000 pixels identical on the pose suite.
* Audio: 1,577/1,577 S_StartSound events matched; SFX PCM and the Nuked OPL3 music are sample identical.

## Scope

* Constructed, not trained. The weights are the engine's logic, compiled by hand. No dataset, no network.
* Not real time, about 10 to 16 fps on the numba kernel.
* Differentiable on the value path only (arithmetic, min, max, comparison, select). Gather, scatter, and branches stay discrete and exact for RNG order, so gradients flow where the arithmetic path connects.
* Per tic simulation is bit exact on all 36 maps; inter map progression is bit checked for Episode 1 only.
* Games run one at a time. Batched execution is a property of the representation, not something this build implements: the nine game grid in the video is nine sequential cartridges.

## License

GPLv2 (`COPYING`) for the engine logic, a Python reimplementation of Doom and Chocolate Doom. Nuked OPL3 port under LGPL 2.1+ (`NUKED-OPL3-LICENSE`, `lgpl-2.1.txt`). Freedoom Phase 1 assets, BSD style (`FREEDOOM-LICENSE`). No id Software `doom.wad` data is included.

DoomTape

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README