-- see more --

A tutorial style reference for scripting in QuakeC (the scripting language for quake engine based games - including CoD)

A tutorial style reference for scripting in QuakeC (the scripting language for quake engine based games - including CoD)

This is part 1 of 2 the complete (printable) download of this file in its entirety is available here.

1. Introduction

1.1 What is QuakeC?

QuakeC is a language similar to C.
QuakeC can be compiled with qcc (Quake C compiler) to produce progs.dat, a file that Quake can load at startup. In that file, Quake searches the engines for various things in the Quake World.
Monsters, players, buttons, weapons are the target of QuakeC, you cannot modify levels or graphics that you can modify with a external editor.
Major part of this document are copyright by Olivier Montanuy . All the informations contained in this document are related to Quake-C, a language developed by and for ID Software, so all those informations are copyright (c) 1996, ID Software.

To compile and use all the code you must have qcc.tar.gz take it from ID Software. You can edit and then compile with qccdos (the compiler) all the .qc files. You can rewrote all AI of the monster or create new entities.
I have only converted, corrected and added some stuff.

1.2 Contributions

Olivier Montanuy is the real compiler of this document, it was first rearranged to a TXT version by Francesco Ferrara. Many thanks to Olivier and Francesco.

2. QuakeC Language - Basic Constructs

2.1 Comments

// followed by comments, until the next line.
/* enclose a block comments */

Those comments are the same as in C++ (and many C languages).

2.2 Names

Names of variable, field, or function have a maximum size of 64 characters, must begin with A-Z,a-z, or _, and can continue with those characters or 0-9.

2.3 New Types

You cannot define new types from the existing ones. In particular, you cannot define new structures, new objects, and you cannot affect a new name to a type (as does typedef in C).

These restrictions make Quake-C compare unfavourably even to Basic, and sure it's about time the ID Software guys hired someone that already wrote a compiler.

You can add only fields to the most important type in QuakeC entity.

2.4 Definition of Variables

type variable1, variable2;
eg:
float a,b;
Where type is one of the pre-defined simple types.
You can also affect default values to variables, for instance :

type variable1 = value;
eg:
float a = 2;
Scoping of variables : There are two levels of scoping. By default all variables are global : they can be accessed by any functions, and they are shared by all the functions (and all the clients of a given network server, of course).

But inside the functions, by using the keyword local just before the declaration of a variable, you can make this variable visible only the function itself (i.e. it will be allocated on the stack).

Note that parameters of functions are treated like local variables : they are only visible to the function, but they can be modified.

2.5 Definition of Constants

Any global variable that is initialized by setting a value to it, is actually assumed to be a constant.

Since a constant is in fact represented by immediate values, you should NEVER attempt to modify a constant by giving it another value. Otherwise the program might have unpredicable results.

The constants are not saved to game files. Only regular variables are.

2.6 Definition of Functions

The general structure of a function definition is :

type (type param1, typeparam2, ... ) function =
{
... code ...
};
Don't forget the ";" after the brackets.

Here are some examples :

void() think = {...};
entity() FindTarget = {...};
void(vector destination, float speed, void() callback) SUB_CalcMove = {...};

2.7 Function Declaration

If you want to use a function before defining it, you must declare it, otherwise the Quake-C compiler will not be able to use it.

The general structure of a function declaration is:

type (type param1, typeparam2, ... ) function;

2.8 Definition of a Frame Function

Frame functions (also called States) are special functions made for convenience. They are meant to facilitate the definition of animation frames, by making them more readable.

Here is an example :

void() framename = [$framenum, nextthink] { ...code...};
It is strictly equivalent to :

void() framename =
{
self.frame= $framenum; // the model frame to displayed
self.nextthink = time + 0.1; // next frame happens in 1/10 of second
self.think = nextthink; // the function to call at the next frame
...code...
};

2.9 Conditional Construct

if( expression )
{
statements
}
else
{
statements
}

2.10 Loop Construct

while( expression )
{
statements
}
or

do
{
statements
}while( expression )

2.11 Function Calls

Call a function :

function_name ( parameter1, parameter2,... )
The cannot be more than 8 parameters.

Return a value :

return( expression )

2.12 Logical Operations

! // logical not
&& // logical and
|| // logical or
Take care that in if() conditional expressions containing two or more logical clauses, all the clauses will be evaluated before the condition test (like in Basic, and unlike C).

That means that if one part of your condition is not always valid or defined, you had better decompose your if() into two successive if(). It should also make it faster.

2.13 Comparisons

<= < >= >
== // equal, beware at the double = like in C.
!= // not equal, like in C.

2.14 Operations on Floats or Intergers

* / - +
Use parenthesis to remove ambiguities.

2.15 Bitwise Operations

& // bitwise and
| // bitwise or
These operators treat floats like integers, so they are usually meant to be used with values made of bit masks.

3. Built-in Functions

These are the built-in functions of Quake C. Since they are hard-coded in C, they cannot be redefined, but they are very fast.

3.1 Basic Math Functions

QuakeC code	Notes
Function: anglemod float anglemod (float angle)	Returns angle in degree, modulo 360.
Function: rint float rint(float val)	Returns val, rounded up to the closest integer value.
Function: floor float floor(float val)	Returns val, rounded up to the integer below (like the equivalent function in C).
Function: ceil float ceil(float val)	Returns val, rounded up to the integer above (like the equivalent function in C).
Function: fabs float fabs(float val)	Returns absolute value of val (like the equivalent function in C).
Function: random float random()	Returns a random floating point number between 0.0 and 1.0.
Function: ftos string ftos(float value)	Float to string: converts value to string.

3.2 Basic Vector Maths

QuakeC code	Notes
Function: normalize vector normalize(vector v)	Returns a vector of length 1. Gives the vector colinear to v, but of length 1. This can be useful for calculation of distance along an axis.
Function: vlen float vlen(vector v)	Returns the length of vector v (never < 0).
Function: vectoyaw float vectoyaw(vector v)	Returns and angle in degree. Vector to yaw : calculates the yaw angle (bearing) corresponding to a given 3D direction v.
Function: vectoangles vector vectoangles(vector v)	returns vector 'pitch yaw 0 'Vector to angles : calculates the pitch angle (aiming) and yaw angle (bearing) corresponding to a given 3D direction v.
Function: vtos string vtos(vector v)	Vector to String : print a vector, as a string.
Function: makevectors void makevectors(vector angles) angle = 'pitch yaw 0'	Calculate the vectors pointing forward, right and up, according to the provided angles. Returns result in the global variables : vector v_forward; // points forward vector v_up; // points up vector v_right; // points toward the right

3.3 Sound Emission

QuakeC code	Notes
Function: sound void sound (entity source, float channel, string sample, float volume, float attenuation)	source = entity emiting the sound (ex: self)channel = channel to use for soundsample = name of the sample WAV file (ex: "ogre/ogdrag.wav")volume = 0.0 for low volume, 1.0 for maximum volumeattenuation= attenuation of soundThe entity emits a sound, on one of it's 8 channels.
Function: ambientsound void ambientsound(vector position, string sample, float volume, float attenuation)	position = position, in 3D space, inside the level sample = name of the sample WAV file (ex: "ogre/ogdrag.wav")volume = 0.0 for low volume, 1.0 for maximum volumeattenuation = attenuation of soundAn ambient sound is emited, from the given position.

3.4 Entity Management

QuakeC code	Notes
Function: spawn entity spawn ()	Returns an empty entity.Create a new entity, totally empty. You can manually set every field, or just set the origin and call one of the existing entity setup functions.
Function: remove void remove (entity e)	Removes entity e from the world (R.I.P.).
Function: makestatic void makestatic (entity e)	Make an entity static to the world, by sending a broadcast message to the network. The entity is then removed from the list of dynamic entities in the world, and it cannot be deleted (until the level ends).
Function: nextent entity nextent(entity e)	Returns entity that is just after e in the entity list.Useful to browse the list of entities, because it skips the undefined ones.
Function: find entity find (entity start, .string field, string match)	start = begining of list to search (world, for the begining of list)field = entity field that must be examined (ex: targetname)match = value that must be matched (ex: other.target)Returns the entity found, or world if no entity was found.Searches the server entity list beginning at start, looking for an entity that has entity.field = match.Example : find the first player entity e = find( world, classname, "player"); Take care that field is a name of an entity field, without dot, and without quotes.
Function: findradius entity findradius (vector origin, float radius)	origin = origin of sphereradius = radius of sphereReturns a chain of entities that have their origins within a spherical area. The entity returned is e, and the next in the chain is e.chain, until e==FALSE. Typical usage: find and harm the victims of an explosion.Example : e = findradius( origin, radius) while(e) { T_Damage(e, ... ) // Let God sort his ones! e = e.chain }
Function: setmodel void setmodel (entity e, string model)	e = entity whose model is to be setmodel = name of the model (ex: "progs/soldier.mdl")Changes the model associated to an entity. This model should also be declared by precache_model. Please set e.movetype and e.solid first.
Function: lightstyle void lightstyle(float style, string value)	style = index of the light style, from 0 to 63.value = (ex: "abcdefghijklmlkjihgfedcb")Modifies a given light style. The light style is used to create cyclic lighting effects, like torches or teleporter lighting. There are 64 light tyles, from 0 to 63. If style is not strictly comprised in these values, the game may crash. Styles 32-62 are assigned by the light program for switchable lights. Value is a set of characters, whose ascii value indicates a light level, from "a" (0) to "z" (30).

3.5 Move Entities

QuakeC code	Notes
Function: ChangeYaw void ChangeYaw()	Change the horizontal orientation of self. Turns towards self.ideal_yaw at self.yaw_speed, and sets the global variable current_yaw.Called every 0.1 sec by monsters.
Function: walkmove float walkmove(float yaw, float dist)	Returns TRUE or FALSE.Moves self in the given direction.Returns FALSE if could not move (used to detect blocked monsters).
Function: droptofloor float droptofloor()	Returns TRUE or FALSE.Drops self to the floor, if the floor is less than -256 coordinates below. Returns TRUE if landed on floor. Mainly used to spawn items or walking monsters on the floor.
Function: setorigin void setorigin (entity e, vector position)	e = entity to be movedposition = new position for the entityMove an entity to a given location. That function is to be used when spawning an entity or when teleporting it. This is the only valid way to move an object without using the physics of the world (setting velocity and waiting). DO NOT change directly e.origin, otherwise internal links would be screwed, and entity clipping would be messed up.
Function: setsize void setsize (entity e, vector min, vector max)	e = entity whose bounding box is to be setmin = minimum, for bounding box (ex: VEC_HULL2_MIN)max = maximum, for bounding box (ex: VEC_HULL2_MAX)Set the size of the entity bounding box, relative to the entity origin. The size box is rotated by the current angle.
Function: movetogoal void movetogoal (float step)	Move self toward it's goal.Used for monsters.

3.6 Flights and Shots

QuakeC code	Notes
Function: aim vector aim(entity e, float missilespeed)	Returns a vector along which the entity e can shoot.Usually, e is a player, and the vector returned is calculated by auto-aiming to the closest enemy entity.
Function: particle void particle(vector origin, vector dir, float color, float count)	origin = initial positiondir = initial directioncolor = color index (73,75...)count = time to live, in seconds .Create a particle effect (small dot that flies away).color = 0 for chunkcolor = 75 for yellowcolor = 73 for blood redcolor = 225 for entity damage
Function: checkclient entity checkclient()	Returns client (or object that has a client enemy) that would be a valid target. If there are more than one valid options, they are cycled each frame.If (self.origin + self.viewofs) is not in the PVS of the target, 0 (false) is returned.

3.7 Collision Checking

QuakeC code	Notes
Function: traceline traceline (vector v1, vector v2, float nomonsters, entity forent)	v1= start of linev2= end of linenomonster= if TRUE, then see through other monsters, else FALSE.forent= ignore this entity, it's owner, and it's owned entities. if forent = world, then ignore no entity.Trace a line of sight, possibly ignoring monsters, and possibly ignoring the entity forent (usually, forent = self). This function is used very often, tracing and shot targeting. Traces are blocked by bounding boxes and exact bsp entities. Returns the results in the global variables : float trace_allsolid; // never used float trace_startsolid; // never used float trace_fraction; // fraction (percent) of the line // that was traced, before // an obstacle was hit. Equal to 1 // if no obstacle were found. vector trace_endpos; // point where line ended or met an // obstacle. vector trace_plane_normal; // direction vector of trace (?) float trace_plane_dist; // distance to impact along direction // vector (?) entity trace_ent; // entity hit by the line float trace_inopen; // boolean, true if line went through // non-water area. float trace_inwater; // boolean, true if line went through // water area.
Function: checkpos CURRENTLY DISABLED. DO NOT USE. scalar checkpos (entity e, vector position)	Returns true if the given entity can move to the given position from it's current position by walking or rolling.
Function: checkbottom float checkbottom(entity e)	e = entity that is to be checkedReturn TRUE or FALSE.Returns TRUE if on the ground. Used only for jumping monster, that need to jump randomly not to get hung up (or whatever it actually means).
Function: pointcontents float pointcontents(vector pos)	Returns the contents of the area situated at position pos.Used to know if an area is in water, in slime or in lava.Makes use of the BSP tree, and is supposed to be very fast.

3.8 Server Related Functions

QuakeC code	Notes
Function: changelevel void changelevel (string mapname)	Warp to the game map named mapname. Actually executes the console command "changelevel" + mapname, so if you want to alias it...
Function: setspawnparms void setspawnparms (entity client)	Restore the original spawn parameters of a client entity.Doesn't work if client is not a player.
Function: stuffcmd stuffcmd (entity client, string text)	client = player that is to receive the commandtext = text of the command, ended by n (newline).Send a command to a given player, as if it had been typed on the player's console. Don't forget the n (newline) at the end, otherwise your command will not be executed, and will stand still on the console window.Examples : stuffcmd(self, "bfn"); // create a flash of // light on the screen. stuffcmd(self, "name Buddyn"); // name the player Buddy. Mostly used to send the command bf, that creates a flash of light on the client's screen.

3.9 Print Messages

QuakeC code	Notes
Function: bprint void bprint (string text)	text = text of the messageBroadcast a message to all players on the current server.
Function: centerprint void centerprint( entity client, string text)	client = player that is to receive the messagetext = text of the messageSends a message to a specific player, and print it centered.
Function: sprint void sprint (entity client, string text)	client = player that is to receive the messagetext = text of the messageSends a message to a player.

3.10 Console

QuakeC code	Notes
Function: localcmd void localcmd (string text)	text = text of the command, ended by n (newline).Execute a command on the server, as if it had been typed on the server's console.Examples : localcmd("restartn"); // restart the level localcmd("teamplay 1n"); // set deathmatch mode to teamplay localcmd("killservern"); // poor server...
Function: dprint void dprint (string text)	text = text of the messagePrints a message to the server console.
Function: cvar float cvar (string variable)	variable = see console variablesReturns the value of a console variable.
Function: cvar_set float cvar_set (string variable, string value)	variable = see console variablesSets the value of a console variable.

3.11 Debugging

QuakeC code	Notes
Function: eprint void eprint (entity e)	e = entity to printPrint details about a given entity (for debug purposes).
Function: coredump void coredump()	Print all entities
Function: traceon void traceon()	Start tracing functions, end them with traceoff()
Function: traceoff void traceoff()	End traces started by traceon()
Function: break void break()	Exit the programs. Never used?
Function: error void error (string text)	Print an error message.
Function: objerror void objerror (string text)	Print an error message related to object self.

3.12 Pre-caching Files

Those functions are used to declare models, sounds and stuff, before the PAK file is built. Just follow this rule : whenever one of your functions makes use of a file that's not defined in Quake, precache this file in a function that will be called by worldspawn(). Then, the QCC compiler can automatically include in the PAK file all the files that you really need to run your programs.
And when the level starts running, those precache orders will be executed, so as to attribute a fixed table index to all those files. DO NOT USE those functions in code that will be called after worldspawn() was called. As a matter of fact, that could bomb Quake (restarting the level, without crashing the game).
Files can only be precached in spawn functions.

QuakeC code	Notes
Function: precache_file void precache_file(string file)	file = name of the file to include in PAK file.Does nothing during game play.Use precache_file2 for registered Quake.
Function: precache_model void precache_model(string file)	file = name of the MDL or BSP file to include in PAK file.Does nothing during game play. Must be used in a model's spawn function, to declare the model file. Use precache_model2 for registered Quake.
Function: precache_sound void precache_sound(string file)	file = name of the WAV file to include in PAK file.Does nothing during game play. Must be used in a model's spawn function, to declare the sound files. Use precache_sound2 for registered Quake.

4. Defines

4.1 Values : Temporary Entities

Information copied from the DEM specifications

// point entity is a small point like entity.
0 TE_SPIKE unknown
1 TE_SUPERSPIKE superspike hits (spike traps)
2 TE_GUNSHOT hit on the wall (Axe, Shotgun)
3 TE_EXPLOSION grenade/missile explosion
4 TE_TAREXPLOSION explosion of a tarbaby
7 TE_WIZSPIKE wizard's hit
8 TE_KNIGHTSPIKE hell knight's shot hit
10 TE_LAVASPLASH Chthon awakes and falls dead
11 TE_TELEPORT teleport end
// large entity is a 2 dimensional entity.
5 TE_LIGHTNING1 flash of the Shambler
6 TE_LIGHTNING2 flash of the Thunderbolt
9 TE_LIGHTNING3 flash in e1m7 to kill Chthon

4.2 Values : Sound Channel of Entities

CHAN_AUTO = 0; // Create a new sound
CHAN_WEAPON = 1; // Replace entitie's weapon noise
CHAN_VOICE = 2; // Replace entitie's voice
CHAN_ITEM = 3; // Replace entitie's item noise
CHAN_BODY = 4; // Replace entitie's body noise
Those values are meant to be used with the function sound.

4.3 Values : Sound Attenuation

ATTN_NONE = 0; // full volume everywhere in the leve
ATTN_NORM = 1; // normal
ATTN_IDLE = 2; // [FIXME]
ATTN_STATIC = 3; // [FIXME]
Those values are meant to be used with the functions sound and ambientsound.

4.4 Values : Contents of Level Areas

CONTENT_EMPTY = -1; // Empty area
CONTENT_SOLID = -2; // Totally solid area (rock)
CONTENT_WATER = -3; // Pool of water
CONTENT_SLIME = -4; // Pool of slime
CONTENT_LAVA = -5; // Lava
CONTENT_SKY = -6; // Sky

4.5 Values : Entity Light Effects

EF_BRIGHTFIELD = 1; // Glowing field of dots
EF_MUZZLEFLASH = 2;
EF_BRIGHTLIGHT = 4;
EF_DIMLIGHT = 8;

4.6 Values : Existing Items

IT_AXE = 4096;
IT_SHOTGUN = 1;
IT_SUPER_SHOTGUN = 2;
IT_NAILGUN = 4;
IT_SUPER_NAILGUN = 8;
IT_GRENADE_LAUNCHER = 16;
IT_ROCKET_LAUNCHER = 32;
IT_LIGHTNING = 64;
IT_EXTRA_WEAPON = 128;
IT_SHELLS = 256;
IT_NAILS = 512;
IT_ROCKETS = 1024;
IT_CELLS = 2048;
IT_ARMOR1 = 8192;
IT_ARMOR2 = 16384;
IT_ARMOR3 = 32768;
IT_SUPERHEALTH = 65536;
IT_KEY1 = 131072;
IT_KEY2 = 262144;
IT_INVISIBILITY = 524288;
IT_INVULNERABILITY = 1048576;
IT_SUIT = 2097152;
IT_QUAD = 4194304;

4.7 Values : Behavior of Solid Objects

SOLID_NOT = 0; // no interaction with other objects
// inactive triggers
SOLID_TRIGGER = 1; // touch on edge, but not blocking
// active triggers, pickable items
// (.MDL models, like armors)
SOLID_BBOX = 2; // touch on edge, block
// pickable items (.BSP models, like ammo box)
// grenade, missiles
SOLID_SLIDEBOX = 3; // touch on edge, but not an onground
// most monsters
SOLID_BSP = 4; // bsp clip, touch on edge, block
// buttons, platforms, doors, missiles

4.8 Values : Type of Movements

MOVETYPE_NONE = 0; // never moves
//float MOVETYPE_ANGLENOCLIP = 1;
//float MOVETYPE_ANGLECLIP = 2;
MOVETYPE_WALK = 3; // Walking players only
MOVETYPE_STEP = 4; // Walking monster
MOVETYPE_FLY = 5; // Hovering Flight
// meant for flying monsters (and players)
MOVETYPE_TOSS = 6; // Balistic flight
// meant for gibs and the like
MOVETYPE_PUSH = 7; // Not blocked by the world, push and crush
// meant for doors, spikes and crusing platforms
MOVETYPE_NOCLIP = 8; // Not blocked by the world
MOVETYPE_FLYMISSILE = 9; // like fly, but size enlarged against monsters
// meant for rockets
MOVETYPE_BOUNCE = 10; // bounce off walls
MOVETYPE_BOUNCEMISSILE = 11 // bounce off walls, but size enlarged against monsters
// meant for grenades

4.9 Values : Entity can Take Solid Damages

DAMAGE_NO = 0; // Can't be damaged
DAMAGE_YES = 1; // Grenades don't explode when touching entity
DAMAGE_AIM = 2; // Grenades explode when touching entity
Most damageable entities have DAMAGE_AIM, so that when they chew on a grenade, it explodes. If you make an entity DAMAGE_YES, the grenades will bounce off it.
4.10 Values : Entity Dead Flag
DEAD_NO = 0; // still living
DEAD_DYING = 1; // dying (helpless)
DEAD_DEAD = 2; // really dead
DEAD_RESPAWNABLE = 3; // dead, but can respawn

4.11 Values : Spawnflags

The spawn flags are bit fields, whose interpretation depend on the concerned entity. There is quite a bit of a hack, that could cause unexpected bugs in the Quake C code.

DOOR_START_OPEN = 1; // allow entity to be lighted in
// closed position
SPAWN_CRUCIFIED= 1; // for zombie
PLAT_LOW_TRIGGER = 1; // for func_plat
SPAWNFLAG_NOTOUCH= 1;
SPAWNFLAG_NOMESSAGE= 1;
PLAYER_ONLY = 1;
SPAWNFLAG_SUPERSPIKE = 1; // for spike shooter
SECRET_OPEN_ONCE = 1; // secret door, stays open
PUSH_ONCE = 1;
WEAPON_SHOTGUN = 1; // weapon, shotgun
H_ROTTEN = 1; // health, rotten (5-10 points)
WEAPON_BIG2 = 1; // items
START_OFF = 1; // light, is off at start.
SILENT = 2;
SPAWNFLAG_LASER = 2; // for spike shooter
SECRET_1ST_LEFT = 2; // secret door, 1st move is left of arrow
WEAPON_ROCKET = 2; // weapon, rocket
H_MEGA = 2; // health, mega (100 points)
DOOR_DONT_LINK = 4;
SECRET_1ST_DOWN = 4; // secret door, 1st move is down from arrow
WEAPON_SPIKES = 4; // weapon, nailgun
DOOR_GOLD_KEY = 8;
SECRET_NO_SHOOT = 8; // secret door, only opened by trigger
WEAPON_BIG = 8; // weapon, super model
DOOR_SILVER_KEY = 16;
SECRET_YES_SHOOT = 16; // secret door, shootable even if targeted
DOOR_TOGGLE = 32;

5. Entities

Part of this information is derived from the DEM file specs 1.0.2 by Uwe Girlich.

In Quake, monsters, players, items, and the level itself are all entities. There are three kind of entities, and you will all encounter them in Quake-C code.

Types of Entities

Static entities

A static entity doesn't interact with the rest of the game. These are flames (progs/flame.mdl), lights, illusionary objects, and the like. It is never be necessary to reference such an entity, so they don't get an entity reference number.

A static entity will be created by the function :

makestatic()
(it causes a spawnstatic message to be sent to every client).
A static entity cannot be removed, once created.

The maximum number of static entities is 127.

Temporary entities

A temporary entity is a short life time entity. For instance, Quake uses these entities for hits on the wall (point-like entities) or for the Thunderbolt flash (line-like entities), gun shots, and anything that is not supposed to last more than one frame.

A temporary entity will be created by sending a valid temporary entity message.
A temporary entity doesn't need to be removed, it disappears by itself.

Dynamic entities

A dynamic entity is anything which changes its behaviour or its appearance. These are ammunition boxes, spinning armors, player models and the like.

A dynamic entity will be created by the sequence :

entity = spawn();
setmodel( entity, "progs/entity.mdl" );
setsize( entity, vector_min, vector_max);
setorigin( entity, position );

It will have to be removed by the function :

remove( entity );
The maximum number of dynamic entities is 449.

Definition of entity fields

These are the fields that are available in the entity objects (like self, other). Beware that this is not true object oriented programming : there is no protection when accessing those fields, and no guaranty on the validity of values. So if you put garbage there you will probably crash the game.

You can add custom fields (for instance, to store the ammo count of a new weapon you created) but those fields must not be situated among thoses that are common between Quake-C and Quake.exe. Otherwise, Quake.exe would have to be re-compiled. So those fields must be situated after the fake variable called end_sys_fields, in the field definitions.

Fields shared between Quake.exe and Quake-C.

These fields describe the most common entity fields. They are shared between the C code of Quake.exe, and the Quake-C code of PROGS.DAT.

Some of the fields are managed by the C code : you can read their value, but YOU SHOULD NEVER MODIFY THEIR VALUE DIRECTLY (there are special built-in functions for that).

Technical data

entity chain; // next entity, in a chain list of entities
float ltime; // local time for entity
float teleport_time; // to avoid backing up
float spawnflags; // see possible values.

Appearance of entity

float modelindex; // index of model, in the precached list
string classname; // spawn function
string model;

The name of the file that contains the entity model.

float frame;

This is the index of the currently displayed model frame. Frames must be defined by a $frame construct in the model file, and manipulated in the code as $xxx (where xxx is the name of the frame).

float skin;

This is the index of the model skin currently displayed. If your model has more than one skin defined, then this value indicates the skin in use. You can change it freely, as long as it remains in a valid range. For instance, it's used by the armor model to show the yellow, red or green skin.

float effects;

This is a flag that defines the special light effects that the entity is subject to. This can supposedly be used to make an entity glow, or to create a glowing field of dots around it.

Position in 3D

vector origin; // position of model
// origin_x, origin_y, origin_z
vector mins; // bounding box extents reletive to origin
// mins_x, mins_y, mins_z
vector maxs; // bounding box extents reletive to origin
// maxs_x, maxs_y, maxs_z
vector size; // maxs - mins
// size_x,size_y,size_z
vector absmin; // origin + mins and maxs
// absmin_x absmin_y absmin_z
vector absmax; // origin + mins and maxs
// absmax_x absmax_y absmax_z
vector oldorigin; // old position
vector angles; // = 'pitch_angle yaw_angle flip_angle'
Quirks: setting the angles on a player entity doesn't work.

Situation of the entity

float waterlevel; // 0 = not in water, 1 = feet,
// 2 = waist, 3 = eyes
float watertype; // a content value
entity groundentity; // indicates that the entity
// moves on the ground
Since groundentity is used nowhere in progs, it's meaning is just a wild guess from a similar field in messages.

Movement in 3D

vector velocity; // = 'speed_x, speed_y, speed_z'
vector avelocity; // = 'pitch_speed yaw_speed 0',
// angle velocity
vector punchangle; // temp angle adjust from damage
// or recoil
float movetype; // type of movement
float yaw_speed; // rotation speed
float solid; // tell if entity can block the
// movements.

Monster's Behavior

entity goalentity; // Monster's movetarget or enemy
float ideal_yaw; // Monster's ideal direction, on paths
float yaw_speed; // Monster's yaw speed.
string target; // Target of a monster
string targetname; // name of the target

Automatic Behavior

float nextthink; // next time when entity must act
void() think; // function invoked when entity
// must act
void() touch; // function invoked if entity is
touched
void() use; // function invoked if entity is
// used
void() blocked; // function for doors or plats,
// called when can't push

// ### RWA, addition ###
entity other; // entity that triggered event on
// 'self'

vector movedir; // mostly for doors, but also used
// for waterjump
string message; // trigger messages
float sounds; // either a cd track number or sound
// number
string noise; // sound played on entity noise
// channel 1
string noise1; // ...
string noise2;
string noise3;

Information by Abducted :
When you want an entity to do something specific, after a certain delay (exploding, disapearing, or the like...), you set next thing to that delay (in seconds), and set think to the function to execute.

Information by Greg Lewis :
It seems that the touch function is called before the field is checked, so you can set this type in the touch function, and it will immediatly be taken into account.

Player/Monster stats and damage status

float deadflag; // tells if an entity is dead.
float health; // health level
float max_health; // players maximum health is
// stored here
float takedamage; // indicates if entity can be
// damaged
float dmg_take; // damage is accumulated through
// a frame. and sent as one single
float dmg_save; // message, so the super shotgun
// doesn't generate huge messages
entity dmg_inflictor; // entity that inflicted the damage
// (player, monster, missile, door)

Player inventory

float items; // bit flags
float armortype; // fraction of damage absorbed by armor
float armorvalue; // armor level
float weapon; // one of the IT_SHOTGUN, etc flags
string weaponmodel; // entity model for weapon
float weaponframe; // frame for weapon model
float currentammo; // ammo for current weapon
float ammo_shells; // remaining shells
float ammo_nails; // remaining nails
float ammo_rockets; // remaining rockets and grenades
float ammo_cells; // remaining lightning bolts
float impulse; // weapon changes
When set to 0, the player's weapon doesn't change. When different from zero, this field is interpreted by the Quake-C
impulse command as a request to change weapon (see ImpulseCommand).

Player Fight

entity owner; // Entity that owns this one (missiles,
// bubbles are owned by the player)
entity enemy; // personal enemy (only for monster entities)
float button0; // fire
float button1; // use
float button2; // jump

vector view_ofs; // position of player eye, relative to origin

float fixangle; // set to 1 if you want angles to change now
vector v_angle; // view or targeting angle for players
float idealpitch; // calculated pitch angle for lookup up slopes
entity aiment; // aimed antity?

Deathmatch

float frags; // number of frags
string netname; // name, in network play
float colormap; // colors of shirt and pants
float team; // team number
float flags; // ?

Fields used only by Quake-C (User defined)

These entity fields are used only by Quake-C programs, and are never referenced by the C code of Quake.exe. So you can do whatever you want with the values, so long as it's compatible with what other Quake-C modules do.

If the fields defined here are not suitable for you, you can define new fields, by adding them at the end of the defintion of fields. As a matter of fact, the number of fields in an entity (hence the size of all the instances of entity objects) is determined by Quake-C: in the PROGS.DAT header, a value named entityfields indicates to Quake.exe the size of the entity object.

Beware however that the more field you add, the more each entity will suck memory. Add just one float (4 bytes) and it will take, in memory, 4 bytes time the number of entity.

The best is to share fields between distinct classes of entities, by reusing the same position for another kind of field. If the Quake C Compiler was a real object-oriented compiler, that would be done very safely by single-inheritance (multiple-inheritance would be a deadly mistake). You will also notice that id software has made quite a lousy usage of most of the fields, defining much more than were actually needed, since they are only used by a few entities.

World fields

string wad; // name of WAD file
// with misc graphics
string map; // name of the map being
// played
float worldtype; // see below
worldtype is 0 for a medieval setting, 1 for metal, and 2 for a base setting.
These fields might soon become global variables, so don't rely too much on them.

Quake Ed fields

string killtarget;
float light_lev; // not used by game, but
// parsed by light util
float style;

Monster Behaviour

Those functions are called when these specific events happen :

void() th_stand; // when stands iddle
void() th_walk; // when is walking
void() th_run; // when is running
void() th_missile; // when a missile comes
void() th_melee; // when fighting in melee
void() th_die; // when dies

void(entity attacker, float damage) th_pain;
That function is executed when the monster takes a certain amount of damage from an attacker (a player, or another monster). Will usually cause the monster to turn against the attacker.

Monster state variables

entity oldenemy; // mad at this player before
// taking damage
float speed;
float lefty;
float search_time;
float attack_state;

float pausetime;
entity movetarget;

Player Only

float walkframe;
float attack_finished;
float pain_finished; // time when pain sound
// is finished
float invincible_finished;
float invisible_finished;
float super_damage_finished;
float radsuit_finished;
float invincible_time; // time when player cease
// to be invincible
float invincible_sound;
float invisible_time; // time when player cease
// to be invisible
float invisible_sound;
float super_time; // time when quad shot expires?
float super_sound;
float rad_time;
float fly_sound;
float axhitme; // TRUE if hit by axe
float show_hostile; // set to time+0.2 whenever a
// client fires a weapon or
// takes damage. Used to alert.
// monsters that otherwise would
// let the player go
float jump_flag; // player jump flag
float swim_flag; // player swimming sound flag
float air_finished; // when time > air_finished, start
// drowning
float bubble_count; // keeps track of the number of bubbles
string deathtype; // keeps track of how the player died

Object stuff

string mdl; // model name?
vector mangle; // angle at start. 'pitch roll yaw'
vector oldorigin; // only used by secret door
float t_length;
float t_width;

Doors

vector dest;
vector dest1;
vector dest2;
float wait; // time from firing to restarting
float delay; // time from activation to firing
entity trigger_field; // door's trigger entity
string noise4;
float aflag;
float dmg; // damage done by door when hit

Miscellaneous

float cnt; // counter
void() think1;
vector finaldest;
vector finalangle;
//
// triggers
//
float count; // for counting triggers
//
// plats / doors / buttons
//
float lip;
float state;
vector pos1;
vector pos2; // top and bottom positions
float height;
//
// sounds
//
float waitmin;
float waitmax;
float distance;
float volume;