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. Some references are taken from `events.qh`.
   2
   3
   4 # MUTATOR functions (from: `qcsrc/server/mutators/events.qh`)
   5
   6 ### Introduction
   7
   8 How to use MUTATOR functions:
   9
  10 **Attention:** to use a hook, first register your mutator using `REGISTER_MUTATOR`, then create your function using `MUTATOR_HOOKFUNCTION`.
  11
  12
  13 **`REGISTER_MUTATOR`**
  14
  15 Registers a new `MUTATOR_HOOKFUNCTION`.
  16 ```
  17 REGISTER_MUTATOR(new_mutator_name, some_variable);
  18 ```
  19
  20
  21 **`MUTATOR_HOOKFUNCTION`**
  22
  23 Creates a function and calls `new_mutator_name` (from `REGISTER_MUTATOR`) and one of `#define MUTATOR()` (from `qcsrc/server/mutators/events.qh` main hooks).
  24
  25 Example:
  26
  27     MUTATOR_HOOKFUNCTION(helloworld, PlayerSpawn)
  28     {
  29         // whatever does
  30     }
  31
  32
  33 **`MUTATOR_CALLHOOK`**
  34
  35 Calls some `MUTATOR_HOOKFUNCTION`.
  36 ```
  37 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hooks);
  38 ```
  39
  40 There are different versions and depends how many variables need to be called in a `MUTATOR_HOOKFUNCTION`:
  41
  42 1 `MUTATOR_HOOKFUNCTION` and 1 variable:
  43
  44 ```
  45 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hooks, some_variable);
  46 ```
  47
  48 1 `MUTATOR_HOOKFUNCTION` and 2 variables:
  49
  50 ```
  51 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hooks, some_variable, some_variable);
  52 ```
  53
  54 1 `MUTATOR_HOOKFUNCTION` and 3 variables:
  55
  56 ```
  57 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hooks, some_variable, some_variable, some_variable);
  58 ```
  59
  60 1 `MUTATOR_HOOKFUNCTION` and multiple variables:
  61
  62 ```
  63 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hooks, some_variable, some_variable, some_variable, some_variable, ...);
  64 ```
  65
  66 <br />
  67 <br />
  68
  69
  70 ## List of MUTATOR functions
  71
  72 **`MakePlayerObserver`**
  73
  74 Called when a player becomes observer, after shared setup.
  75 ```
  76 #define EV_MakePlayerObserver(i, o) \
  77     /** player */ i(entity, MUTATOR_ARGV_0_entity) \
  78     /**/
  79 MUTATOR_HOOKABLE(MakePlayerObserver, EV_MakePlayerObserver)
  80 ```
  81
  82 **`PutClientInServer`**
  83
  84 Called when client spawns in server. (Not sure described)
  85 ```
  86 #define EV_PutClientInServer(i, o) \
  87         /** client wanting to spawn */ i(entity, MUTATOR_ARGV_0_entity) \
  88     /**/
  89 MUTATOR_HOOKABLE(PutClientInServer, EV_PutClientInServer);
  90 ```
  91
  92 **`ForbidSpawn`**
  93
  94 Returns true to prevent a spectator/observer to spawn as player.
  95 ```
  96  #define EV_ForbidSpawn(i, o) \
  97     /** player */ i(entity, MUTATOR_ARGV_0_entity) \
  98     /**/
  99 MUTATOR_HOOKABLE(ForbidSpawn, EV_ForbidSpawn);
 100 ```
 101
 102 **`AutoJoinOnConnection`**
 103
 104 Returns true if client should be put as player on connection.
 105 ```
 106 #define EV_AutoJoinOnConnection(i, o) \
 107     /** player */ i(entity, MUTATOR_ARGV_0_entity) \
 108     /**/
 109 MUTATOR_HOOKABLE(AutoJoinOnConnection, EV_AutoJoinOnConnection);
 110 ```
 111
 112 **`ForbidRandomStartWeapons`**
 113
 114 Called when player spawns to determine whether to give them random start weapons. Return true to forbid giving them.
 115 ```
 116 #define EV_ForbidRandomStartWeapons(i, o) \
 117         /** player */ i(entity, MUTATOR_ARGV_0_entity) \
 118     /**/
 119 MUTATOR_HOOKABLE(ForbidRandomStartWeapons, EV_ForbidRandomStartWeapons);
 120 ```
 121
 122 **`PlayerSpawn`**
 123
 124 Called when a player spawns as player, after shared setup, before his weapon is chosen (so items may be changed in here)
 125
 126
 127     #define EV_PlayerSpawn(i, o) \
 128         /** player spawning */ i(entity, MUTATOR_ARGV_0_entity) \
 129         /** spot that was used, or NULL */ i(entity, MUTATOR_ARGV_1_entity) \
 130         /**/
 131     MUTATOR_HOOKABLE(PlayerSpawn, EV_PlayerSpawn);
 132
 133
 134 **`PlayerWeaponSelect`**
 135
 136 Called after a player's weapon is chosen so it can be overriden here.
 137 ```
 138 #define EV_PlayerWeaponSelect(i, o) \
 139         /** player spawning */ i(entity, MUTATOR_ARGV_0_entity) \
 140     /**/
 141 MUTATOR_HOOKABLE(PlayerWeaponSelect, EV_PlayerWeaponSelect);
 142 ```
 143
 144 **`reset_map_global`**
 145
 146 Called in reset_map.
 147 ```
 148 #define EV_reset_map_global(i, o) \
 149     /**/
 150 MUTATOR_HOOKABLE(reset_map_global, EV_reset_map_global);
 151 ```
 152
 153 **`reset_map_players`**
 154
 155 Called in reset_map.
 156 ```
 157 #define EV_reset_map_players(i, o) \
 158     /**/
 159 MUTATOR_HOOKABLE(reset_map_players, EV_reset_map_players);
 160 ```
 161
 162 <br />
 163 <br />
 164
 165
 166 **`Damage_Calculate`**
 167
 168 Called to adjust damage and force values which are applied to the player, used for e.g. strength damage/force multiplier, I'm not sure if I should change this around slightly (Naming of the entities, and also how they're done in g_damage).
 169
 170
 171     #define EV_Damage_Calculate(i, o) \
 172         /** inflictor           */ i(entity, MUTATOR_ARGV_0_entity) \
 173         /** attacker            */ i(entity, MUTATOR_ARGV_1_entity) \
 174         /** target              */ i(entity, MUTATOR_ARGV_2_entity) \
 175         /** deathtype           */ i(float,  MUTATOR_ARGV_3_float) \
 176         /** damage          */ i(float,  MUTATOR_ARGV_4_float) \
 177         /** damage              */ o(float,  MUTATOR_ARGV_4_float) \
 178         /** mirrordamage    */ i(float,  MUTATOR_ARGV_5_float) \
 179         /** mirrordamage        */ o(float,  MUTATOR_ARGV_5_float) \
 180         /** force           */ i(vector, MUTATOR_ARGV_6_vector) \
 181         /** force                       */ o(vector, MUTATOR_ARGV_6_vector) \
 182         /**/
 183     MUTATOR_HOOKABLE(Damage_Calculate, EV_Damage_Calculate);
 184
 185 <br />
 186 <br />
 187
 188 AND.... STILL in process