Lovingly reproduced from the Game Engine Black Book: Wolfenstein 3D by Fabien Sanglard.
How the Engine Was Built: Architecture and Startup
Lovingly reproduced from the Game Engine Black Book: Wolfenstein 3D by Fabien Sanglard.
The Wolfenstein 3D source code was uploaded to id Software's FTP server on July 21st, 1995. It fits in one directory. The total line count: 27,223 lines of code, of which about 90% is C and the rest assembly. For comparison, curl (the command-line download tool) is 154,134 lines. Chrome is 1,700,000. The Linux kernel is 15,000,000.
When the source was released, the response was overwhelmingly positive. John Carmack does remember one email that stood out: it pointed out a persistent typo in the code where "column" was spelled "collumn" dozens of times. The message was not politely worded.
Three Systems in a Trenchcoat
The engine is really three systems working together: a 2D menu renderer, a 3D game renderer, and a sound system. They communicate by sharing memory.
The 2D and 3D renderers are regular loops: process inputs, update the world, draw the frame, repeat. The sound system is different. Because the operating system had no concept of threads or processes, the only way to run audio concurrently with rendering was to use hardware interrupts. The sound system literally stops the CPU mid-frame, runs its own code, and then lets the CPU continue. Depending on what audio is playing, this happens between 140 and 7,000 times per second.
Seven Managers
The source code is organized in two layers. The high-level WL_ files handle game logic. Below them, a set of ID_ managers handle hardware interaction. There are seven:
The Memory Manager handles all conventional RAM, using a linked list of blocks rather than the standard malloc, which can lead to fragmented memory with no way to compact it. The Page Manager serves as a cache for 3D assets (textures, sprites, sounds), loading them from disk into RAM on demand and managing what gets evicted when memory fills up. The Video Manager abstracts VGA register manipulation. The Cache Manager loads and decompresses map data and 2D graphics from disk. The User Manager handles text layout for menus. The Sound Manager abstracts all four supported audio systems. The Input Manager handles keyboard, mouse, and joystick.
Startup: Signon Screen
The very first thing the engine does when it starts is show a diagnostic screen listing every piece of hardware it detected: how much RAM, whether EMS and XMS drivers are loaded, what sound card is present, whether a joystick is connected.
This was important. id Software was a small team with no customer support infrastructure. If a player's machine didn't have enough conventional memory, they needed to understand why. John Romero even wrote a separate help document (included in the appendices of this book) explaining what 640KB of conventional memory meant and why it might be "used up."
The signon screen is unusual in how it gets drawn. At startup, only the Memory Manager has been initialized. There is no filesystem access yet, no way to load assets from disk. So the signon screen bitmap (320x200 = 64,000 bytes) and the color palette (768 bytes) are compiled directly into the executable. DOS loads them into RAM along with the rest of the program. Once displayed, those 64,000 bytes are freed to make room for runtime data.
Solving the VGA Problem
Chapter 2 described the fundamental problem with VGA: neither Mode 12h nor Mode 13h supports double buffering, making smooth animation seemingly impossible.
The engine's solution was discovered and documented by Michael Abrash in Dr. Dobb's Journal in July 1991. Inside Mode 13h's VGA circuitry is a chip called Chain-4 that automatically routes memory writes to the correct bank. Disabling it gives the programmer direct control over all four VRAM banks and access to the full 256KB, instead of the 64KB that Chain-4 exposes.
Wolfenstein 3D disables Chain-4 but keeps the resolution at 320x200 rather than switching to the 320x240 square-pixel resolution that a full Mode-X setup would allow. The reason: 320x240 would mean 17% more pixels per frame, which the engine couldn't afford to render in time. This custom configuration, later dubbed "Mode-Y," divides the 256KB of VRAM into four sections: three framebuffers of 64,000 bytes each, and a fourth section for storing HUD graphics.
With three framebuffers, the engine draws into one while the screen displays another, and always has a third ready. This is triple buffering, and it completely eliminates tearing without ever having to wait for the screen to finish refreshing.
There's one more wrinkle. Switching which framebuffer the screen displays requires updating a 16-bit starting address in the CRT Controller, but the out instruction can only write 8 bits at a time. If the screen happens to refresh between the two writes, it reads a half-updated address and displays a mangled image. The engine avoids this by sizing each framebuffer so that consecutive pages differ only in their high byte, making the page-flip a single write operation.
The Rating Screen
After the signon screen comes a custom rating screen. The ESRB didn't exist yet (it was established in 1994, partly in response to the controversy Doom would cause). id Software rated the game themselves: PC-13, "Profound Carnage."