Table of Contents
The gamecode used in AudioQuake has two main goals:
This is achieved by adding features to the gameplay such as navigation aids and audio cues for events. Techniques used include the addition of entities, use of impulses, addition of sound functions (some directed at specific clients) and bots.
By acting as a layer on top of the Quake gamecode, the AGRIP code allows developers to hook into it, use its accessibility functions and not have to worry about changes in the underlying gamecode. Developers' lives are made easier when they use the modular ZQuake/AGRIP gamecode system as they can keep the footprint of their mods as small as possible. Ways to do this are detailed throughout this manual, but include the ability to re-use all existing standard and AGRIP code and the provision of hooks into the AGRIP code at convenient points.
Many functions created in the development of AudioQuake are written to be as generic as possible. They form what could be thought of as an “accessibility library” on top of the standard QuakeC.
This modular design approach was tested... all bot navigation code was modified to use the AGRIP accessibility aid functions. This meant that the bots' perception of the world was essentially that of a blind player. The bots performed well and began to navigate in a similar style to that of most blind gamers.
Our recommended method of setting up your mod, in terms of directory structure and code re-use, can be found above. This section explains how the AGRIP code is laid out internally (i.e. inside the agrip/ directory).
The source code is heavily commented; take advantage of this to learn how to make best use of the library code that has been written for your mods.
Stores definitions (global variables, entity fields) for the AGRIP mod. This file should be read by mod developers to learn about the various hooks in our code that are available to them. An example hook is AGRIP_MODHOOK_PRECACHE, which allows you to define a function that is called to precache extra data your mod needs.
If you need a hook into a function and we don't provide one currently, you should ask us to create one. The reason is that in future, if the QC code for ZQuake changes, your mod may well not work. If you hook into ours, though, we can shield you from such effects of change to the underlying gamecode. Proposals for new hooks should be sent to the mailing list.
The Detector 5000.
The “Auxiliary/Extended Player Information” object. This is needed because the player doesn't have enough entity fields spare to store all of the information we need to store (such as is used for collision detection). Each player is given a private one of these when they spawn and the information it records is used by lots of other AGRIP code.
The EtherScan RADAR.
Navigational aids that do not rely on the presence of the “nav” object.
Hooks from AGRIP into the main QuakeC gamecode. DO NOT confuse this with the way we provide hooks into our code for mod developers; this file simply contains AGRIP code that we've put here to lower the footprint on the QuakeC gamecode as a whole.
The procedure for hooking into our code is described FIXME elsewhere.
The waypoint marker object.
This is a huge QC file that contains the core navigation helper object. The player uses this to get feedback on where they are, what hazards are present and so on.
This is the “makefile” for the QuakeWorld gamecode. It lists all the .qc files that need to be compiled for the multiplayer game modes to work. The first line gives the output filename (a .dat file, that contains the compiled QuakeC gamecode).
You'll notice that some external files are included (from other QC source directories described above). They are from the original QuakeWorld gamecode; the AGRIP code augments them and hooks into them in certain places. Your mod code should aim to avoid hooking directly into these files; rather it should hook into the AGRIP code where possible (please tell us if that isn't possible)
Sound entity object, created to provide loopable, movable and removable sounds. Used extensively by other AGRIP code.
This is the same type of file as progs.src, but is aimed at the single-player gamecode. Therefore, the monster and AI code is included too.
The bot we use, written by Darryl “Coffee” Atchison.
A file that contains the functions that the Tutor Bot needs to function when compiled for multiplayer gamecode (it requires some AI and other functions from the singleplayer code).
Each function contains a header comment. The information provided by the comment is designed to help you use the function in your own modifications. In fact, all of the code has been prepared in such a way that a special tool can process it and turn it into a website that allows you to learn about any individual function. The idea is that you can look up functions by name, or the type of work they do, and see where they fit into the rest of the code (and how they work).
If you'd like to visit the “Doxygen” documentation on the AGRIP QuakeC code, go to the AGRIP documentation site.