doom-on-github

Doom on GitHub

Play Doom on your GitHub contribution graph — a Chrome extension that compiles DoomGeneric to WebAssembly and renders every frame live onto the real contribution grid.

Install · How it works · Build from source · ABI spec · Privacy

Install

Get it from the Chrome Web Store.

Then on any GitHub profile: open the contribution graph’s Contribution settings menu (top right of the graph) and check Doom. The graph expands to a taller grid and a live game starts immediately — no setup, no save file, nothing to configure.

Prefer to run it from source? See Build from source.

How it works

Arrows move and turn, Ctrl fires, Space uses/opens doors, Escape pauses. Standard Doom controls — nothing GitHub-specific.
The game starts straight into E1M1 with monster respawning turned on, so a long-running tab stays lively instead of running out of demons.
Every GitHub contribution-graph color level (the 5 shades from “no activity” to “a lot”) maps directly to Doom’s rendered brightness, dithered to avoid hard banding at this resolution.
Toggling Doom off restores your actual contribution graph exactly as it was.

Architecture

Piece	What it does
`doomgeneric_github.c`	The DoomGeneric backend: owns the framebuffer, downsamples Doom’s 320×200 render to the graph’s resolution, and exposes a tiny C ABI (see `docs/SPECS.md`) for the JS host to drive.
`extension/src/doom/worker.js`	Runs the compiled WASM module in a dedicated Web Worker at Doom’s native 35Hz tick rate, off the page’s main thread.
`extension/src/doom/frame.js` + `engine.html`	A hidden iframe hosting the worker, relaying input in and frames out via `postMessage`.
`extension/src/doom/display-driver.js`	Expands the real contribution grid to the taller display size and paints each cell by setting its `data-level` attribute — the exact mechanism GitHub’s own CSS uses to color a real contribution square.
`extension/src/content.js` + `utils.js`	Finds the contribution graph’s settings menu and injects the Doom toggle into it.

Nothing is downloaded at runtime: the WASM binary, the shareware IWAD, and the Doom engine are all bundled in the extension. No network requests, no accounts, no data collected — see PRIVACY.md.

Build from source

Requires the Emscripten SDK on PATH.

emsdk_env    # or emsdk_env.bat / emsdk_env.ps1, from your emsdk checkout
make -f Makefile.emscripten clean
make -f Makefile.emscripten

This produces engine.js / engine.wasm at the repo root — copy both into extension/src/doom/ before loading the extension.

Load the extension locally: chrome://extensions → enable Developer mode → Load unpacked → select the extension/ folder.

Test the engine without the extension: serve the repo root (python -m http.server 8080) and open test/pipeline.html, which drives the exact same worker/iframe/input pipeline the real extension uses.

ABI

The C ↔ JS boundary is small and documented in full in docs/SPECS.md: a handful of exported functions (DG_Github_Init, DG_Github_Input, DG_GetFramebufferPtr, doomgeneric_Tick) and one flat framebuffer, one byte per cell, values 0–4 matching GitHub’s contribution levels.

Acknowledgments

DoomGeneric by ozkl — the portable Doom implementation this is built on.
id Software — for Doom, and for releasing the source.