Duke Nukem (1991) — a browser port

An HTML + vanilla-JS port of the original MS-DOS Duke Nukem (1991, Apogee/id Software — not Duke Nukem II or Duke Nukem 3D). It decodes the real game's original data files at runtime and reimplements the engine in JavaScript: no emulator, no transcoded assets, just the same worldalX.dnY levels, sprites, sounds and menus the DOS game shipped, read directly.

Play it in your browser → (needs your own copy of the game data — see What you need below). The same deployment also hosts the Asset Viewer.

This README covers using and playing it. For how the port was built and verified, see PLAN.md; for the reverse-engineered file formats, see FORMATS.md.

Special thanks

This port would not have been possible without the reverse-engineering work of others, used as the starting hypothesis for every decoder here (then verified against the real files — see CLAUDE.md and FORMATS.md):

• ModdingWiki — the community reference for the level, savegame, demo, tileset, sound and raw-EGA-image formats this game uses, plus the shared data types and the LZEXE compression the .exe files ship with.
• Lethal Guitar — a four-part deep dive into the engine internals themselves, not just the file formats: tile rendering, collision detection, and a two-part look at the mirror-floor and underwater graphical effects (part 2).

And, of course, Apogee Software and Todd Replogle for the original game.

What you need

This repository does not include the game data, and never will — Duke Nukem is copyrighted software. You need your own legally obtained copy of the original DOS game: Episode 1 ("Shrapnel City") was released as freely distributable shareware, so it's the easiest to obtain and try first; Episodes 2 and 3 ("Mission: Moonbase" and "Trapped in the Future!") were the commercial registered version.

The port reads the game's data files only — worldalX.dnY levels, .dn1/.dn2/.dn3 graphics/sound/tileset files, keys.dnY, and so on. It never reads or runs the .exe files, so you don't need DOS or an emulator, just the data.

Running it

npm install
npm run dev

Then open the URL Vite prints (typically http://localhost:5173). This starts a local dev server; nothing is uploaded anywhere, and none of your game files ever leave your machine.

Two pages are available:

• index.html (the root URL) — the actual game.
• viewer.html ("Asset Viewer →" link in the game's header) — a browsable inspector for every file the game ships, plus a level editor. See Asset Viewer below. Not needed to play.

Pointing it at your game files

The page needs to find your copy of the data files. Two ways, depending on how you're running it:

• Local development (the npm run dev server above): drop your game files straight into a game/ folder at the project root (create it if it doesn't exist). The dev server serves it directly and the page picks it up automatically — no folder picker needed. game/ is git-ignored, so this never risks committing copyrighted files.
• A built/deployed copy (npm run build, or someone else's hosted instance): the production build ships no game data at all, so click "Open game folder…" in the header and select the folder containing your files. This uses the browser's native folder picker (Chrome/Edge, and any other browser with File System Access API support — the button stays hidden on browsers that lack it, e.g. Firefox and Safari as of this writing). Your files are read locally by the browser; they are never uploaded.

Either way, point it at one folder containing all the files for whichever episode(s) you own — the same flat layout the original DOS install used (e.g. worldal1.dn1, duke1.dn1, anim0.dn1, keys.dn1, ... alongside worldal1.dn2, keys.dn2, ... if you also own Episode 2). The Episode dropdown in the header switches which episode's files it reads from that same folder — you don't need a separate folder per episode.

Playing

Controls

Movement defaults to the arrow keys; Fire and Jump come from whatever your copy's own keys.dnY file specifies (on the shipped shareware copy, that's Z to fire and X to jump). You can rebind any of the six actions in-game: F1 → G)ame Setup → K)eyboard mode, pick a slot (1–6), then press the new key. A gamepad also works out of the box — same menu, J for joystick mode, which reports connection status and lets you swap which button fires vs. jumps.

Getting started

The game boots through the same sequence as the original: the Apogee splash screen, the DUKE title screen (any key advances), then the DUKE MAIN MENU:

Key	Does
S	Start a new game (episode 1 shows the Dr. Proton taunt intro first)
R	Restore a saved game
I	Instructions
O	Ordering information
G	Game setup — sound, hints, keyboard rebind, joystick
H	High scores
P	Previews / Main Demo — watch the attract-mode demo play itself
V	View your own recorded demo (unlocks after you finish a level once)
T	Back to the title screen
C	Credits
Q	Quit

During play

Key	Does
F1	Help menu — S)ave, I)nstructions, G)ame Setup, H)igh scores, F10) Restart
P	Pause
S	Toggle sound
H	Toggle hint mode (re-arms or dismisses the one-shot "Secret Tip" hint boxes)
F10	Restart the current level from your last checkpoint (with a Y/N confirm)
Esc / Q	Quit to the main menu (with a confirm)
, / . (< / >)	Decrease / increase game speed — hold to sweep the full range

Saving

Saving is only offered at a hallway checkpoint between levels (F1 → S — matching the original, which only allowed saving there too), and the game auto-saves a checkpoint at every level transition regardless. Save data, key bindings, joystick swap, and high scores all live in your browser's local storage, keyed per episode — they persist across reloads on the same browser and device, but don't sync anywhere and don't touch your actual game files.

High scores

Beat one of the ten scores on the in-game High Scores table and you'll be prompted to enter your name, exactly like the original DOS game's name-entry screen.

Cheats

The original game shipped with hidden developer cheats. Two of them needed a secret argument typed after duke1/duke2/duke3 at the DOS prompt; this port's equivalent of that argument is a ?asp query string on the URL — e.g. http://localhost:5173/?asp.

Always available, during play, no ?asp needed:

Combo	Does
Backspace + Page Down (held together)	Full firepower and all keys
Backspace + G (held together)	Freezes the game — a leftover developer debug pause

Needs ?asp on the URL:

Combo	Does
G + O + D (held together, during play)	All items, full health, all keys, full firepower
G + O + W (held together, during play)	Instantly finish the current level
F6 while holding Fire, at the title screen	Start recording a new attract-mode demo tape

The F6 gesture is the same tool Apogee used to record the demo the game ships with — it starts a fresh game on the level the shipped demo plays out on. While recording, a "⏺ Save" button appears in the header; click it any time to download the tape as a real MY_DEMO.DN?/USERDEMO.DN? file, in the exact format the original game reads.

Asset Viewer

viewer.html browses every file format the original game uses, decoded and rendered directly — not a screenshot gallery, the actual bytes. Pick an episode, then pick an asset from the dropdown (grouped by category: Engine, Actors, Level Editor, Tilesets, Fonts, Backdrops, Full-screen art, Levels, Sound banks, Saves & config). Each asset is also deep-linkable — viewer.html#worldal1.dn1 opens that entry directly, so you can link straight to a specific level or sprite sheet.

It uses the same two ways of finding your game files as the game page (the local game/ folder in dev, or "Open game folder…" in a built copy) — plus one more, only here: drag and drop your game files (or the whole folder) straight onto the page. That works in every browser, including ones without the File System Access API, but read-only — dropped files can't be saved back to, only downloaded as copies (see the level editor below).

What's in it, briefly:

• Tilesets / Fonts / Backdrops / Full-screen art — the raw EGA graphics, decoded and rendered as PNGs you can zoom.
• Levels — a read-only map viewer: full 128×90 overview, or crop to what the in-game 320×200 viewport would actually show at a given position.
• Actors — every enemy/item/hazard sprite the level format can place, browsable by code, with its animation frames.
• Sound banks — the PC-speaker sound effects, playable in-browser.
• Saves & config — decoded key bindings, high-score tables, savegames, and recorded demos (rendered as an input timeline — one column per game cycle, one row per key).
• Engine — the actual game, embedded in the viewer for convenience.

Level editor

Select Level Editor for an episode to open a real level editor for the worldalX.dnY format — paint the same map codes the game reads, then save out a file the game (real DOS or this port) can load. The byte round-trip is checked by this project's own test suite against every shipped level, so what you export is a genuine level file, not an approximation.

• New blank level starts from an empty map; Open loads any shipped level from the dropdown, or Open file… loads a .dnY file from your computer.
• The palette has two tabs: Terrain (the four background/solid tilesets, click a tile to select it) and Objects (every enemy, item, hazard and interactive object the format supports, each with a thumbnail and description).
• Left click paints the selected tile; drag paints a run. Right click is an eyedropper — it picks the code under the cursor into the palette instead of painting. Multi-tile actors (e.g. the helicopter) still occupy one map cell; the cursor outline shows the full sprite footprint so you can see what will actually render.
• Undo / Redo (buttons, or Ctrl/Cmd+Z and Ctrl/Cmd+Shift+Z or Ctrl+Y), up to 100 steps. Scale, and toggles for actor sprites and the grid overlay, are display-only and don't affect the saved file.
• Download .dnY saves a copy through your browser's normal download. Save to folder… (only shown if you opened your game files with the folder picker, not drag-and-drop or the dev server) writes the file back in place, after a confirmation — this overwrites the original on disk, with no undo once it runs. The page also warns before you navigate away with unsaved changes.
• The map view is the same whole-level overview the read-only Levels viewer uses in overview mode, so — like that view — it can't show the backdrop: the backdrop is pinned to the in-game viewport, not the map, so there's no single correct way to render it behind a 128×90 overview. This doesn't affect what gets saved, only what you see while editing.

Compatibility

Playing works in any reasonably modern browser. The one feature that's Chromium-only (File System Access API) is the folder picker for a deployed/built copy — everything else, including the local-dev game/ folder approach above, works everywhere.

Fidelity

This is a from-scratch reimplementation, verified level by level against the original executable (disassembled) and against real captured frames from the DOS game running under emulation — not a guess at "close enough." It isn't a byte-for-byte guarantee against every possible edge case, but every format decoder and engine behaviour here was checked against the original, not assumed. See PLAN.md if you want the receipts.