Programming QuakeC stuff in Xonotic

Note: The article is written as developer notes to ease developer tasks and save QuakeC terms here.

Table of Contents

CSQC, MENUQC, SVQC and GAMEQC blocks

MUTATOR functions

2.1. How to use MUTATOR functions

2.2. List of MUTATOR functions

Weapon functions

3.1. A bit of introduction

3.2. List of weapon functions

HUD, Menu and Draw functions

Gamemodes

5.1. Samples

Effects

CSQC, MENUQC, SVQC and GAMEQC blocks

Xonotic uses the csprogs.dat from the server you're playing on, as it must match the server's progs.dat code (whereas your menu.dat is always your local copy).

Menu and HUD code are actually separated as they run in 2 distinct programs: csprogs.dat and menu.dat

Server program is progs.dat

Code inside a #ifdef CSQC block is part of the client code and will be compiled to csprogs.dat
Code inside a #ifdef MENUQC block is part of the menu code and will be compiled to menu.dat
Code inside a #ifdef SVQC block is part of the menu code and will be compiled to progs.dat
Also, code inside a #ifdef GAMEQC block is part of both client (not menu) and server code.

A bit of explanation about the use of each type of cvars

g_* cvars:

Example: g_balance_grapplehook_speed_fly is clearly a server or game cvar (g_* cvars are server and game cvars), so you CAN'T declare it within a #ifdef CSQC block. This type of cvar only can be declared inside a #ifdef SVQC or #ifdef GAMEQC block (if possible).

sv_* cvars:

Example: sv_campcheck is clearly a server cvar (sv_* cvars are server cvars), only can be declared inside a #ifdef SVQC block.

cl_* cvars:

Example: cl_chatsound is clearly a client cvar (cl_* cvars are client cvars), only can be declared inside a #ifdef CSQC block.

hud_* cvars:

Example: hud_progressbar_alpha is a client cvar (hud_* cvars belong to client cvars), only can be declared inside a #ifdef CSQC block.

MUTATOR functions

How to use MUTATOR functions

You can look the following link if you're trying/testing your own mutator: Writing your first mutator

Attention: to use a hook, first register your mutator using REGISTER_MUTATOR, then create your function using MUTATOR_HOOKFUNCTION.

REGISTER_MUTATOR

Registers a new MUTATOR_HOOKFUNCTION.

REGISTER_MUTATOR(new_mutator_name, some_variable);

MUTATOR_HOOKFUNCTION

Creates a function and calls new_mutator_name (from REGISTER_MUTATOR) and one of #define MUTATOR() (from qcsrc/server/mutators/events.qh main hooks).

Example:

MUTATOR_HOOKFUNCTION(new_mutator_name, events.qh_main_hook)
{
    // whatever does
}

MUTATOR_CALLHOOK

Calls some MUTATOR_HOOKFUNCTION.

MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook);

There are different versions and depends how many variables need to be called in a MUTATOR_HOOKFUNCTION:

1 MUTATOR_HOOKFUNCTION and 1 variable:

MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable);

1 MUTATOR_HOOKFUNCTION and 2 variables:

MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable, some_variable);

1 MUTATOR_HOOKFUNCTION and 3 variables:

MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable, some_variable, some_variable);

1 MUTATOR_HOOKFUNCTION and multiple variables:

MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable, some_variable, some_variable, some_variable, ...);

List of MUTATOR functions

You can look the MUTATOR functions in:

COMMON: qcsrc/common/mutators/events.qh
CLIENT: qcsrc/client/mutators/events.qh
SERVER: qcsrc/server/mutators/events.qh

Weapon functions

A bit of introduction

You'll need understand that weapons can be interacted with autocvars variables (example: float autocvar_g_balance_someweapon_speed;) and each weapon with .qh file where cvars are declared without the need to declare using autocvar_blabla.... Think, touch, explode and those types of functions can be declared within an attack function and whatever it is called. Note that there are also METHODs that are necessary for the weapon to work.

Think function makes the weapon shot react on what to do.
Touch function makes the weapon shot react against some element where touch (like player, monster, vehicle, ...).
Explode function makes the weapon explosion react.
Attack/Whatever function is where the weapon attack executes, keep in mind that it has the other functions attached to be executed.

You can look the example of this weapon code:

List of weapon functions

This is a created list of functions to modify/create weapons. There may be incomplete explanations for each function.

There are contents taken from qcsrc/common/weapons/all.qh

WARNING: The contents may content wonky code, and the interactions can change and not do the same what happens here.

W_SetupShot_Dir

W_SetupShot_Dir(
	ent,
 	wepent,
 	s_forward,
 	antilag,
 	recoil,
 	snd,
 	chan,
 	maxdamage,
 	deathtype 
)

W_SetupProjVelocity_Explicit

void W_SetupProjVelocity_Explicit(
    entity 	proj,
    vector 	dir,
    vector 	upDir,
    float 	pSpeed,
    float 	pUpSpeed,
    float 	pZSpeed,
    float 	spread,
    float 	forceAbsolute 
)

W_MuzzleFlash(located in qcsrc/common/weapons/all.qh line 406)

In the moment when player shots the weapon, weapon flashes.

Note: write #ifdef SVQC at the start of using this function, and write with #endif after declared the function (only can do this if the code needs to be executed, although maybe you need more functions/things in the code inside this).

void W_MuzzleFlash(Weapon thiswep, entity actor, .entity weaponentity, vector shotorg, vector shotdir);

Weapon selection functions (located in qcsrc/server/weapons/selection.qh)
Weapon decrease ammo, speed factor, rate factor, reload functions (located in qcsrc/server/weapons/weaponsystem.qh)

HUD, Menu and Draw functions

You can look the draw functions where HUD is being drawn:

Draw functions and macros (qcsrc/client/draw.qh)

More info inside the code where you can draw/print HUD and menu:

Globals, constants, fonts, prints, error cmds, vector stuff, conversion functions and all drawing/printing HUDs/menus/characters related (qcsrc/dpdefs/upstream/menudefs.qc)

Gamemodes

Keep in mind that to develop a gamemode, you need a map having enabled inside its name_of_map.mapinfo file this: gametype shortcut_of_gamemode. (example: gametype tdm (tdm is Team Deathmatch). After modifying the map file, compress the map contents, save as .zip and rename the extension to .pk3

Making gamemodes doesn't seem easy. There's a little explanation of what does each element.

Generated files for gamemodes:

qcsrc/common/gamemodes/gamemode/_mod.inc generated file where the includes of each gamemode are stored.

qcsrc/common/gamemodes/gamemode/_mod.qh generated file where the includes of each gamemode are stored.

Gamemode files:

Server type:

qcsrc/common/gamemodes/gamemode/name_of_gamemode/sv_name_of_gamemode.qc

qcsrc/common/gamemodes/gamemode/name_of_gamemode/sv_name_of_gamemode.qh

Client type:

qcsrc/common/gamemodes/gamemode/name_of_gamemode/cl_name_of_gamemode.qc

qcsrc/common/gamemodes/gamemode/name_of_gamemode/cl_name_of_gamemode.qh

Base:

qcsrc/common/gamemodes/gamemode/name_of_gamemode/name_of_gamemode.qc

qcsrc/common/gamemodes/gamemode/name_of_gamemode/name_of_gamemode.qh

qcsrc/common/gamemodes/gamemode/name_of_gamemode/_mod.inc generated file where the includes of a gamemode is generated.

qcsrc/common/gamemodes/gamemode/name_of_gamemode/_mod.qh generated file where the includes of a gamemode is generated.

Optional things (if necessary):

qcsrc/common/ent_cs.qc (if an ENTCS_PROP() is needed for a gamemode)

qcsrc/common/mutators/mutator/waypoints/all.inc where REGISTER_WAYPOINT can interact the situation of waypoints.

Notifications, applying BADCVAR and displaying gamemode in the menu:

qcsrc/common/notifications/all.inc where notifications output appears in the scenario.

qcsrc/common/notifications/all.qh where CASE(CPID, NAME_OF_ELEMENT) is needed for a gamemode.

qcsrc/menu/xonotic/util.qc where gamemodes can appear in the main menu (Multiplayer > Create). GAMETYPE(MAPINFO_TYPE_NAME_OF_GAMEMODE) \

qcsrc/server/world.qc where BADCVAR(g_*) for each gamemode are stored.

Configuration files where gamemodes interact:

xonotic-data.pk3dir/gamemodes-server.cfg where server gamestart hooks, gametype vote hooks, respawn delay/waves/weapon_stay cvars and gamemode game/server cvars connect.

xonotic-data.pk3dir/gamemodes-client.cfg where client gamestart hooks cvars connect.

xonotic-data.pk3dir/notifications.cfg where notifications need to be activated in the scenario.

Menu and HUD icons:

gfx/menu/luma/gametype_nameshortcut.tga

gfx/menu/luminos/gametype_nameshortcut.tga

gfx/menu/wickedx/gametype_nameshortcut.tga

gfx/menu/xaw/gametype_nameshortcut.tga

(Example: gametype_tdm.tga is an icon of Team Deathmatch)

Samples

There are good examples of the commits and repositories of people who developed gamemodes:

Lyberta's GunGame gametype commits

Taken from: https://forums.xonotic.org/showthread.php?tid=7314

You can look and test the Lyberta's GunGame gametype repository

How Survival gamemode was developed (first commit)

It's recommended use the final product in this repository. Many changes have been influenced.

SMB modpack repository has added Survival gamemode and others.

Effects

Spawns effect particle in-game.

The effects can be used with Send_Effect(effect, org, vel, howmany) function to test the effects from qcsrc/common/effects/all.inc

Send_Effect function definition is inside: qcsrc/common/effects/effect.qh

For example, you can test the smokes, using EFFECT_SMOKE_LARGE:

Send_Effect(EFFECT_SMOKE_LARGE, this.origin, '0 0 0', 1);

EFFECT list: qcsrc/common/effects/all.inc