Table of Contents
This chapter introduces some vital concepts you need to be aware of and understand before you can understand how modifying any aspect of the game actually works.
A file system is basically the organised arrangement of objects (normally files and directories) which make up your data. The VFS (Virtual File System) is, as its name suggests, virtual. File systems on your disks are not–they are stored on disk and comprise data you put on that disk in that file system. The source of the data is a physical device, and usually exclusively that device. By contrast, the VFS is virtual–objects in the file system are loaded sequentially from various sources, and the prevailing object in case of a conflict is the one loaded last. This is important in understanding how a mod works.
When Quake starts, it scans a directory looking for files called “PAK files”, so-called because their extension is .pak. These pak files are numbered, starting from zero, and Quake loads these files in ascending order. The pak file contains a file system, and this is loaded into the in-game file system. The process is repeated for each pak file in this directory.
Next, Quake will read a file system from a directory in your "Real" disk file system. That directory typically contains a mod, and the user specifies it with a command-line parameter to Quake when it is started. Putting the files in the mod directory is equivalent to putting them into an additional pak file (tools exist to help you do that) in the pak files directory.
In both cases, when a file exists in the virtual file system, any version loaded later with the same path will replace the one loaded before it. Since the file system is virtual, the source of these files is insignificant–it may be either the pak files or the mod directory, and the loading behaviour will usually mean that mods get loaded over in-game objects. The programmed game code does not make any special differentiation between files loaded from one place as opposed to another–it simply references the object desired, and the engine will determine the ultimate location of the object.
The best way to learn about how the PAK files are created is to extract the data from them and experiment with changing it. You can use tools such as PakExplorer to do this.
This section describes the overall process for modifying the game. The list below describes a typical set-up that allows you to test your mod, tweak things and quickly re-test. When you want to make packages of your mod for end-users to quickly install and easily manage, you'll need to read the part on QMODs. The rest of the manual goes into more detail on how you carry out certain stages in this process, such as modifying content or gamecode.
Add to/modify the gamecode, or add new content. (Note that modifying the engine would make the game no longer AudioQuake, hence it's not mentioned here, but accessible total conversions into entirely new games are very much encouraged!)
Place your modifications into a new directory inside the AudioQuake directory, beside the id1/ directory that's already there. Any files in your directory with the same name as ones in id1/ (or inside the .pak files) will override the pre-existing ones.
For example, if you have changed some of the sounds in the game, you can recreate the directory structure of the .pak files in id1, including only the sounds you changed (the rest will still be loaded from the .pak files). If your mod is called “testmod”, the sounds may be in testmod/sound/player/. If you've modified the gamecode, put progs.dat and spprogs.dat into the testmod/ directory and they'll override the ones in id1/*.pak.
Start the game, telling it to load in your new modifications over the top of the default gamecode and content in id1/. This is the standard way that mods work, by replacing certain parts of the original game content and/or code.
In normal Quake, this would be done by specifying “+gamedir mod_directory” on the command line. In AudioQuake, however, this is done by changing the “default_gamedir” line in the “general” section of start.ini to the directory of your mod, as opposed to “id1”. This points the game at your mod for an extra source of content and gamecode (the contents of the id1/ directory will still be loaded into the VFS, however, as that's the standard Quake behaviour).
This technique is intended to be used only by mod developers, when testing their mod (note that it stops you from being able to run standard AudioQuake). To make packages of your mod for end-users, please see the QMODs part. There are a number of advantages in using the QMOD method: users can install mods simply by double-clicking; they can switch between multiple mods easily via the launcher instead of having to edit a Perl script and your mod can be kept up-to-date with changes to the users' settings automagically by the AudioQuake launcher.
Tweak and test, repeat as necessary.
Package up your mod into a QMOD file. This requires that you put any mod-specific settings into a file named mod.cfg in your mod's directory. Ensure that any autoexec.cfg and/or config.cfg files have been removed, as the QMOD system can copy over the user's settings, which are likely to be different than the ones you've specifed, into your mod for you. This enusres that key bindings and settings are consistent from the user's perspecitve. The QMOD system can keep your mod up-to-date with changes in the user's settings automatically. Read the QMOD part of this manual for information on the other steps you need to take.
The rest of this manual explains how to perform the modifications of gamecode and engine, as well as packaging up your modification in QMOD form, building AudioQuake releases from source and how the Stats and Servers infrastructure works.
As map editing is not (currently) possible, it is not described. Work on making map editing accessible is ongoing, however.