Saturday, August 31, 2024

Doom Code WalkThru

Doom is a First-Person Shooter developed and published by id Software in December 1993. Doom is the first franchise installment and one of the most widely ported video games since the code was released Dec-1997.

Let's check it out!

Ports
In order to better understand the Doom source code we would like to debug step thru both the Doom port PrBoom on Linux and the Doom port DoomRetro on Windows written in C using modern-day software tools:
 Linux  PrBoom  Cross-platform version of Doom ported to Linux
 Windows  DoomRetro  Classic refined Doom source port for Windows PC

WAD Files
WAD is the acronym for "Where's All the Data?" which is the file format used by Doom and all Doom engine-based games for storing data. A WAD file consists of a header, a directory and the data lumps that make up the resources stored within the file. A WAD file can be one of two types: an Internal WAD or a Patch WAD:

 IWAD   Internal WAD   Core WAD file loaded by engine that provides all data required to run game
 PWAD   Patch WAD   Optional file that replaces IWAD data and provides additional data to engine
According to doomwiki there is List of notable WADs available to download beginning with Doom1.wad etc.

Doom Bible
The Doom Bible is the original design document which includes the specifications for the WAD file format structure that initiated an incredible modding scene in which fans created their own WAD files containing new levels commonplace for first-person shooter games! Now let's debug step thru Doom C source code.

PrBoom
PrBoom is a cross-platform version of the classic 3D first-person shooter Doom from id Software. PrBoom has since been ported to Linux and many other platforms. PrBoom requires the original IWAD data files.

Follow this YouTube video to setup PrBoom in VS Code and build and debug step through the source code! Launch Terminal. Install the following Linux packages as PrBoom pre-requisites, if not currently installed:
 sudo apt-get install libghc-opengl-dev
 sudo apt-get install libghc-sdl-dev

Download prboom-plus-2.5.1.3 from sourceforge.net. That is the link that seemed to work OK for me. Launch Terminal. Execute following commands to extract source code, configure, build and run PrBoom:
 tar -xvf prboom-plus-2.5.1.3.tar.gz
 cd ~/prboom-plus
 chmod +x configure
 ./configure
 make
 chmod +x src/prboom-plus

If you get the following configure: error: *** You must have the SDL libraries installed before you can compile prboom *** See http://prboom.sourceforge.net/linux.html then install the following packages:
 sudo apt-get install libsdl1.2-dev
 sudo apt-get install libsdl-mixer1.2-dev
 sudo apt-get install libsdl-net1.2-dev

Copy all files from the DoomCodeWalkThru Files directory to the local hidden directory ~/.prboom-plus
 cp ~/GitHub/SteveProXNA/Doom/Files/* ~/.prboom-plus

Launch VS Code. Create build shell script, hidden .vscode directory with tasks.json and launch.json files
 tasks.json  launch.json
 {
     "version": "2.0.0",
     "label": "build",
     "type": "shell",
     "linux": {
         "command": "./build.sh"
     },
 }
 {
   "version": "0.2.0",
   "configurations": [
     {
       "name": "(gdb) Launch",
       "type": "cppdbg",
       "request": "launch",
       "program": "${workspaceFolder}/src/prboom-plus",
       "args": [
         "-iwad",
         "Doom1.wad"
       ],
       "stopAtEntry": false,
       "cwd": "${workspaceFolder}",
       "externalConsole": false,
       "MIMode": "gdb",
     }
   ]
 }

Open i_main.c. Set breakpoints. Press Ctrl+Shift+B to build and F5 to debug step through source code!

IMPORTANT - the first character of IWAD file must be I not P otherwise may get an "IWAD not found" error.

CRITICAL - specify the arguments -iwad and WAD file e.g. Doom1.wad otherwise you will encounter error:
 M_LoadDefaults: Load system defaults.
  default file: ~/.prboom-plus/prboom-plus.cfg
   found ~/.prboom-plus/prboom-plus.wad
 
 prboom-plus v2.5.1.3 (http://prboom-plus.sourceforge.net/)
 I_SetAffinityMask: manual affinity mask is 1
 IdentifyVersion: IWAD not found

Keys

 F1 Help
 F2 Save game
 F3 Load game
 F4 Sound volume
 F5 Change HUD
 F6 Save game
 F7 End game
 F8 Message toggle
 F9 Quick load
 F10 Quit application
 Escape Menu back
 Enter Menu forward
 
 Home Restart game
 Tab Map
 0-9 Change weapons
 Left arrow Rotate left
 Right arrow Rotate right
 Up arrow Move forward
 Down arrow Move back
 Ctrl Shoot
 Space Open door
 < Strafe left
 > Strafe right
 / Rotate 180
Note: F11 does Gamma correction. Also, re-copy Prboom-plus.cfg and Prboom-plus.wad to reset HUD.

The YouTube video shows some examples how to hack the d_englsh.h to make custom text and sounds!

DoomRetro
Doom Retro is the classic, refined Doom source port for Windows PC. Written in C, Doom Retro source code is maintained in doomretro Git repository and regularly compiled for both 32 and 64-bit using Visual Studio.

Launch Visual Studio 2022. Open doomretro.sln. Choose Debug | 32-bit. Right click Solution and Rebuild. Ensure the Platform Toolset is Visual Studio 2022 (v143) in the project Properties | Configuration Properties.

Open doomretro.c. Set breakpoints. Press Ctrl+Shift+B to build and F5 to debug step through source code! The function D_OpenWADLauncher() will prompt WAD file selection. Choose a WAD file from Files directory.


Keys

 F1 Help
 F2 Save game
 F3 Load game
 F4 Sound volume
 F5 Graphics toggle
 F6 Save game
 F7 End game
 F8 Message toggle
 F9 Quick load
 F10 Quit application
 Escape Menu back
 Enter Menu forward
 
 Tab Map
 0-9 Change weapons
 Left arrow Rotate left
 Right arrow Rotate right
 Up arrow [W] Move forward
 Down arrow [S] Move back
 Ctrl Shoot
 Space Open door
 A or < Strafe left
 D or > Strafe right
 Caps Lock Always run toggle
 Back Tick Console commands

Commands
Press the back tick [`] key prompts the Console Commands dialog box. Here are some useful commands:
 clear Clears console
 cmdlist Lists all commands
 god Toggle God mode
 health 100 Set health = 100%
 playerstats Shows player stats
 quit Quit application
 
 maplist List all maps to play
 map E1M7 Warp to map E1M7
 playerstats Shows player stats
 restartmap Restart current map
 newgame Start new game
 endgame End the game


Documentation
The Game Engine Black Book: DOOM book is excellent reference material which goes into great depth about the development process of Doom in 1993. Masters of Doom documents the history of id Software and goes into great depth about development of many id Software franchises leading up-and-including Doom success.

Summary
To summarize, we have now setup Doom ports on both Linux and Windows computers to debug step through and better understand the source code. While this has been a fun and nostalgic exercise, many believe that this is crucial that Software Developers should review influential source code: rather than repeat the same past mistakes, we should study great works that preceded us and learn from and build upon their lessons.

Another motivation to study classic video game source code is their relevance to modern day AI topics such as Reinforcement Learning. For example: VizDoom allows developing AI bots to play Doom using only visual information. Hosted by The Farama-Foundation VizDoom allows creating environments based on the Doom engine. The library provides Python API wrappers for the OpenAI Gym / Gymnasium interface and provides an excellent opportunity to research machine visual learning and deep reinforcement learning in the future!

No comments:

Post a Comment