docs: rewrite architecture documentation by uditmital-netizen · Pull Request #2 · Neosmith-ai/wolf3d

uditmital-netizen · 2026-07-19T09:40:59Z

Summary

Full rewrite of the docs/ tree from scratch, written by reading the source
in WOLFSRC/ directly and cross-checking each claim against
WOLFSRC/<file>:<line>.

What's included

ARCHITECTURE.md + README.md — top-level overview: what the code is,
directory layout, main loop, data-flow diagram, fixed-point model, coordinate
system, build system, and reading order.
8 systems/ guides — rendering, audio, input, game-logic, file-cache,
ui-menu, actordata, tools-build.
21 files/ per-file references — every WL_*.C and ID_*.C engine
module, each with role summary, key globals, function table (with line
numbers), and notes.
2 reference/ indexes — functions.md and constants.md.

Notes

Documentation only — no source or build files are modified, and nothing is
compiled.
Line numbers reference the tree at the tip of master.

🤖 Generated with Claude Code

This commit adds the full docs/ tree for the Wolfenstein 3-D source code reference. It was generated by reading the 1992 source in WOLFSRC/ at revision 0516778. New reference indexes (previously advertised but missing): - docs/reference/functions.md — every public function by file, with signature, source line, and one-line role. - docs/reference/constants.md — #define, enum, and .EQU constants grouped by 14 semantic families (limits, trig, tiles, scancodes, VGA registers, audio, paging, actor enums, etc.). Fixes to existing per-file notes: - docs/files/WL_DRAW.md: replaced ??? line numbers for ThreeDRefresh (1336) and PlayLoop (1368). - docs/files/WL_MAIN.md: corrected Scores[7] location to ID_US_1.C:57 (was WL_MAIN.C:???). - docs/files/WL_DRAW.md: removed a stray non-ASCII character. All previously dangling reference/ links now resolve. Co-Authored-By: Claude <noreply@anthropic.com>

Fixes from review: - ARCHITECTURE.md §6: corrected FINEANGLES from 28800 to 3600 (the source defines FINEANGLES=3600 in WL_DEF.H:105). - reference/constants.md: corrected DOORWALL (WL_DRAW.C:19, was :22) and ACTORSIZE (WL_DRAW.C:21, was :26). - files/WL_DRAW.md: same DOORWALL/ACTORSIZE line number corrections. Co-Authored-By: Claude <noreply@anthropic.com>

Full rewrite of docs/ from scratch by reading WOLFSRC/ directly: - ARCHITECTURE.md + README.md (top-level overview) - 8 systems/ guides (rendering, audio, input, game-logic, file-cache, ui-menu, actordata, tools-build) - 21 files/ per-file references (WL_*.C and ID_*.C modules) - reference/functions.md and reference/constants.md Describes the existing source only; no code or build changes. Co-Authored-By: Claude <noreply@anthropic.com>

uditmital-netizen

Code review — documentation accuracy

Great coverage, and the structure is consistent across all 33 files. I verified every FILE.C:line citation, function name, constant value, and internal link against WOLFSRC/. The scaffolding is solid; the issues below are factual errors about where functions live or how data is processed — the kind that send a reader to the wrong place. Recommend addressing the HIGH items before merge.

HIGH (flatly wrong):

WL_PLAY.md / WL_DRAW.md: PlayLoop is defined in WL_PLAY.C:1368, not WL_DRAW.C. WL_PLAY.C is a 1472-line file full of real definitions, not "declarations only."
WL_DRAW.md: wallheight[] is at line 42, typed unsigned wallheight[MAXVIEWWIDTH] — not line 102 / int[MAXWALLTILES].
WL_GAME.md: line 112 is SetSoundLoc, not ScanInfoPlane (which is at 221, declared 41).
systems/file-cache.md: map data is Carmack-then-RLEW (CA_CacheMap → CAL_CarmackExpand then CA_RLEWexpand), not Carmack-then-Huffman.

MEDIUM: enum line-ranges in constants.md (dir/stat_t/enemy_t), SpawnWill is at 1426 not 1450, ShowArticle is one #ifdef JAPAN function not two overloads, PollControls owner, Patch386 at 241, and a few prototype-vs-definition line cites.

LOW/nit: ThreeDRefresh/DrawScaleds cite the prototype/comment-banner line rather than the definition.

All internal markdown links resolve. Inline comments anchor each item.

uditmital-netizen · 2026-07-19T10:31:25Z

+a transverse header used by the renderer and gameplay stack to share
+a few constants and the `PlayLoop` prototype.
+
+The actual `PlayLoop` is implemented in `WL_DRAW.C` (which is


HIGH — factually wrong. PlayLoop is defined in WL_PLAY.C at line 1368 (void PlayLoop (void)), not in WL_DRAW.C. This page premise is inverted: WL_PLAY.C is a 1472-line file full of definitions (PollControls, TryMove, T_Player, etc.). Rewrite the title and "logic lives in WL_DRAW.C" line.

uditmital-netizen · 2026-07-19T10:31:25Z

+
+## Functions
+
+None defined here. `PlayLoop` is defined in `WL_DRAW.C`.


HIGH. PlayLoop is defined here (WL_PLAY.C:1368). "None defined here" is incorrect.

uditmital-netizen · 2026-07-19T10:31:25Z

+
+1. The 3-D **raycaster** — per-column wall drawing.
+2. The **scaled-shape** renderer (`DrawScaleds`).
+3. The **`PlayLoop`** function — gameplay per-tick.


HIGH. PlayLoop is not in WL_DRAW.C; it is WL_PLAY.C:1368. Line 1368 of WL_DRAW.C is inside ThreeDRefresh.

uditmital-netizen · 2026-07-19T10:31:25Z

+| `DrawPlayerWeapon`        | line 1201     | Draw B.J.'s held weapon on the screen                                                            |
+| `CalcTics`                | line 1236     | Tick rate measurement                                                                            |
+| `ThreeDRefresh`           | `WL_DRAW.C:1336`| Per-tick entry — orchestrates the renderer                                                       |
+| `PlayLoop`                | `WL_DRAW.C:1368`| Per-gameplay-tick loop — drives player + actor state                                             |


HIGH. Remove this row — WL_DRAW.C has no PlayLoop. It lives in WL_PLAY.C:1368.

uditmital-netizen · 2026-07-19T10:31:25Z

+| `viewx`, `viewy`    | line 58     | fixed — camera position                                                    |
+| `viewangle`         | line 59     | int — camera heading                                                       |
+| `viewsin`, `viewcos`| line 60     | fixed — sin/cos of camera heading                                          |
+| `wallheight[]`      | line 102    | int[MAXWALLTILES] — wall texture heights                                   |


HIGH. wallheight[] is declared at WL_DRAW.C:42 as unsigned wallheight[MAXVIEWWIDTH] — not line 102, and not int[MAXWALLTILES]. Line, type, and dimension symbol are all wrong.

uditmital-netizen · 2026-07-19T10:31:26Z

+## Notes
+
+- `text` is a global parse cursor mutated by `ParseNumber`/`RipToEOL`/`HandleWord`; the parser is stateful and single-pass per page.
+- There are two `ShowArticle` overloads (lump index vs. raw string) sharing the same layout core — the string form powers help screens loaded from `HELPART.`.


MEDIUM. Not two overloads — C has no overloading. Lines 599/601 are the #ifdef JAPAN / #else signatures of a single ShowArticle; only one compiles per build (the char far * form in non-JAPAN builds). Reword as build variant.

uditmital-netizen · 2026-07-19T10:31:26Z

+
+## Relationship to the game loop
+
+`WL_PLAY.C::PollControls` (per tick) asks the Input Manager for the current


MEDIUM. PollControls is declared in WL_DEF.H:923 and called from WL_DEBUG.C, but its definition is not in WL_PLAY.C in this tree — verify the owning file before asserting WL_PLAY.C::PollControls.

uditmital-netizen · 2026-07-19T10:31:26Z

+| `ReadConfig`              | `WL_MAIN.C:90`     | Read `CONFIG.<ext>` from disk into the global config state                                      |
+| `WriteConfig`             | `WL_MAIN.C:193`    | Write the global config state back to `CONFIG.<ext>`                                            |
+| `JHParmStrings[]`         | `WL_MAIN.C:240`    | Static `{"no386", nil}` parser string list                                                      |
+| `Patch386`                | `WL_MAIN.C:243`    | Sniff the CPU; sets `IsA386` via the `JABHACK.ASM` glue                                          |


MEDIUM. Patch386 is defined at WL_MAIN.C:241; line 243 is extern void far jabhack2(void);.

uditmital-netizen · 2026-07-19T10:31:26Z

+
+## The raycaster (`WL_DRAW.C`)
+
+`ThreeDRefresh()` (`WL_DRAW.C:72`, the entry point called once per tick from


LOW/nit. WL_DRAW.C:72 is the prototype; the ThreeDRefresh definition is at 1336. Cite the definition (the text already says "defined near the end").

uditmital-netizen · 2026-07-19T10:31:26Z

+   simplification that gives Wolf3D its right-angle-only geometry.
+4. `TransformActor()` (`WL_DRAW.C:210`) rotates each visible actor into view
+   space so it can be depth-sorted and scaled.
+5. `DrawScaleds()` (`WL_DRAW.C:1054`) walks the transformed, depth-sorted list


LOW/nit. WL_DRAW.C:1054 is the = DrawScaleds comment banner; the definition is at 1072 (which WL_DRAW.md cites correctly).

Udit Mital and others added 3 commits July 18, 2026 15:09

uditmital-netizen commented Jul 19, 2026

View reviewed changes

Navigation Menu

Uh oh!

docs: rewrite architecture documentation - #2

docs: rewrite architecture documentation#2
uditmital-netizen wants to merge 3 commits into
masterfrom
docs/rewrite-architecture

uditmital-netizen commented Jul 19, 2026

Uh oh!

uditmital-netizen left a comment

Uh oh!

uditmital-netizen Jul 19, 2026

Uh oh!

uditmital-netizen Jul 19, 2026

Uh oh!

uditmital-netizen Jul 19, 2026

Uh oh!

uditmital-netizen Jul 19, 2026

Uh oh!

uditmital-netizen Jul 19, 2026

Uh oh!

uditmital-netizen Jul 19, 2026

Uh oh!

uditmital-netizen Jul 19, 2026

Uh oh!

uditmital-netizen Jul 19, 2026

Uh oh!

uditmital-netizen Jul 19, 2026

Uh oh!

uditmital-netizen Jul 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant


		## Functions

		None defined here. `PlayLoop` is defined in `WL_DRAW.C`.


		## Relationship to the game loop

		`WL_PLAY.C::PollControls` (per tick) asks the Input Manager for the current


		## The raycaster (`WL_DRAW.C`)

		`ThreeDRefresh()` (`WL_DRAW.C:72`, the entry point called once per tick from

Uh oh!

Conversation

uditmital-netizen commented Jul 19, 2026

Summary

What's included

Notes

Uh oh!

uditmital-netizen left a comment

Choose a reason for hiding this comment

Code review — documentation accuracy

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant