Tutorial: My First Mod
It's 2010. Almost 11 years after Quake 3 was first released. I'm writing a tutorial about making your first mod for Quake 3. It's a bit late for that, maybe. After 11 years, interest in creating new mods for Quake 3 has dropped to an all time low and very few people are probably interested in creating Quake 3 mods. So why am I still writing this tutorial? First, mostly for myself. It took me some time to figure all the stuff that's in here out and writing it down is a good way to remember it. Also, Quake 3 is probably one of the last games that have a low entry level of content creation. Maps, models, textures... it's all still relatively accessible whereas newer games like Doom 3 or Unreal Tournament 3 require quite a lot more work and technical knowledge to create simple things like textures or basic maps. Additionally, Quake 3's rule set is pretty straight forward. Because of this, complex game rules and gameplay mechanisms don't obfuscate the code that's behind those rules. Last but not least, Quake 3 is still relatively popular (even more so with Quake Live, although that won't do us much good when creating mods). There are still some hardcore mappers and modders out there. Quake 3 is also old enough that it runs very smoothly on most people's computers.
Quake 3 also has some downsides. The code is ANSI C, which is a third generation language, which means that compared to more modern (object oriented) programming languages such as Java, PHP and C#, it's all a bit rougher around the edges. The Quake 3 sourcecode is also not the best set up package to download. It requires some preparation before it's actually workable. Because properly setting up the source code is something that can take a while if you're trying to figure it out by yourself, I've written it all down in this tutorial. But to make things better, I'm also going to explain to you exactly how the Weapons of Fury: Reloaded mod was made. The compiled version of this mod is offered elsewhere on our website, but it's complete sourcecode is available as well. Once you're done with this tutorial, you'll have coded your own version of the Weapons of Fury: Reloaded mod.
In this tutorial I will assume that you have some basic knowledge of the C programming language and that you know how to set up your own IDE. I will be working in Visual Studio 2008, for which installation instructions will be included in this tutorial. If you use a different IDE, I'm sorry, you're on your own.
Downloading and setting up the sourcecode
There are various sources from where the sourcecode can be downloaded, but the safest place is id Software's own FTP server. This is located at ftp.idsoftware.com. Your browser might be able to understand that link allowing you to directly download the file. If not, point your favorite FTP client to ftp.idsoftware.com and log in as anonymous user. The file you need is located in idstuff/quake3/source and is called Q3A_TA_GameSource_132.exe. That location also contains a Linux version of the file, but that won't be covered by this tutorial.
After downloading the installation file, install it to your harddrive to a location of your choice. In the installation folder you'll find five folders:
- \bin: this contains a number of compiler's we'll need when generating qvm files (more on that later).
- \code: Contains all the source code we're going to edit.
- \lcc: Contains the sourcecode for the lcc compiler, which we won't cover in this tutorial.
- \q3asm: Contains the sourcecode for the q3asm compiler, which we won't cover in this tutorial.
- \ui: Contains menu files which are also outside of the scope of this tutorial.
The first and probably very important step is to make a copy of the \code folder to another location as backup. It's always handy to have a copy of the unedited code available. If you're using a source control system like SVN or Git then that's even better.
You'll find that there's a .dsw file in the \code folder. Double click this file or open it in Visual Studio. If you're using a newer version of Visual Studio such as Visual Studio 2005 or 2008 then it'll prompt you that it wants to convert the project files to the new VS200x format. Let it do this.
Visual Studio will most likely complain that a "missionpack" related file cannot be found. Ignore this error and tell Visual Studio to remove all source control bindings if it asks you about this. Once it's done, close Visual Studio saving all changes.
VS will have generated a .sln file. That's a recognizable filetype for most Visual Studio users. Double click it to open it in Visual Studio. You'll find that there's 4 projects loaded in this solution. More details on that later. First, go ahead and right-click the "ui" project and select "unload project". This will exclude the project from being built and is necessary as the "ui" project will throw errors during compile time. It is not needed to build the source.
VS offers a number of build targets: Debug, Debug Alpha, Debug TA, Release, Release Alpha, Release TA, vector. So far I've only built to a release target. The debug targets will allow for debugging. The TA debug/release target will include missionpack code. Select "Release" for now. Now it's time to build the code. Select the Build Solution option from the Build menu. Your code will now be built. There may be a large number of warnings (about the use of unsafe functions) but as long as no errors are displayed, everything is fine.
The output of the compiler can be found in the \code\Release folder. There will be three dll files: cgamex86.dll, qagamex86.dll, uix86.dll. These are now the compiled binaries that form your mod. To test if things work correctly, you can create a test mod folder in your Quake 3 folder. To do this, go to your Quake 3 folder (the one containing quake3.exe and the baseq3 folder) and create a new folder in there. Give it an appropriate name (I'll go for testmod) and place your three dll files in there. Now copy over the q3config.cfg file from your baseq3 folder to your testmod folder as well. Open the q3config.cfg file using a text editor and locate the following lines:
seta vm_ui "2" seta vm_game "2" seta vm_cgame "2"
The values in your q3config.cfg might be set to 1 instead of 2, but in both cases, they must all be set to 0, like this:
seta vm_ui "0" seta vm_game "0" seta vm_cgame "0"
This will stop Quake 3 from trying to load qvm files and look for dll files instead. Now all we need to do is start up Quake 3 and tell it to load our mod. This can be done by starting up Quake 3 using the following commandline parameters:
quake3.exe +set fs_game testmod +devmap q3dm1
This will tell Quake 3 to load the dll's located in the testmod folder (change the name if you have your dll's stored in a different folder) and it will also automatically load the Q3DM1 map with cheats enabled. You can also copy/paste that line into a text file and save it as testmod.bat in your quake 3 folder.