Functions-and-other-programming-QuakeC-things-in-Xonotic.md

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