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
  34 <br />
  35
  36 # 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))
  37
  38 ### How to use MUTATOR functions:
  39
  40 **Attention:** to use a hook, first register your mutator using `REGISTER_MUTATOR`, then create your function using `MUTATOR_HOOKFUNCTION`.
  41
  42
  43 - **`REGISTER_MUTATOR`**
  44
  45 Registers a new `MUTATOR_HOOKFUNCTION`.
  46 ```c
  47 REGISTER_MUTATOR(new_mutator_name, some_variable);
  48 ```
  49
  50
  51 - **`MUTATOR_HOOKFUNCTION`**
  52
  53 Creates a function and calls `new_mutator_name` (from `REGISTER_MUTATOR`) and one of `#define MUTATOR()` (from `qcsrc/server/mutators/events.qh` main hooks).
  54
  55 Example:
  56 ```c
  57 MUTATOR_HOOKFUNCTION(new_mutator_name, events.qh_main_hook)
  58 {
  59     // whatever does
  60 }
  61 ```
  62
  63 - **`MUTATOR_CALLHOOK`**
  64
  65 Calls some `MUTATOR_HOOKFUNCTION`.
  66 ```c
  67 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook);
  68 ```
  69
  70 There are different versions and depends how many variables need to be called in a `MUTATOR_HOOKFUNCTION`:
  71
  72 1 `MUTATOR_HOOKFUNCTION` and 1 variable:
  73
  74 ```c
  75 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable);
  76 ```
  77
  78 1 `MUTATOR_HOOKFUNCTION` and 2 variables:
  79
  80 ```c
  81 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable, some_variable);
  82 ```
  83
  84 1 `MUTATOR_HOOKFUNCTION` and 3 variables:
  85
  86 ```c
  87 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable, some_variable, some_variable);
  88 ```
  89
  90 1 `MUTATOR_HOOKFUNCTION` and multiple variables:
  91
  92 ```c
  93 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable, some_variable, some_variable, some_variable, ...);
  94 ```
  95
  96 <br />
  97
  98 ## List of MUTATOR functions
  99
 100 You can look the MUTATOR functions in:
 101
 102 - **COMMON:** [`qcsrc/common/mutators/events.qh`](https://timepath.github.io/scratchspace/d4/d95/common_2mutators_2events_8qh.html)
 103
 104 - **CLIENT:** [`qcsrc/client/mutators/events.qh`](https://timepath.github.io/scratchspace/d8/d0e/client_2mutators_2events_8qh.html)
 105
 106 - **SERVER:** [`qcsrc/server/mutators/events.qh`](https://timepath.github.io/scratchspace/d6/ddd/server_2mutators_2events_8qh.html)
 107
 108 <br />
 109 <br />
 110
 111 # WEAPON functions
 112
 113 ## A bit of introduction
 114
 115 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.
 116
 117 - **Think** function makes the weapon shot react on what to do.
 118 - **Touch** function makes the weapon shot react against some element where touch (like player, monster, vehicle, ...).
 119 - **Explode** function makes the weapon explosion react.
 120 - **Attack/Whatever** function is where the weapon attack executes, keep in mind that it has the other functions attached to be executed.
 121
 122 You can look the example of this weapon code:
 123 - [**devastator.qh**](https://timepath.github.io/scratchspace/d9/dfa/devastator_8qh_source.html)
 124 - [**devastator.qc**](https://timepath.github.io/scratchspace/d9/d5d/devastator_8qc_source.html)
 125
 126 <br />
 127
 128 ## List of WEAPON functions
 129
 130 This is a created list of functions to modify/create weapons. There may be incomplete explanations for each function.
 131
 132 There are contents taken from [`qcsrc/common/weapons/all.qh`](https://timepath.github.io/scratchspace/d0/ddd/weapons_2all_8qh_source.html)
 133
 134 **WARNING:** The contents may content wonky code, and the interactions can change and not do the same what happens here.
 135
 136 <br />
 137
 138 - [**W_SetupShot_Dir**](https://timepath.github.io/scratchspace/d4/d3f/tracing_8qh.html#aff0ea351757ee6caf83b25d12d18656c)
 139
 140 ```c
 141 W_SetupShot_Dir(
 142         ent,
 143         wepent,
 144         s_forward,
 145         antilag,
 146         recoil,
 147         snd,
 148         chan,
 149         maxdamage,
 150         deathtype
 151 )
 152 ```
 153
 154 - [**W_SetupProjVelocity_Explicit**](https://timepath.github.io/scratchspace/d7/d31/tracing_8qc.html#a55f8f2b1828413bfb123a5fcb61b9f8e)
 155
 156 ```c
 157 void W_SetupProjVelocity_Explicit(
 158     entity      proj,
 159     vector      dir,
 160     vector      upDir,
 161     float       pSpeed,
 162     float       pUpSpeed,
 163     float       pZSpeed,
 164     float       spread,
 165     float       forceAbsolute
 166 )
 167 ```
 168
 169 - [**W_MuzzleFlash**](https://timepath.github.io/scratchspace/d0/ddd/weapons_2all_8qh_source.html)(located in **`qcsrc/common/weapons/all.qh`** line 406)
 170
 171 In the moment when player shots the weapon, weapon flashes.
 172
 173 **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 which needs execute can do this, although maybe you need more functions/things in the code inside this).
 174
 175 ```c
 176 void W_MuzzleFlash(Weapon thiswep, entity actor, .entity weaponentity, vector shotorg, vector shotdir);
 177 ```
 178
 179 - [**Weapon selection functions**](https://timepath.github.io/scratchspace/d8/d6b/selection_8qh.html)
 180 (located in **`qcsrc/server/weapons/selection.qh`**)
 181
 182 - [**Weapon decrease ammo, speed factor, rate factor, reload functions**](https://timepath.github.io/scratchspace/d5/de0/weaponsystem_8qc.html)
 183 (located in **`qcsrc/server/weapons/weaponsystem.qh`**)
 184
 185 <br />
 186
 187 # HUD, Menu and Draw functions
 188
 189 You can look the draw functions where HUD is being drawn:
 190 - [**Draw functions and macros (`qcsrc/client/draw.qh`)**](https://timepath.github.io/scratchspace/d5/d8d/client_2draw_8qh_source.html)
 191
 192 More info inside the code where you can draw/print HUD and menu:
 193 - [**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)
 194
 195 <br />
 196
 197 AND... STILL more things in process