Doom WAD Lab

Browser WebGL2 renderer for classic Doom / Doom II IWAD maps, plus a KVX voxel viewer for Voxel Doom models.

Live demo

Production (after infra deploy):

• https://wadlab.computingandtooting.com
• https://wadlab.tootingandcomputing.com

Quick start

npm install
npm run dev

Open the dev server URL. Two modes:

Mode	Description
Level Viewer	Load a WAD, pick a map, walk around in WebGL2
Voxel Viewer	Preview Voxel Doom .kvx models (Three.js)

Release packages

Versioned release archives are built from package.json:

npm run package:release

The command runs the production build, writes dist/release.json, and creates releases/doom-wad-lab-v<version>+<sha>.tgz with a matching .sha256 file. GitHub Actions publishes a real GitHub Release with generated notes and those assets on v* tags. GitLab CI publishes a GitLab Release for tags and attaches the same archive/checksum plus deployment notes.

Release documentation

Detailed per-version notes live in docs/releases/. Regenerate them any time with:

npm run release:backfill

Before tagging a new version, append an entry to tools/release/version-manifest.json, regenerate docs, then push vX.Y.Z. See .cursor/rules/release-documentation.mdc for the full checklist.

Documentation

Full technical docs: docs/README.md

Complete technical bibles (gold standard)

Bible	What it covers
📖 Master index — docs/bible/	Hub linking both bibles, end-to-end data flow
WAD Bible	Every lump: container format, map records, palettes, sprites, switches, line specials, all 68 stock maps by episode
Classic Layer Bible	Layers panel → Node WebGL2 pipeline, live toggles, per-layer tests
GZDoom Renderer Bible	Vertices → BSP → walls → flats → sky → lights → sprites → GLES/WASM gold corpus
Classic Node/WebGL Renderer Chronicle	Dated progress log for the difficult pure Classic renderer conversion: verified wins, failed attempts, and remaining gaps

Guide	Topic
Testing	Vitest, parity suites, parallelization, CI checklist
WAD processing	Parse pipeline, workers, geometry, caches
MUS & music	MUS decode, MIDI conversion, SoundFont playback
Voxels	KVX format, VOXELDEF, in-game meshes
Rendering	WebGL2 vs original Doom, culling, sky
Visual enhancements	Lighting, slime glow, POM, transitions
Performance	Workers, React, caching, preload
Project history	How the app evolved from gl-doom-redo to production

Stack

Package	Role
React 19	UI — level viewer, loaders, transitions
Vite 6	Dev server & production build
apl-easy-gl	WebGL2 helpers & shader programs
gl-matrix	Matrices & camera
three	Voxel Viewer 3D preview
spessasynth_core	MIDI + SoundFont synthesis
earcut	Polygon triangulation
Vitest	Unit tests

Assets

Place files under public/:

public/wads/DOOM.WAD
public/wads/DOOM2.WAD
public/wads/test.wad          # bundled smoke-test WAD
public/voxels/SARGA.kvx       # Voxel Doom models (optional)
public/soundfont/TimGM6mb.sf2 # General MIDI SoundFont

Voxel metadata is bundled under voxel_doom/ (VOXELDEF + ZScript). Actual .kvx binaries are not in git — copy from a Voxel Doom install.

Controls (level viewer)

• WASD — move
• Mouse — look (click to capture)
• Tab — automap
• E / Click — use
• Esc — release mouse

Deploy

Hosting uses S3 + CloudFront + WAF with GitHub Actions OIDC. See infra/README.md.

Checks

npm run build
npm run test:unit
# Parity (needs IWADs + corpus artifacts):
npm run test:corpus && npm run test:modular

See docs/TESTING.md for the full command reference.

License

MIT — see LICENSE if present.