Making Q3ASM Actually Work

HOW THE SMEG DO I...?

Many people have reported difficulty compiling *.qvm files with the batch programs that come with the Quake III Arena & Quake III Team Arena Source Code (alternate link). This tutorial attempts to help people set things up so that it becomes possible.

NOTE: I make no guarantee whatsoever that this will work - I’m simply showing you how I got my copy of the code to run on my Windows 98 system. Some parts may not work for you, especially if you are using a non-Windows system (though I can’t blame you if you are! ;-] ).

UPDATE 27/06/01: I have just made a minor alteration to the batch files (in the download zip) to overcome problems experienced on Windows 2000 Professional. Many thanks to Nate Acheson for the heads-up!

UPDATE 13/12/01: Finally compatible with version 1.29h of the source code (which, as far as I am aware, is the codebase used in the 1.3x Point Release). And thanks to the attentions of some kind soul signed bk, this tutorial is now only half as long as it once needed to be ;-)

1 • The Installation

First things first: install the source code. The installer will want to put it in C:\Quake3; make sure that this is exactly where you put it!!! There are two little command-line programs that have to be put there, and if they aren’t, nothing will work.

You should now have new schtuffels as follows:

		C:\
		 +-quake3
		    +-bin_nt
		    |  +-A few files
		    |
		    +-code
		    |  +-cgame
		    |  |  +-A whole shitload of files
		    |  |
		    |  +-game
		    |  |  +-A whole shitload of files
		    |  |
		    |  +-q3_ui
		    |  |  +-A whole shitload of files
		    |  |
		    |  +-ui
		    |     +-A few other files
		    |
		    +-ui
		    |  +-A whole shitload of files
		    |
		    +-One or two files

2 • Basic Messing Around

Because of the way things were set up in a previous release of the source code, there are a few changes you need to make to this new directory structure. Your first step is to rename the code directory - call it source, instead. Go inside this directory, and create a new directory called lcc. Finally, go inside this one and create a directory called bin.

Now, look in C:\Quake3\bin_nt. There are six *.exe files: move all of them to C:\Quake3\source\lcc\bin. Now that they’ve been moved, delete bin_nt.

The world should now look like this:

		C:\
		 +-quake3
		    +-source
		    |  +-cgame
		    |  |  +-A whole shitload of files
		    |  |
		    |  +-game
		    |  |  +-A whole shitload of files
		    |  |
		    |  +-lcc
		    |  |  +-bin
		    |  |    +-A few files
		    |  |
		    |  +-q3_ui
		    |  |  +-A whole shitload of files
		    |  |
		    |  +-ui
		    |     +-A few other files
		    |
		    +-ui
		    |  +-A whole shitload of files
		    |
		    +-One or two files

Now, copy the files C:\Quake3\source\game\g_syscalls.c and C:\Quake3\source\game\g_syscalls.asm to C:\Quake3\source; copy the files C:\Quake3\source\cgame\cg_syscalls.c and C:\Quake3\source\cgame\cg_syscalls.asm to C:\Quake3\source; finally, copy the files C:\Quake3\source\q3_ui\ui_syscalls.c and C:\Quake3\source\q3_ui\ui_syscalls.asm to C:\Quake3\source. You should now have 3 files called *_syscalls.c and 3 files called *_syscalls.asm in the C:\Quake3\source directory: never alter or delete these files!!! In fact, check the Read-Only flag in the properties for all six of these files!

3 • Adding The Forgotten Files

The biggest problem is that, when they were putting together the source download, they forgot to include two little files that do the actual compiling. The second-biggest problem (one that has plagued Q3 Coders since the beginning) is that the batch files that run the compilers don’t work (except for some Win2k users). Download the required files (alternate link) for this tuturial and unzip them into the C:\Quake3\source directory. You will probably be asked if you want to overwrite some files - if so, answer yes, as these are replacements for the broken batch files.

4 • Cleaning (?) Up The Mess

id Software has included the source code to Team Arena as well as the standard Q3A code. This is fine, but remember that you cannot make a “Team Arena Mod”, since Team Arena is itself a mod. With this in mind, when you start a fresh codebase as outlined in the next section, there will be quite a few files missing, but this section will show you how to prove to the compiler that it doesn’t actually need them. Each file that must be edited will be listed, followed by the changes you need to make.

Note: since the 1.29h codebase, you might need to un-check the Read-Only flag on pretty much all files before you can edit them. I’ve included a line at the top of all the batch files that automatically does this for the entire directory, so just run game.bat, cgame.bat and q3_ui.bat once each (you will get errors, but don’t worry for now, we’ll fix them!), before going further.

Note: a few of these modifications were actually suggested by CyberKewl - many thanks to him for finding them.

• C:\Quake3\source\cgame\cg_consolecmds.c

Right near the top, move the line that goes #include "../ui/ui_shared.h" exactly one line down (ie below the line that says #ifdef MISSIONPACK).

• C:\Quake3\source\cgame\cg_servercmds.c

Right near the top, change the line that goes #include "../../ui/menudef.h" to #include "../q3_ui/menudef.h".

• C:\Quake3\source\game\ai_cmd.c
C:\Quake3\source\game\ai_dmnet.c
C:\Quake3\source\game\ai_dmq3.c
C:\Quake3\source\game\ai_team.c
C:\Quake3\source\game\ai_vcmd.c

Near the top of each of these files, change the line #include "../../ui/menudef.h" to read #include "../q3_ui/menudef.h".

In case you’re wondering, this menudef.h file is normally found in a directory that the standard Q3A code doesn’t even bother with - when you start a fresh code base for a new mod, you won’t have this directory. All I’ve done is make a copy of this file and put it in a directory that the standard Q3A code does deal with - this is much easier than my original method, which you don’t even want to hear about, believe me!

• C:\Quake3\source\game\bg_public.h

Search for the following text: “(*trace)( trace_t *results” (between the quotes, not including the quotes). You’ll find yourself inside the definition of the struct pmove_t. Now the line of code you’ve arrived at is a problem - both the cgame code and the game code reference this struct, but they define the respective functions with slightly different parameters. Specifically, vec3_t mins and vec3_t maxs are declared as const in the game code, but not in the cgame code. The simplest way around this that I can see is to use conditional compiling - that is, let the cgame code see things the way it wants to, and compile it with the const declarations for the game code, like so:

	// callbacks to test the world
	// these will be different functions during game and cgame
#ifdef CGAME
	void (*trace)(trace_t *results, const vec3_t start, vec3_t mins, vec3_t maxs, const vec3_t end, int passEntityNum, int contentMask);
#else
	void (*trace)(trace_t *results, const vec3_t start, const vec3_t mins, const vec3_t maxs, const vec3_t end, int passEntityNum, int contentMask);
#endif
	int			(*pointcontents)( const vec3_t point, int passEntityNum );
} pmove_t;

• C:\Quake3\source\game\g_cmds.c

Right near the top, change the line #include "../../ui/menudef.h" to read #include "../q3_ui/menudef.h".

• C:\Quake3\source\game\g_spawn.c

The compiler will complain of an “empty declaration at line #174” - the line in question being void SP_item_botroam( gentity_t *ent ) {};. All you have to do is to delete the ; at the end of that line. I have to admit that it took me a while to work that one out!
/me slaps forhead.

• C:\Quake3\source\q3_ui\ui_local.h

Right near the top, change the line #include "../ui/ui_public.h" to read #include "ui_public.h" - the note on the line above is still correct, we’ve just moved the file.

• C:\Quake3\source\q3_ui\ui_main.c

Search for the string UI_HASUNIQUECDKEY (well...it's not really a string, it's a numerical value, but Notepad doesn't know that). Change the line below that from return qtrue; to return qfalse; - you’ll notice some comments in that little region that tell you to do much the same thing. (I should have added this in ages ago - thanks to Bob Palinckx for that heads-up!)

• C:\Quake3\source\q3_ui\ui_startserver.c

At two places in the file, search for the string _friendlt - just change both of these to read _friendly, instead - they’re both typos that never got fixed.

Finally, a quick word of warning - when you compile the q3_ui directory, you’ll get a lot of big confusing warning messages - two in ui_ingame.c, two in ui_atoms.c and one in ui_menu.c, all of them involving “pointer to void” and other esoteric expressions ;-) There is no way to fix them, so just take note of where you normally see them, so you’ll know which ones to ignore later on (just don’t fall into the trap of ignoring all error messages in the q3_ui directory!).

5 • Starting A Fresh Code Base

The batch programs should now work. In order to begin a new mod with a fresh set of code, create a source directory inside your mod’s subdirectory (for me it’s C:\Games\Quake III Arena\HardHavoc\source). From now on, when I refer to the source directory, I mean the new one you just made under your mod’s directory.

From inside C:\Quake3\source, copy the cgame, game and q3_ui directories to your new source directory. Then copy the six files within C:\Quake3\source to the new source directory, too.

Now find the three *.q3asm files in source\cgame, source\game and source\q3_ui. Edit each one of these so that the first line has the exact directory\filename that the outputted *.qvm file for each should be, inside the quotes, eg for me the first line of cgame.q3asm should read -o "C:\Games\Quake III Arena\HardHavoc\vm\cgame", the first line of game.q3asm should read -o "C:\Games\Quake III Arena\HardHavoc\vm\qagame" (pay attention, there!) and the first line of q3_ui.q3asm should read -o "C:\Games\Quake III Arena\HardHavoc\vm\ui" (are you still paying attention?). For you, the directory structure will be different, but they will all be the same as mine from the vm bit onwards.

You’re nearly there! Now, open source\game\g_local.h. You see that line that says #define GAMEVERSION "baseq3"? Change the baseq3 to something relevant your mod’s subdirectory (mine is #define GAMEVERSION "HardHavoc"). Now open source\game\bg_public.h and do the same sort of thing for #define GAME_VERSION "baseq3-1" (ie I changed mine to #define GAME_VERSION "HardHavoc-1").

That’s the end! To make sure everything is working, go to line 649 of source\game\g_missile.c and change the 900 to a 300. Then recompile all three *.qvm files by running source\cgame\cgame.bat, source\game\game.bat and source\q3_ui\q3_ui.bat. When you run the mod, fire a few rockets - if you can run after them and catch up with them, everything has gone well! (change it back again unless you want to keep it!)

Just a quick note to those who are unfamiliar with Quake III programming - whenever you make a modification to one of the source code files, you usually only need to run the *.bat file in that directory (ie recompile the *.qvm file that that source file is a part of). However, if you make any modifications to any of the source\game\bg_*.* files, you need to recompile all three *.qvms. And it’s also worth mentioning that you should NEVER edit either of the source\game\q_shared.* files - they are both part of the source code to the quake3.exe file (ie the engine!) and so any changes made to those files would require recompiling quake3.exe - which nobody but id Software can do!!!

If there are any problems with this tutorial, eMail me and tell me exactly what’s not working. Good luck, and have fun!