This is the developer-facing documentation set: architecture, game-design rationale, and a themed reference of notable design decisions. It's written for contributors and future-self, not players — for the pitch and quick start, see the top-level README.md; for the player manual, see doc/user.
These docs are a curated, evergreen reference — they describe current rules and rationale, not a chronological history. The notes file at the repo root is the raw, ongoing backlog of open work; the chronological record of completed work lives in history.md.
Which file a thing belongs in comes down to the question it answers:
| question | file |
|---|---|
| "why is the code like this?" — a choice that still governs the code, including a choice not to do something | decisions.md |
| "what happened, and what did it cost?" — completed work, and approaches measured and reverted | history.md |
| "what still needs doing?" | notes |
The middle one matters more than it looks: a reverted approach leaves no trace in the code — the code is precisely where it isn't — so without a written record the next person re-attempts it.
- Architecture — the
fs → parser → map → enginepipeline and the hard rules that keep it that way - Game Design — why source code maps to a dungeon the way it does, and the intent behind enemies, weapons, and scoring
- Design Decisions — a themed reference of notable tradeoffs and reversals, citing
notestask numbers for full detail - Development History — the chronological record of completed work, and the approaches that were measured and reverted; moved out of
notesso that file stays a working backlog - WAD Texture Packs — which lump names the game looks for in a DOOM WAD, per styleset and per gameplay-signal slot; what a WAD must contain to work as a texture pack; the fallback chain, the format limits that silently drop a slot, and how to check a pack with
report:wad-stylesets - Testing — the Vitest unit-test suite: setup, shared mocks, mocking philosophy, reusable techniques, how to run the verify scripts locally, what the suite structurally cannot catch, and the documentation-screenshot capture — the one script whose output is committed, plus the staging test hooks it needs and why the bot must never use them
- Adding a Weapon — the touchpoint checklist for a new weapon; most of them are hardcoded enumerations, and the ones that fail silently (the playtest bot's mirrored weapon table especially) are called out per step
- Adding a Language — the same for a new parser: the mandatory grammar-ABI vetting gate, and the shared vocabulary tables where a missing language loses a whole map feature without erroring
- Multiplayer Server Deployment — step-by-step runbook for standing up the signaling server, the client build, and the optional coturn TURN relay, natively or via the
docker/stack - Balancing Telemetry Bot — the automated bot-driven balance-review/regression tool: entry points, profiles, env vars, and the headed-vs-headless timing gotcha
- Lane Orchestration — the contract for the scheduler that spreads a capture across several machines you own: what a consumer must supply, what it guarantees, the invariants that make its lock-free claiming safe, and which parts are genuinely generic versus tuned to this workload. Lives next to the code so it travels if the scheduler is ever extracted
- Capturing Another Campaign — the runbook for measuring balance on some other body of code (a GitHub project, a folder under
~/sources): why the offline solver already handles any directory while the bot is pinned todemo-campaign/, how to stage one so all three level-enumeration rules agree, what a real sweep costs, and the traps that have each eaten a run - Multiplayer Research — the 2026-07-18 feasibility pass that decided multiplayer's shape before any of it was built: the privacy analysis, the no-backend filter and where it broke, short-code-vs-QR, and the measured cross-browser determinism result. Historical rationale, not current behaviour — the four specs below supersede it wherever they disagree
- Multiplayer Specs — the four documents behind the multiplayer implementation, all marked implemented and CI-verified. They are specifications rather than guides, and are the place to look when changing netcode behaviour rather than using it:
- Signaling + lobby server — the one piece of backend that turned out to be unavoidable: a minimal WebRTC signaling mailbox plus the lobby feature
- Netcode — the lockstep layer sitting above the single-player
RaycasterEngine - Game-state adaptation — the
simulate()/render()/advance()split, the N-player model, player-count elite scaling, and coop revive - Balancing & telemetry automation — the multiplayer arm of the telemetry bot (see balancing-telemetry.md for the day-to-day reference)
- Performance Tooling — the
?perfDebug=1frame diagnostics, theperf:bench/perf:reportbenchmark harness, and the measurement gotchas from the 2026-07 audit
Point-in-time audit reports, kept for their evidence rather than as current reference — the evergreen docs above supersede them wherever they disagree.
- Performance review, 2026-08-02 — the frame-time audit that found the real draw-call cost class, including two earlier wrong mechanisms it retracts
- Code review, 2026-08-03