A playable, fully client-side DOOM that runs entirely in your web browser — no install, no backend, no accounts.
It bundles the doomgeneric engine compiled
to WebAssembly (a fork of the original LinuxDOOM 1.10 source port) together with
Freedoom: Phase 1 — a free, libre replacement for
the classic DOOM — so it plays out of the box with a real game. You can also load
your own legally-owned .wad IWAD at runtime via drag-and-drop or the file picker,
and your choice is remembered across sessions.
This repo is a thin shell, not a game. The hard part — the DOOM engine, the game data, the music instruments, the original 1993 game design — is other people's work, redistributed here under their own licenses. What lives here is about 600 lines of browser glue holding them together. See Credits.
The app is a static website — there is nothing to compile. Just serve the folder over HTTP and open it in a browser.
Option A — npm (recommended):
cd /path/to/Browser-DOOM
npm install # installs the tiny http-server dev dependency (or use any static server)
npm run dev # serves on http://localhost:8080Option B — Python (no Node needed):
cd /path/to/Browser-DOOM
python3 -m http.server 8080Option C — any static server (VS Code "Live Server", npx http-server -p 8080, etc.).
Then open http://localhost:8080 in a modern browser (Chrome, Firefox, Edge, Safari).
⚠️ Do not openindex.htmlby double-clicking it. The app is an ES module that loads the WebAssembly engine and WADs over HTTP; browsers blockfetch()and module loading on thefile://scheme, so the buttons would look "dead." If you open it that way, the page shows a message telling you to use a local server. Always serve fromhttp://localhost.
Click Play to start, or Load WAD… / drag a .wad onto the window to play a
custom IWAD.
- ✅ Fully client-side — the engine runs as WebAssembly in your browser; nothing is uploaded, and the game runs locally once the page is loaded.
- ✅ Ready to play — bundled Freedoom: Phase 1 (a complete, free replacement for DOOM's game data).
- ✅ Keyboard controls — move and turn with the arrow keys, fire, strafe, run, switch weapons, and use Doom's in-game menus. (The engine is keyboard-only; see Controls.)
- ✅ Runtime WAD loading — drag-and-drop or pick a
.wadto play any legally-owned IWAD (DOOM, DOOM II, Final Doom, Heretic, Hexen, FreeDM, Freedoom, …). - ✅ Persistent game selection — your chosen WAD is stored in IndexedDB and restored on the next visit; Use Freedoom returns to the bundled default.
- ✅ Fullscreen toggle and a lightweight HUD (FPS + current game name).
| Action | Control |
|---|---|
| Move forward / back | ↑ / ↓ |
| Turn left / right | ← / → |
| Strafe | Alt + ← / →, or , / . |
| Fire | Ctrl |
| Open / use | Space |
| Run | Shift |
| Switch weapon | 1 – 7 |
| Automap | Tab |
| Save / load game | F2 / F3 (current session only — see Troubleshooting) |
| In-game menu | Esc |
The mouse does nothing in this build, and neither does WASD. The engine is doomgeneric, whose entire platform input API is a single
DG_GetKey()callback — there is no mouse handling in it at all. Its key map covers the arrow keys, Ctrl, Space, Shift, Alt, Tab, Esc, Enter and F2–F11; letter keys fall through unmapped, and vanilla Doom does not bind WASD. Use the arrow keys.
- Click Load WAD… on the start screen, or drag any
.wadfile onto the window. - The page reloads and boots the game with your WAD; your selection is saved so it is used next time.
- Click Use Freedoom to clear your custom WAD and return to the bundled default.
Notes:
- Files are never uploaded — everything runs locally in your browser.
- Full-game IWADs (
.wadfiles starting with theIWADheader) are supported. PWAD files (mods/patches) and PK3/ZIP archives are not supported by this engine and are rejected with a clear message. - For best results use a retail IWAD named like
doom.wad/doom2.wad. The engine auto-detects DOOM, DOOM II, Final Doom, Heretic, Hexen, FreeDM, Freedoom, Hacx, Chex Quest, and Strife. Any other filename is treated as DOOM II.
| Requirement | Detail |
|---|---|
| Browser | A modern browser that supports WebAssembly and WebGL (Chrome, Firefox, Edge, Safari) |
| Server | Any static HTTP server (the app will not run from file://) |
| Node.js | Only needed for the optional npm run dev command; not required to play |
This is a thin web shell around an unmodified, prebuilt engine.
Browser (http://localhost:8080)
│
├─ index.html UI shell: boot screen, game screen, help screen
├─ style.css styling
├─ config.js paths to the engine + default WAD
└─ app.js bootstrap + logic
│
│ 1. resolve the WAD to use (bundled Freedoom, or a user IWAD
│ persisted in IndexedDB)
│ 2. seed the Emscripten Module (canvas, locateFile, onRuntimeInitialized)
│ 3. inject <script src="engine/doomgeneric.js"> → loads .wasm + .data
│ 4. on onRuntimeInitialized, write the chosen WAD into the engine's
│ virtual file system (FS_unlink / FS_createDataFile), then main()
│ auto-runs
│ 5. engine renders via SDL2 → WebGL onto <canvas id="canvas">
▼
engine/ doomgeneric (Emscripten WebAssembly, GPL-2.0)
doomgeneric.js Emscripten glue
doomgeneric.wasm compiled engine
doomgeneric.data GUS instrument patches (shareware IWAD removed)
public/
freedoom1.wad default game data (Freedoom Phase 1)
Key details:
- Engine bootstrap.
app.jsseedswindow.Modulewith the canvas, alocateFileoverride (so the glue finds.wasm/.datainengine/), and anonRuntimeInitializedhook. It then injects the engine<script>, which loads the WebAssembly + data package and auto-runs the engine'smain(). - WAD injection. The chosen WAD is written into the Emscripten FS using
Module['FS_unlink']/Module['FS_createDataFile']insideonRuntimeInitialized— which fires after the bundled data is loaded and just beforemain(), so Doom's IWAD search finds only the intended game. - No re-encoding. Freedoom and user WADs are streamed straight into the WASM FS as-is; nothing is converted.
- Persistence. The active WAD lives in IndexedDB and survives a reload; its bytes are re-validated on load. Nothing else persists — the engine's filesystem is in-memory (MEMFS), so anything it writes is gone when the page reloads.
- No threads / no COOP-COEP. The engine is single-threaded, so it works with any simple static server and needs no special HTTP headers.
There is no installer — this is a static web app, so "uninstalling" just means removing the folder and clearing browser-stored data.
Remove the project folder:
rm -rf /path/to/Browser-DOOMRemove the npm dev dependency (if you ran npm install):
cd /path/to/Browser-DOOM
rm -rf node_modules package-lock.jsonClear browser data the app created (the active custom WAD), per browser:
- Chrome / Edge: Settings → Privacy and security → Cookies and other site data →
find
localhost:8080→ Delete (also clears the IndexedDBbrowser-doomdatabase). - Firefox: Settings → Privacy & Security → Cookies and Site Data → Manage Data →
remove
localhost:8080. - Safari: Preferences → Privacy → Manage Website Data → remove
localhost.
No server processes, services, or background tasks are left behind — just stop the
one-off python3 -m http.server / npm run dev with Ctrl+C in its terminal.
/
index.html UI shell (boot / game / help screens)
style.css styling
app.js WAD handling, engine bootstrap, IndexedDB persistence, controls UI
config.js static paths to the engine + default WAD
package.json npm metadata + dev server script (http-server)
.gitignore
engine/ doomgeneric WASM engine (GPL-2.0 prebuilt)
doomgeneric.js Emscripten glue
doomgeneric.wasm compiled engine
doomgeneric.data GUS instrument patches (shareware IWAD removed)
LICENSE GPL-2.0 license for the engine
public/
freedoom1.wad default game data (Freedoom Phase 1)
docs/
screenshot.png
LICENSE MIT license for this wrapper project
THIRD_PARTY_NOTICES.md bundled third-party licenses
This project combines code and game data under different licenses.
- Wrapper (this repo's own code) —
index.html,style.css,app.js,config.js, docs: MIT (seeLICENSE). - Engine — doomgeneric WebAssembly build
of the LinuxDOOM 1.10 source port: GPL-2.0 (see
engine/LICENSEand the doomgeneric repository). Because the engine is GPL-2.0, redistributing it must comply with the GPL-2.0 terms. - Default game data — Freedoom Phase 1 (
public/freedoom1.wad): a permissive BSD-style license (copyright Freedoom contributors). - Music instruments — the Gravis Ultrasound patch set inside
engine/doomgeneric.data: packaged into the public domain by Simon Howard (fraggle), but the.patfiles themselves carry a 1992–94 Advanced Gravis / EYE & I Productions copyright with no explicit redistribution grant. Treat their status as unclear.
See THIRD_PARTY_NOTICES.md for the full text, the GPL-2.0 source offer, and
per-component notices.
Legal note. No id Software game data is distributed in this repository. The upstream doomgeneric build bakes id's DOOM shareware IWAD into its data package; it has been removed here, and the loader manifest adjusted to match. The 211 remaining files in
engine/doomgeneric.data(GUS instrument patches and Timidity configs) are byte-identical to upstream. SeeTHIRD_PARTY_NOTICES.md.Users may load their own legally owned WAD files at runtime; those files stay on the user's machine and are never uploaded.
Browser DOOM exists because of decades of work by other people. In rough order of how much of the thing you are actually playing they are responsible for:
- id Software — John Carmack, John Romero, Tom Hall, Adrian Carmack, Kevin Cloud, Sandy Petersen, Dave Taylor, Bobby Prince and colleagues — who wrote DOOM in 1993 and then, in 1997, released the engine source so that projects like this one could exist at all. DOOM and its trademarks remain theirs; this project is unaffiliated with and unendorsed by id Software, ZeniMax, or Microsoft.
- ozkl and the doomgeneric contributors — for the portable source port and the WebAssembly build that does all the real work here.
- The Freedoom contributors — the artists, level designers and composers who rebuilt an entire DOOM-compatible game from scratch so that ports like this have something legal and free to ship.
- Simon Howard (fraggle), with Tom Klok, Sebastien Bacquet and Jaydee — for packaging and configuring the GUS instrument patches that give the music its voice.
- The Emscripten project — for the toolchain that puts a 1993 C codebase in a browser tab.
- lofihippo — pieced together the wrapper, using DeepSeek V4 Flash 0731.
Buttons look "dead" / nothing happens on Play or Load WAD.
You almost certainly opened index.html via file://. Serve the folder over HTTP
(see Quick start) and open http://localhost:8080.
My saved game disappeared after I reloaded the page. Expected, for now. The engine's filesystem is in-memory only, so Doom's F2/F3 saves work while the tab is open but do not survive a reload. Making them persistent needs the engine rebuilt with Emscripten's IDBFS support.
How do I switch back to the bundled game? On the start screen click Use Freedoom.
A WAD I dropped in didn't load.
It may be a PWAD (mod) or a PK3/ZIP archive, which this engine doesn't support.
Use a full-game .wad with an IWAD header.
No sound? Click the page first (browsers require a user gesture before audio starts), then check OS/browser volume and that the tab isn't muted.
Does it need internet? Only to load the page and its assets once. After the page is loaded the game runs locally in your browser.
Tested on modern Chrome, Firefox, Edge and Safari. A browser that supports WebGL is required for the SDL2 renderer. There is no touch or on-screen control scheme, so a physical keyboard is needed to play — phones and tablets will load the game but cannot control it.
