Table of Contents
QuakeC is a high-level gamecode language that is compiled into bytecode/assembly instructions for the QuakeC Virtual Machine (in much the same way that Java and Perl work). The virtual machine is what executes your compiled-down code (the .dat files). The reasons why a virtual machine is used are portability (QuakeC works on all platforms that Quake does) and security (your mod cannot access anything outside of the QuakeC VM, other than the “builtin” functions that the Quake engine provides).
The engine provides builtin functions for doing performance-critical calculations (such as working out if a particular 3D vector corresponding to the aim of a weapon would hit a player) and interfacing with the outside world via the presentation of content to the user, such as sounds (e.g. when a weapon fires, a sound is made).
The whole gamecode for Quake, with AGRIP extensions, and any modifications you make must be compiled together into one .dat file. All of the code you need is in the Subversion repository. Unfortunately this has the side effect that only one modification can running any time; the Unreal engine (which powers a competing series of games) provides some ways to combat this and run multiple modifications at once. Alas it is not Open Source so hasn't been made accessible yet. In practise this limitation of the Quake engine should not make too much difference, as the user can have multiple mods installed at any time (the game launcher and QMOD system take care of this).
QuakeC is similar to C in nature. This is not a tutorial on the language itself; it is assumed the reader is used to programming in general. Much information can be found through the resources listed in appendix section on the matter.
QuakeC (.qc) files must be compiled into a .dat to be run by the game. The gamecode for the entire game is composed of many QuakeC files. Some of the files are only applicable to the single-player game and some are multiplayer-specific, so actually two .dat files are usually built (one for each type of gameplay).
Which QuakeC files are compiled together, and the order in which that's done, is dictated by a .src file. This is a text file that lists the name of the output file on the first line and, on following lines, the QuakeC files to be processed. ZQuake is a QuakeWorld (multiplayer) game engine, but has had the single player monsters and AI ported to it. Because of this, the convention is for there to be a progs.src file used to produce the multiplayer progs.dat code, and a spprogs.src file that is used to create the singleplayer spprogs.dat.
Building of the QuakeC code as part of the whole AudioQuake release is covered in more detail elsewhere in the manual. The important part from a QuakeC perspective is that the ZQuake QuakeC Compiler (zqcc) must be run on a suitable progs.src file to turn the QuakeC files into a .dat file for the game to run.
The ZQuake project hosts gamecode for a number of popular game modes and mods. This includes a version of the classic single-player Quake gamecode ported to QuakeWorld. It is laid out in a number of directories as follows.
Gametypes that have not yet been made accessible. Note that this version of CTF is not under active development and kteams is a deathmatch-like mode (we decided to make the classic Quake TeamDM more akin to that found in later games such as Unreal Tournament rather than adopt this mod).
Code for various bots which we don't use.
Code for the mission pack "The Scourge of Armagon" (also unused).
Where it all started – a maintained version of the QuakeWorld (DM, Classic TeamDM) gamecode.
The extra code on top of that in the qw/ directory to add all the elements of single player classic Quake.
As with other code here, lots of it is linked and depends on code in other directories. Most code uses a lot of the stuff in the qw/ directory and this one is no exception.
Such tight linking of code keeps the codebase small, easy to maintain and reliable.
Our accessibility hooks into the main game (both QW and QWSP versions are catered for, though the use of different .src files, which tell ZQCC how to build the AGRIPified gamecode .dats.
Again, our code links heavily to that in the qw/ and qwsp/ directories.
As has been pointed out, much of the code hare is linked and when you develop a mod, we recommend you start a new top-level directory in here and reuse as much of the existing code as you can. Start with one of the AGRIP progs.src files and add any extra .qc files you might need in your own directory.
If you need to override any functions in the main code, don't replace an entire file with your own version – there is a way for you to override individual functions elsewhere in the code, which will be explained later.
Constructing your mod in this way has the advantages of much easier upgrades between AGRIP versions (as if you follow the guidelines here you'll be hooking into our code mostly and won't have to worry about changes in the stock ZQuake code). It also keeps your mod's codebaese small, simple and therefore easy to maintain and (hopefully!) more reliable.
Guidelines for constructing your mod in this way can be found throughout this guide.