Programming-QuakeC-stuff-in-Xonotic.md

   1 **Note:** The article is written as developer notes to ease developer tasks and save QuakeC terms here.
   2
   3 # CSQC, MENUQC, SVQC and GAMEQC blocks
   4
   5 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).
   6
   7 Menu and HUD code are actually separated as they run in 2 distinct programs: ***csprogs.dat*** and ***menu.dat***
   8
   9 Server program is ***progs.dat***
  10
  11 - Code inside a **`#ifdef CSQC`** block is part of the client code and will be compiled to **csprogs.dat**
  12
  13 - Code inside a **`#ifdef MENUQC`** block is part of the menu code and will be compiled to **menu.dat**
  14
  15 - Code inside a **`#ifdef SVQC`** block is part of the menu code and will be compiled to **progs.dat**
  16
  17 - Also, code inside a **`#ifdef GAMEQC`** block is part of both client (not menu) and server code.
  18
  19 ### A bit of explanation about the use of each type of cvars
  20
  21 - **g_*** cvars:
  22
  23 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).
  24
  25 - **sv_*** cvars:
  26
  27 Example: `sv_campcheck` is clearly a server cvar (**sv_*** cvars are server cvars), only can be declared inside a **`#ifdef SVQC`** block.
  28
  29 - **cl_*** cvars:
  30
  31 Example: `cl_chatsound` is clearly a client cvar (**cl_*** cvars are client cvars), only can be declared inside a **`#ifdef CSQC`** block.
  32
  33 - **hud_*** cvars:
  34
  35 Example: `hud_progressbar_alpha` is a client cvar (**hud_*** cvars belong to client cvars), only can be declared inside a **`#ifdef CSQC`** block.
  36
  37
  38 <br />
  39
  40 # MUTATOR functions (from: [`qcsrc/client/mutators/events.qh`](https://timepath.github.io/scratchspace/d8/d0e/client_2mutators_2events_8qh_source.html), [`qcsrc/common/mutators/events.qh`](https://timepath.github.io/scratchspace/d4/d95/common_2mutators_2events_8qh_source.html), [`qcsrc/server/mutators/events.qh`](https://timepath.github.io/scratchspace/d6/ddd/server_2mutators_2events_8qh_source.html))
  41
  42 ### How to use MUTATOR functions:
  43
  44 You can look the following link if you're trying/testing your own mutator: [Writing your first mutator](writing-your-first-mutator)
  45
  46 **Attention:** to use a hook, first register your mutator using `REGISTER_MUTATOR`, then create your function using `MUTATOR_HOOKFUNCTION`.
  47
  48
  49 - **`REGISTER_MUTATOR`**
  50
  51 Registers a new `MUTATOR_HOOKFUNCTION`.
  52 ```c
  53 REGISTER_MUTATOR(new_mutator_name, some_variable);
  54 ```
  55
  56
  57 - **`MUTATOR_HOOKFUNCTION`**
  58
  59 Creates a function and calls `new_mutator_name` (from `REGISTER_MUTATOR`) and one of `#define MUTATOR()` (from `qcsrc/server/mutators/events.qh` main hooks).
  60
  61 Example:
  62 ```c
  63 MUTATOR_HOOKFUNCTION(new_mutator_name, events.qh_main_hook)
  64 {
  65     // whatever does
  66 }
  67 ```
  68
  69 - **`MUTATOR_CALLHOOK`**
  70
  71 Calls some `MUTATOR_HOOKFUNCTION`.
  72 ```c
  73 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook);
  74 ```
  75
  76 There are different versions and depends how many variables need to be called in a `MUTATOR_HOOKFUNCTION`:
  77
  78 1 `MUTATOR_HOOKFUNCTION` and 1 variable:
  79
  80 ```c
  81 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable);
  82 ```
  83
  84 1 `MUTATOR_HOOKFUNCTION` and 2 variables:
  85
  86 ```c
  87 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable, some_variable);
  88 ```
  89
  90 1 `MUTATOR_HOOKFUNCTION` and 3 variables:
  91
  92 ```c
  93 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable, some_variable, some_variable);
  94 ```
  95
  96 1 `MUTATOR_HOOKFUNCTION` and multiple variables:
  97
  98 ```c
  99 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable, some_variable, some_variable, some_variable, ...);
 100 ```
 101
 102 <br />
 103
 104 ## List of MUTATOR functions
 105
 106 You can look the MUTATOR functions in:
 107
 108 - **COMMON:** [`qcsrc/common/mutators/events.qh`](https://timepath.github.io/scratchspace/d4/d95/common_2mutators_2events_8qh.html)
 109
 110 - **CLIENT:** [`qcsrc/client/mutators/events.qh`](https://timepath.github.io/scratchspace/d8/d0e/client_2mutators_2events_8qh.html)
 111
 112 - **SERVER:** [`qcsrc/server/mutators/events.qh`](https://timepath.github.io/scratchspace/d6/ddd/server_2mutators_2events_8qh.html)
 113
 114 <br />
 115 <br />
 116
 117 # Weapon functions
 118
 119 ## A bit of introduction
 120
 121 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.
 122
 123 - **Think** function makes the weapon shot react on what to do.
 124 - **Touch** function makes the weapon shot react against some element where touch (like player, monster, vehicle, ...).
 125 - **Explode** function makes the weapon explosion react.
 126 - **Attack/Whatever** function is where the weapon attack executes, keep in mind that it has the other functions attached to be executed.
 127
 128 You can look the example of this weapon code:
 129 - [**devastator.qh**](https://timepath.github.io/scratchspace/d9/dfa/devastator_8qh_source.html)
 130 - [**devastator.qc**](https://timepath.github.io/scratchspace/d9/d5d/devastator_8qc_source.html)
 131
 132 <br />
 133
 134 ## List of weapon functions
 135
 136 This is a created list of functions to modify/create weapons. There may be incomplete explanations for each function.
 137
 138 There are contents taken from [`qcsrc/common/weapons/all.qh`](https://timepath.github.io/scratchspace/d0/ddd/weapons_2all_8qh_source.html)
 139
 140 **WARNING:** The contents may content wonky code, and the interactions can change and not do the same what happens here.
 141
 142 <br />
 143
 144 - [**W_SetupShot_Dir**](https://timepath.github.io/scratchspace/d4/d3f/tracing_8qh.html#aff0ea351757ee6caf83b25d12d18656c)
 145
 146 ```c
 147 W_SetupShot_Dir(
 148         ent,
 149         wepent,
 150         s_forward,
 151         antilag,
 152         recoil,
 153         snd,
 154         chan,
 155         maxdamage,
 156         deathtype
 157 )
 158 ```
 159
 160 - [**W_SetupProjVelocity_Explicit**](https://timepath.github.io/scratchspace/d7/d31/tracing_8qc.html#a55f8f2b1828413bfb123a5fcb61b9f8e)
 161
 162 ```c
 163 void W_SetupProjVelocity_Explicit(
 164     entity      proj,
 165     vector      dir,
 166     vector      upDir,
 167     float       pSpeed,
 168     float       pUpSpeed,
 169     float       pZSpeed,
 170     float       spread,
 171     float       forceAbsolute
 172 )
 173 ```
 174
 175 - [**W_MuzzleFlash**](https://timepath.github.io/scratchspace/d0/ddd/weapons_2all_8qh_source.html)(located in **`qcsrc/common/weapons/all.qh`** line 406)
 176
 177 In the moment when player shots the weapon, weapon flashes.
 178
 179 **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).
 180
 181 ```c
 182 void W_MuzzleFlash(Weapon thiswep, entity actor, .entity weaponentity, vector shotorg, vector shotdir);
 183 ```
 184
 185 - [**Weapon selection functions**](https://timepath.github.io/scratchspace/d8/d6b/selection_8qh.html)
 186 (located in **`qcsrc/server/weapons/selection.qh`**)
 187
 188 - [**Weapon decrease ammo, speed factor, rate factor, reload functions**](https://timepath.github.io/scratchspace/d5/de0/weaponsystem_8qc.html)
 189 (located in **`qcsrc/server/weapons/weaponsystem.qh`**)
 190
 191 <br />
 192
 193 # HUD, Menu and Draw functions
 194
 195 You can look the draw functions where HUD is being drawn:
 196 - [**Draw functions and macros (`qcsrc/client/draw.qh`)**](https://timepath.github.io/scratchspace/d5/d8d/client_2draw_8qh_source.html)
 197
 198 More info inside the code where you can draw/print HUD and menu:
 199 - [**Globals, constants, fonts, prints, error cmds, vector stuff, conversion functions and all drawing/printing HUDs/menus/characters related (`qcsrc/dpdefs/upstream/menudefs.qc`)**](https://timepath.github.io/scratchspace/d8/de2/menudefs_8qc_source.html)
 200
 201 <br />
 202
 203 # Gamemodes
 204
 205 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`
 206
 207 Making gamemodes doesn't seem easy. There's a little explanation of what does each element.
 208
 209 ### Generated files for gamemodes:
 210
 211 [`qcsrc/common/gamemodes/gamemode/_mod.inc`](https://timepath.github.io/scratchspace/d9/d67/common_2gamemodes_2__mod_8inc_source.html) generated file where the includes of each gamemode are stored.
 212
 213 [`qcsrc/common/gamemodes/gamemode/_mod.qh`](https://timepath.github.io/scratchspace/d7/d0b/common_2gamemodes_2__mod_8qh_source.html) generated file where the includes of each gamemode are stored.
 214
 215 <br />
 216
 217 ### Gamemode files:
 218
 219 - Server type:
 220
 221 `qcsrc/common/gamemodes/gamemode/name_of_gamemode/sv_name_of_gamemode.qc`
 222
 223 `qcsrc/common/gamemodes/gamemode/name_of_gamemode/sv_name_of_gamemode.qh`
 224
 225 <br />
 226
 227 - Client type:
 228
 229 `qcsrc/common/gamemodes/gamemode/name_of_gamemode/cl_name_of_gamemode.qc`
 230
 231 `qcsrc/common/gamemodes/gamemode/name_of_gamemode/cl_name_of_gamemode.qh`
 232
 233 <br />
 234
 235 - Base:
 236
 237 `qcsrc/common/gamemodes/gamemode/name_of_gamemode/name_of_gamemode.qc`
 238
 239 `qcsrc/common/gamemodes/gamemode/name_of_gamemode/name_of_gamemode.qh`
 240
 241 `qcsrc/common/gamemodes/gamemode/name_of_gamemode/_mod.inc` generated file where the includes of a gamemode is generated.
 242
 243 `qcsrc/common/gamemodes/gamemode/name_of_gamemode/_mod.qh` generated file where the includes of a gamemode is generated.
 244
 245 <br />
 246
 247 ### Optional things (if necessary):
 248
 249 [`qcsrc/common/ent_cs.qc`](https://timepath.github.io/scratchspace/d5/dff/ent__cs_8qc_source.html) (if an `ENTCS_PROP()` is needed for a gamemode)
 250
 251 [`qcsrc/common/mutators/mutator/waypoints/all.inc`](https://timepath.github.io/scratchspace/d2/d2b/mutators_2mutator_2waypoints_2all_8inc_source.html) where `REGISTER_WAYPOINT` can interact the situation of waypoints.
 252
 253 <br />
 254
 255 ### Notifications, applying BADCVAR and displaying gamemode in the menu:
 256
 257 [`qcsrc/common/notifications/all.inc`](https://timepath.github.io/scratchspace/d9/d09/notifications_2all_8inc_source.html) where notifications output appears in the scenario.
 258
 259 [`qcsrc/common/notifications/all.qh`](https://timepath.github.io/scratchspace/dc/d8f/notifications_2all_8qh_source.html) where `CASE(CPID, NAME_OF_ELEMENT)` is needed for a gamemode.
 260
 261 [`qcsrc/menu/xonotic/util.qc`](https://timepath.github.io/scratchspace/df/d9b/menu_2xonotic_2util_8qc_source.html) where gamemodes can appear in the main menu (Multiplayer > Create). `GAMETYPE(MAPINFO_TYPE_NAME_OF_GAMEMODE) \`
 262
 263 [`qcsrc/server/world.qc`](https://timepath.github.io/scratchspace/dd/dbe/world_8qc_source.html)  where `BADCVAR(g_*)` for each gamemode are stored.
 264
 265 <br />
 266
 267 ### Configuration files where gamemodes interact:
 268
 269 `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.
 270
 271 `xonotic-data.pk3dir/gamemodes-client.cfg` where client gamestart hooks cvars connect.
 272
 273 `xonotic-data.pk3dir/notifications.cfg` where notifications need to be activated in the scenario.
 274
 275 <br />
 276
 277 ### Menu and HUD icons:
 278
 279 `gfx/menu/luma/gametype_nameshortcut.tga`
 280
 281 `gfx/menu/luminos/gametype_nameshortcut.tga`
 282
 283 `gfx/menu/wickedx/gametype_nameshortcut.tga`
 284
 285 `gfx/menu/xaw/gametype_nameshortcut.tga`
 286
 287 (Example: `gametype_tdm.tga` is an icon of Team Deathmatch)
 288
 289 <br />
 290
 291 ## Samples
 292
 293 There are good examples of the commits and repositories of people who developed gamemodes:
 294
 295 - [**Lyberta's GunGame gametype commits**](https://gitlab.com/xonotic/xonotic-data.pk3dir/-/merge_requests/482/diffs)
 296
 297 Taken from: https://forums.xonotic.org/showthread.php?tid=7314
 298
 299 You can look and test the [**Lyberta's GunGame gametype repository**](https://gitlab.com/xonotic/xonotic-data.pk3dir/-/tree/Lyberta/GunGame)
 300
 301 - [**How Survival gamemode was developed (first commit)**](https://gitlab.com/xonotic/xonotic-data.pk3dir/-/commit/8f61a40877542ac94baa74c5ed653c77b77bd855)
 302
 303 It's recommended use the final product in this [**repository**](https://gitlab.com/xonotic/xonotic-data.pk3dir/-/tree/Mario/survival). Many changes have been influenced.
 304
 305 [**SMB modpack repository**](https://github.com/MarioSMB/modpack/tree/master/mod/common/gamemodes/survival) has added Survival gamemode and others.
 306
 307 # Effects
 308
 309 Spawns effect particle in-game.
 310
 311 The effects can be used with `Send_Effect(effect, org, vel, howmany)` function to test the effects from [**qcsrc/common/effects/all.inc**](https://timepath.github.io/scratchspace/d9/d95/effects_2all_8inc_source.html)
 312
 313 **Send_Effect** function definition is inside: [**qcsrc/common/effects/effect.qh**](https://timepath.github.io/scratchspace/d5/de6/effect_8qh_source.html)
 314
 315 For example, you can test the smokes, using `EFFECT_SMOKE_LARGE`:
 316 ```c
 317 Send_Effect(EFFECT_SMOKE_LARGE, this.origin, '0 0 0', 1);
 318 ```
 319
 320 EFFECT list: [**qcsrc/common/effects/all.inc**](https://timepath.github.io/scratchspace/d9/d95/effects_2all_8inc_source.html)
 321
 322 <br />