Difference between revisions of "QuakeC Globals"

Revision as of 23:34, 30 July 2023

Globals are variables that aren't entity specific and can be accessed from anywhere at any time. Much like fields, they're broken down into system globals and QuakeC globals. Valid global data types include string, vector, float, and entity. Globals are declared via:

    datatype globalName;

System globals are globals defined within the engine itself and must be present for the game to work. These are always defined before anything else. The end of them is denoted by the void end_sys_globals; declaration. System globals must always be declared in the order defined within the vanilla QuakeC files as they are linked by memory offsets internally. Changing the order will break logic.

QuakeC globals are standard globals that have no internal linkage and can be defined freely anywhere. Note that these are not stored between maps and will be reset upon changing levels.

System Globals

The following globals should be defined in the exact order of this list, otherwise memory offset errors can occur.

entity self - The entity that the physics frame is currently processing.
entity other - If a collision is occurring, this is the entity self is colliding with. This should only be used from touch() functions.
entity world - The default world entity. This entity's fields cannot be written to directly and it is considered null in conditional checks.
float time - The current game time in seconds.
float frametime - The difference between the previous physics frame and the current one in seconds.
float force_retouch - If greater than 0, relinks all entities into the world. Useful for getting entities to touch newly created triggers. This should be set to 2 to properly reset everything since setting it to 1 will only relink entities starting from the current self onward.
string mapname - The name of the current map e.g. start, e2m1, etc.
float deathmatch - If non-zero, PvP is enabled. If set to 2, uses the classic deathmatch rules.
float coop - If non-zero, co-op is enabled.
float teamplay - If non-zero while PvP is active, team PvP is enabled. If set to 1, friendly fire is disabled.
float serverflags - Tracks the state of the game across the entire session. This doesn't get reset between level changes. The first 4 bits are reserved for the runes with each bit corresponding to its respective episode e.g. episode 1 is the first bit. If this is non-zero when going back to the start map, the player's inventory will be cleared.
float total_secrets - The total secret count for the current map.
float total_monsters - The total monster count for the current map.
float found_secrets - How many secrets have been found in the current map.
float killed_monsters - How many monsters have been killed in the current map.

Parms store information about each player when moving between levels. Players have their own set of parms, but the globals act as an interface for setting them. These can be changed to however the modder wants to encode information, but below is how they're handled by default.

float parm1 - Stores the player's items field minus any keys and power ups.
float parm2 - Stores the player's health. This is capped between 50 and 100.
float parm3 - Stores the amount of armor the player has.
float parm4 - Stores the amount of shells the player has. This has a minimum amount of 25.
float parm5 - Stores the amount of nails the player has.
float parm6 - Stores the amount of rockets the player has.
float parm7 - Stores the amount of cells the player has.
float parm8 - Stores the player's weapon field.
float parm9 - Stores the player's armor damage reduction multiplied by 100 to give two decimal places of accuracy (decimal places beyond this get discarded).
float parm10
float parm11
float parm12
float parm13
float parm14
float parm15
float parm16

-Unused

The following are used by makevectors() to store the local axes that the function generates from the passed angles.

vector v_forward - The facing direction of the passed angles.
vector v_up - The direction pointing directly up from the facing direction of the passed angles.
vector v_right - The direction pointing directly to the right of the facing direction of the passed angles.

The following are used by traceline() to pass information from the function to QuakeC.

float trace_allsolid - If TRUE, the trace was stuck entirely in solids.
float trace_startsolid - If TRUE, the trace started inside of a solid.
float trace_fraction - The fraction of the total distance the trace traveled before stopping. Ranges from [0, 1].
vector trace_endpos - The position the trace stopped.
vector trace_plane_normal - The normal of the plane that the trace hit.
float trace_plane_dist - The distance from the world origin of the plane that the trace hit. This is d in the plane equation ax + by + cz + d = 0.
entity trace_ent - The entity that the trace hit.
float trace_inopen - If TRUE, the trace traveled through open air.
float trace_inwater - If TRUE, the trace traveled through a liquid.
entity msg_entity - When sending a network message to a specific player via MSG_ONE, this is the player the message is sent to.

Below are a special set of global functions the engine calls. These have no internal definitions so the function body must be defined somewhere in QuakeC to work. As such, their functionality is entirely customizable.

void() main - Unused.
void() StartFrame - Called at the start of every physics frame before anything else is processed.
void() PlayerPreThink - Called before the player's physics is ran.
void() PlayerPostThink - Called after the player's physics is ran.
void() ClientKill - Called when the player kills themselves via the console command.
void() ClientConnect - Called when a player joins the game, either for the first time or from changing levels.
void() PutClientInServer - Called when a player is set to spawn or respawn.
void() ClientDisconnect - Called when a player leaves the game, either from disconnecting or changing levels.
void() SetNewParms - Sets the default parms for the player when they join the game for the first time or when respawning in deathmatch.
void() SetChangeParms - Called when the player is about to change levels and their parms need to be set so they can be decoded when joining the new map.

QuakeC Globals

These can be defined anywhere in any order. Since they can't be set from the map editor they're free to be changed and removed, but doing so may break saves so exercise caution. It may be better to just deprecate them to keep save compatibility.

World Globals

string string_null - Null string. This differs from "" in that it's not considered a valid string in conditional checks while "" is.
float skill - The current difficulty of the map. Can be one of the following:

0 - Easy

1 - Normal

2 - Hard

3 - Nightmare

float framecount - The total number of physics frames the server has processed.
float gameover - If TRUE, the server is changing levels and players should not be considered fully disconnected.

Entity Globals

entity activator - The entity that's considered the activator when calling SUB_UseTargets().
entity damage_attacker - The source of the attack when an entity takes damage.
entity newmis - Set by launch_spike() to store the newly created projectile entity.

Monster Entity Globals

float movedist - When attempting to move, stores how far the current monster is trying to travel in map units.

@@ Line 1: / Line 1: @@
-Globals are variables that aren't entity specific and can be accessed from anywhere at any time. Much like fields, they're broken down into system globals and QuakeC globals. Valid global data types include <code>string</code>, <code>vector</code>, <code>float</code>, and <code>entity</code>. Function pointers are also allowed by specifying the return type and any parameters that need to be passed to it. The return type should be void if it doesn't return anything. Globals are declared via:
+Globals are variables that aren't entity specific and can be accessed from anywhere at any time. Much like fields, they're broken down into system globals and QuakeC globals. Valid global data types include <code>string</code>, <code>vector</code>, <code>float</code>, and <code>entity</code>. Globals are declared via:
       datatype globalName;
-     returntype(datatype param1) globalFunction;
-Global functions are less useful but have a possible usage with setting up world data processing. When setting a function pointer, only the name of the function is needed e.g. <code>globalFunction = MyFunction;</code>. It can then be called like any other function by invoking the pointer.
 System globals are globals defined within the engine itself and must be present for the game to work. These are always defined before anything else. The end of them is denoted by the void <code>end_sys_globals;</code> declaration. System globals must always be declared in the order defined within the vanilla QuakeC files as they are linked by memory offsets internally. Changing the order will break logic.