The Dark Mod - Compilation Guide

This guide should provide you with enough information to compile The Dark Mod's game code from source.

The sources are available through "snapshots", i.e. whenever the Dark Mod team is releasing a new update (e.g. TDM 1.01) the corresponding sources are released as well.

Download the sources

You can download the latest source package from our website: http://www.thedarkmod.com/download_source.php

Windows

For Windows you'll need Visual Studio to compile the project, you can get the free Express editions from the Microsoft website. It should work with every version starting from VC++ 2005 upwards, although I'd recommend the VC++ 2008 one. If you go for the older VC++ 2005, you'll need the Platform SDK as well, which is another large download. You don't need a Platform SDK for VC++ 2008.

Download the sources and unpack them somewhere. You'll find a d3game.sln solution file (which is in VC++ 2005 format), which you can double-click to open in Visual Studio. The newer VC++ 2008 will present you an upgrade wizard to convert the solution to 2008.

Once opened, select the Configuration Type in the topmost toolbar (either "release" or "debug", depending on what you want to do) and hit "Build Solution" (Ctrl-Shift-B). The compilation usually takes a few minutes, watch the output window at the bottom of Visual Studio. Once completed, you'll find the compiled gamex86.dll in a subfolder named "releasedll" (for release builds" or "debugdll" (for debug builds).

In order to "install" the gamex86.dll, you need to copy it somewhere where Doom3.exe can find it. There are two ways to do that: either you place the dll right next to your DOOM3.exe which will override any other mechanism (the game will always load the DLL right next to DOOM3.exe first), or you put them in a PK4 (along with a binary.conf file) and place it in your mod folder. There is some info on www.iddevnet.com/doom3 about how to do that.

Debugging the Game

To debug your custom built game code, you need to attach Visual Studio's debugger to the Doom3.exe process. There are two ways to accomplish that:

The quick one:

1. Go to Visual Studio and open the d3game solution
2. Start the game (either through tdmlauncher.exe or through DOOM3.exe plus command lines)
3. Once the game is up and running, Alt-Tab back to Visual Studio
4. Go to menu "Debug" > "Attach to Process..." and select the DOOM3.exe process from the list in that dialog popping up.
5. The debugger will now attach to Doom3 (along with all loaded DLLs) and you can now place breakpoints or intercept game crashes.

The longer one (if you debug your game more than once or twice):

1. Go to Visual Studio and open the d3game solution
2. Right-click the Solution in the "Solution Explorer" and select "Add" > "Existing Project..."
3. Browse to DOOM3.exe and select that, you'll see the DOOM3.exe project added to your solution explorer view.
4. Right-Click the DOOM3.exe and choose "Select as startup project".
5. Now you can start the debugger just by hitting F5 and Visual Studio will automatically attach to the Doom3 process.
6. [Optional]: You can specify command line parameters to Doom3.exe by opening the Doom3.exe project properties and adding the desired parameters (e.g. com_allowConsole or fs_game_base/fs_game) to the "Command Arguments" item. This is necessary if you want to debug a specific TDM mission (although in this case, employing the "quick" method above is easier).

Note: you can still attach your debugger to any running DOOM3.exe process with the second method.

Troubleshooting

My breakpoints don't work (they are hollow circles instead of full ones)

Check if you copied the correct gamex86.dll to the folder where DOOM3.exe is located. The code you're viewing and the DLL loaded by DOOM3.exe must match exactly, otherwise Visual Studio won't load your symbols. Make sure that the configuration type (release or debug build) is matching as well. Also make sure that the code is properly compiled, e.g. hit "Build Solution" again - the output window should tell you that everything is up to date.

I cannot inspect all the variables / The instruction pointer is skipping code

You are probably running a release build, which comes with some optimisations. When debugging a release build, you'll notice that your instruction pointer (the yellow arrow) is sometimes skipping statements. These have most likely been optimised out of the binary during compilation/linking. You'll also have troubles when trying to inspect temporary variables or inlined functions. Use a debug build if this prevents you from figuring out things during debugging.

Linux

For Linux you'll need gcc and scons, plus a few packages depending on your distribution. There is a README.linux file contained in the source package you downloaded, check it out for some details.

I have a bugfix for the team

In case you figured out a problem in the TDM game code and you maybe even have a fix available, please drop by at our forums to tell the coding staff. Your fix might be incorporated in the main development branch.

Additional Info about the TDM Code

The Dark Mod codebase is quite large in the meantime and we have reorganised and refactored/replaced a great number of things. There are a few things which haven't changed too much (like the animation code), but most gameplay code has been altered to fit TDM's needs.

Additionally, the TDM code relies on a few static libraries which are not required in the vanilla D3 code, see below.

Boost Libraries

TDM's code is using boost libraries. Most boost libraries we're using are header-only (i.e. they work without special linking), with the exception of boost::filesystem. The latter requires a static library to be built for your OS and linked into the game code. For Windows the source package you downloaded already contains the correct binaries for VC++ 2005 and VC++ 2008 in both release and debug flavours. They can be found in the win32\lib folder.

ZipLoader

For the FM installation code, we made use of the minizip/zlib sources. For Windows and Linux the package already comes with the correct static .lib and .a files, so this should work out of the box. In case you need to compile these libraries from scratch (e.g. for a newer compiler or a different OS) there is a .vcproj file available in win32\ziploader (Windows) or a sconscript in sys/scons/Sconscript.ziploader. Use these to compile a new static library and make sure the library is referenced by the d3game project.

DevIL

Our lightgem code makes use of some image processing routines, which are contained in the open source DevIL package. The correct static library is already contained in the source package you downloaded, hence it should work right out of the box. In case you need to compile that library from scratch (applies to Windows only, Linux users will just need to download the correct package from their repositories), there are the DevIL sources in win32/devil, including a vcproj file, which you can use as basis.

TDMLauncher

The Dark Mod comes with a custom launching app named tdmlauncher which makes mission installation/uninstallation easier for players. The source code for the tdmlauncher is contained in the source package linked above, head to the folder dmlauncher/ where you'll find a Visual Studio solution file as well as a sconscript.tdmlauncher. TDMLauncher is making use of boost::filesystem, that's why there is a separate lib/ folder in there as well (for Linux only). See above for info about the boost libraries.

How to compile the boost static libraries in Windows

Any VC++ compiler version other than VC++ 2005 and VC++ 2008 will require a recompile of the boost static libraries which The Dark Mod links against. At the time of writing, TDM is using the following boost libraries:

• boost.filesystem
• boost.system

To build these static libraries, boost provides the jam tool (bjam.exe), which can be used to build the statics for you. Go get the boost sources from their website (http://www.boost.org) and extract them into a new folder. Then get bjam (can also be downloaded from their website, but you can also build it from scratch), open a console (Win-R ==> "cmd" => Enter) and head to:

cd <YOUR BOOST FOLDER HERE>
cd libs
cd filesystem
cd build
bjam --toolset=msvc link=static release stage
bjam --toolset=msvc link=static debug stage

After these commands, the libboost_filesystem_vc*.lib files (both debug and release variants) are in the stage/ directory below your boost folder. You'll need to repeat the above steps and replace filesystem with the names of the other libraries regex and system.

Now take the *.lib files and copy them into your win32/lib folder in your source directory and the linking should succeed.