198b7d991b1393b169d7aae7ffd1b2d2d6f99607
[xonotic/xonotic-data.pk3dir.git] / qcsrc / server / mutators / base.qh
1 #define CBC_ORDER_EXCLUSIVE 3
2 #define CBC_ORDER_FIRST 1
3 #define CBC_ORDER_LAST 2
4 #define CBC_ORDER_ANY 4
5
6 float CallbackChain_ReturnValue; // read-only field of the current return value
7
8 entity CallbackChain_New(string name);
9 float CallbackChain_Add(entity cb, float() func, float order);
10 float CallbackChain_Remove(entity cb, float() func);
11 // a callback function is like this:
12 // float mycallback(entity me)
13 // {
14 //   do something
15 //   return r;
16 // }
17 float CallbackChain_Call(entity cb);
18
19 #define MUTATOR_REMOVING 0
20 #define MUTATOR_ADDING 1
21 #define MUTATOR_ROLLING_BACK 2
22 typedef float(float) mutatorfunc_t;
23 float Mutator_Add(mutatorfunc_t func, string name);
24 void Mutator_Remove(mutatorfunc_t func, string name); // calls error() on fail
25
26 #define MUTATOR_ADD(name) Mutator_Add(MUTATOR_##name, #name)
27 #define MUTATOR_REMOVE(name) Mutator_Remove(MUTATOR_##name, #name)
28 #define MUTATOR_DEFINITION(name) float MUTATOR_##name(float mode)
29 #define MUTATOR_DECLARATION(name) float MUTATOR_##name(float mode)
30 #define MUTATOR_HOOKFUNCTION(name) float HOOKFUNCTION_##name()
31 #define MUTATOR_HOOK(cb,func,order) do { if(mode == MUTATOR_ADDING) { if(!HOOK_##cb) HOOK_##cb = CallbackChain_New(#cb); if(!CallbackChain_Add(HOOK_##cb,HOOKFUNCTION_##func,order)) { print("HOOK FAILED: ", #func, "\n"); return 1; } } else if(mode == MUTATOR_REMOVING || mode == MUTATOR_ROLLING_BACK) { if(HOOK_##cb) CallbackChain_Remove(HOOK_##cb,HOOKFUNCTION_##func); } } while(0)
32 #define MUTATOR_ONADD if(mode == MUTATOR_ADDING)
33 #define MUTATOR_ONREMOVE if(mode == MUTATOR_REMOVING)
34 #define MUTATOR_ONROLLBACK_OR_REMOVE if(mode == MUTATOR_REMOVING || mode == MUTATOR_ROLLING_BACK)
35
36 #define MUTATOR_HOOKABLE(cb) entity HOOK_##cb
37 #define MUTATOR_CALLHOOK(cb) CallbackChain_Call(HOOK_##cb)
38
39 #define MUTATOR_RETURNVALUE CallbackChain_ReturnValue
40
41
42
43
44 // register all possible hooks here
45
46 MUTATOR_HOOKABLE(MakePlayerObserver);
47         // called when a player becomes observer, after shared setup
48
49 MUTATOR_HOOKABLE(PutClientInServer);
50         entity self; // client wanting to spawn
51
52 MUTATOR_HOOKABLE(PlayerSpawn);
53         entity spawn_spot; // spot that was used, or world
54         // called when a player spawns as player, after shared setup, before his weapon is chosen (so items may be changed in here)
55
56 MUTATOR_HOOKABLE(reset_map_global);
57         // called in reset_map
58
59 MUTATOR_HOOKABLE(reset_map_players);
60         // called in reset_map
61
62 MUTATOR_HOOKABLE(ForbidPlayerScore_Clear);
63         // returns 1 if clearing player score shall not be allowed
64
65 MUTATOR_HOOKABLE(ClientDisconnect);
66         // called when a player disconnects
67
68 MUTATOR_HOOKABLE(PlayerDies);
69         // called when a player dies to e.g. remove stuff he was carrying.
70         // INPUT:
71                 entity frag_inflictor;
72                 entity frag_attacker;
73                 entity frag_target; // same as self
74                 float frag_deathtype;
75
76 MUTATOR_HOOKABLE(PlayerJump);
77         // called when a player presses the jump key
78         // INPUT, OUTPUT:
79                 float player_multijump;
80                 float player_jumpheight;
81
82 MUTATOR_HOOKABLE(GiveFragsForKill);
83         // called when someone was fragged by "self", and is expected to change frag_score to adjust scoring for the kill
84         // INPUT:
85                 entity frag_attacker; // same as self
86                 entity frag_target;
87         // INPUT, OUTPUT:
88                 float frag_score;
89
90 MUTATOR_HOOKABLE(MatchEnd);
91         // called when the match ends
92
93 MUTATOR_HOOKABLE(GetTeamCount);
94         // should adjust ret_float to contain the team count
95         // INPUT, OUTPUT:
96                 float ret_float;
97
98 MUTATOR_HOOKABLE(SpectateCopy);
99         // copies variables for spectating "other" to "self"
100         // INPUT:
101                 entity other;
102
103 MUTATOR_HOOKABLE(ForbidThrowCurrentWeapon);
104         // returns 1 if throwing the current weapon shall not be allowed
105
106 MUTATOR_HOOKABLE(WeaponRateFactor);
107         // allows changing attack rate
108         // INPUT, OUTPUT:
109                 float weapon_rate;
110
111 MUTATOR_HOOKABLE(SetStartItems);
112         // adjusts {warmup_}start_{items,weapons,ammo_{cells,rockets,nails,shells,fuel}}
113
114 MUTATOR_HOOKABLE(BuildMutatorsString);
115         // appends ":mutatorname" to ret_string for logging
116         // INPUT, OUTPUT:
117                 string ret_string;
118
119 MUTATOR_HOOKABLE(BuildMutatorsPrettyString);
120         // appends ", Mutator name" to ret_string for display
121         // INPUT, OUTPUT:
122                 string ret_string;
123
124 MUTATOR_HOOKABLE(CustomizeWaypoint);
125         // called every frame
126         // customizes the waypoint for spectators
127         // INPUT: self = waypoint, other = player, other.enemy = spectator
128
129 MUTATOR_HOOKABLE(FilterItem);
130         // checks if the current item may be spawned (self.items and self.weapons may be read and written to, as well as the ammo_ fields)
131         // return error to request removal
132
133 MUTATOR_HOOKABLE(TurretSpawn);
134         // return error to request removal
135         // INPUT: self - turret
136
137 MUTATOR_HOOKABLE(OnEntityPreSpawn);
138         // return error to prevent entity spawn, or modify the entity
139
140 MUTATOR_HOOKABLE(PlayerPreThink);
141         // runs in the event loop for players; is called for ALL player entities, also bots, also the dead, or spectators
142
143 MUTATOR_HOOKABLE(GetPressedKeys);
144         // TODO change this into a general PlayerPostThink hook?
145
146 MUTATOR_HOOKABLE(PlayerPhysics);
147         // called before any player physics, may adjust variables for movement,
148         // is run AFTER bot code and idle checking
149
150 MUTATOR_HOOKABLE(GetCvars);
151         // is meant to call GetCvars_handle*(get_cvars_s, get_cvars_f, cvarfield, "cvarname") for cvars this mutator needs from the client
152         // INPUT:
153                 float get_cvars_f;
154                 string get_cvars_s;
155
156 MUTATOR_HOOKABLE(EditProjectile);
157         // can edit any "just fired" projectile
158         // INPUT:
159                 entity self;
160                 entity other;
161         
162 MUTATOR_HOOKABLE(MonsterSpawn);
163         // called when a monster spawns
164     
165 MUTATOR_HOOKABLE(MonsterDies);
166         // called when a monster dies
167         // INPUT:
168                 entity frag_attacker;
169                 
170 MUTATOR_HOOKABLE(MonsterRespawn);
171         // called when a monster wants to respawn
172         // INPUT:
173                 entity other;
174                 
175 MUTATOR_HOOKABLE(MonsterDropItem);
176         // called when a monster is dropping loot
177         // INPUT, OUTPUT:
178                 .void() monster_loot;
179                 entity other;
180         
181 MUTATOR_HOOKABLE(MonsterMove);
182         // called when a monster moves
183         // returning TRUE makes the monster stop
184         // INPUT:
185                 float monster_speed_run;
186                 float monster_speed_walk;
187                 entity monster_target;
188     
189 MUTATOR_HOOKABLE(MonsterFindTarget);
190         // called when a monster looks for another target
191     
192 MUTATOR_HOOKABLE(MonsterCheckBossFlag);
193     // called to change a random monster to a miniboss
194
195 MUTATOR_HOOKABLE(AllowMobSpawning);
196         // called when a player tries to spawn a monster
197         // return 1 to prevent spawning
198
199 MUTATOR_HOOKABLE(PlayerDamage_SplitHealthArmor);
200         // called when a player gets damaged to e.g. remove stuff he was carrying.
201         // INPUT:
202                 entity frag_inflictor;
203                 entity frag_attacker;
204                 entity frag_target; // same as self
205                 vector damage_force; // NOTE: this force already HAS been applied
206         // INPUT, OUTPUT:
207                 float damage_take;
208                 float damage_save;
209
210 MUTATOR_HOOKABLE(PlayerDamage_Calculate);
211         // called to adjust damage and force values which are applied to the player, used for e.g. strength damage/force multiplier
212         // i'm not sure if I should change this around slightly (Naming of the entities, and also how they're done in g_damage).
213         // INPUT:
214                 entity frag_attacker;
215                 entity frag_target;
216                 float frag_deathtype;
217         // INPUT, OUTPUT:
218                 float frag_damage;
219                 float frag_mirrordamage;
220                 vector frag_force;
221
222 MUTATOR_HOOKABLE(PlayerPowerups);
223         // called at the end of player_powerups() in cl_client.qc, used for manipulating the values which are set by powerup items.
224         // INPUT
225         entity self;
226         float olditems; // also technically output, but since it is at the end of the function it's useless for that :P
227
228 MUTATOR_HOOKABLE(PlayerRegen);
229         // called every player think frame
230         // return 1 to disable regen
231         // INPUT, OUTPUT:
232                 float regen_mod_max;
233                 float regen_mod_regen;
234                 float regen_mod_rot;
235                 float regen_mod_limit;
236
237 MUTATOR_HOOKABLE(PlayerUseKey);
238         // called when the use key is pressed
239         // if MUTATOR_RETURNVALUE is 1, don't do anything
240         // return 1 if the use key actually did something
241
242 MUTATOR_HOOKABLE(SV_ParseClientCommand);
243         // called when a client command is parsed
244         // NOTE: hooks MUST start with if(MUTATOR_RETURNVALUE) return 0;
245         // NOTE: return 1 if you handled the command, return 0 to continue handling
246         // NOTE: THESE HOOKS MUST NEVER EVER CALL tokenize()
247         // INPUT
248         string cmd_name; // command name
249         float cmd_argc; // also, argv() can be used
250         string cmd_string; // whole command, use only if you really have to
251         /*
252                 // example:
253                 MUTATOR_HOOKFUNCTION(foo_SV_ParseClientCommand)
254                 {
255                         if(MUTATOR_RETURNVALUE) // command was already handled?
256                                 return 0;
257                         if(cmd_name == "echocvar" && cmd_argc >= 2)
258                         {
259                                 print(cvar_string(argv(1)), "\n");
260                                 return 1;
261                         }
262                         if(cmd_name == "echostring" && cmd_argc >= 2)
263                         {
264                                 print(substring(cmd_string, argv_start_index(1), argv_end_index(-1) - argv_start_index(1)), "\n");
265                                 return 1;
266                         }
267                         return 0;
268                 }
269         */
270
271 MUTATOR_HOOKABLE(Spawn_Score);
272         // called when a spawnpoint is being evaluated
273         // return 1 to make the spawnpoint unusable
274         // INPUT
275         entity self; // player wanting to spawn
276         entity spawn_spot; // spot to be evaluated
277         // IN+OUT
278         vector spawn_score; // _x is priority, _y is "distance"
279
280 MUTATOR_HOOKABLE(SV_StartFrame);
281         // runs globally each server frame
282
283 MUTATOR_HOOKABLE(SetModname);
284         // OUT
285         string modname; // name of the mutator/mod if it warrants showing as such in the server browser
286
287 MUTATOR_HOOKABLE(Item_Spawn);
288         // called for each item being spawned on a map, including dropped weapons
289         // return 1 to remove an item
290         // INPUT
291         entity self; // the item
292
293 MUTATOR_HOOKABLE(SetWeaponreplace);
294         // IN
295                 entity self; // map entity
296                 entity other; // weapon info
297         // IN+OUT
298                 string ret_string;
299
300 MUTATOR_HOOKABLE(Item_RespawnCountdown);
301         // called when an item is about to respawn
302         // INPUT+OUTPUT:
303         string item_name;
304         vector item_color;
305
306 MUTATOR_HOOKABLE(BotShouldAttack);
307         // called when a bot checks a target to attack
308         // INPUT
309         entity checkentity;
310
311 MUTATOR_HOOKABLE(PortalTeleport);
312         // called whenever a player goes through a portal gun teleport
313         // allows you to strip a player of an item if they go through the teleporter to help prevent cheating
314         // INPUT
315         entity self;
316
317 MUTATOR_HOOKABLE(HelpMePing);
318         // called whenever a player uses impulse 33 (help me) in cl_impulse.qc
319         // normally help me ping uses self.waypointsprite_attachedforcarrier,
320         // but if your mutator uses something different then you can handle it
321         // in a special manner using this hook
322         // INPUT
323         entity self; // the player who pressed impulse 33
324
325 MUTATOR_HOOKABLE(VehicleSpawn);
326         // called when a vehicle initializes
327         // return TRUE to remove the vehicle
328
329 MUTATOR_HOOKABLE(VehicleEnter);
330         // called when a player enters a vehicle
331         // allows mutators to set special settings in this event
332         // INPUT
333         entity vh_player; // player
334         entity vh_vehicle; // vehicle
335
336 MUTATOR_HOOKABLE(VehicleTouch);
337         // called when a player touches a vehicle
338         // return TRUE to stop player from entering the vehicle
339         // INPUT
340         entity self; // vehicle
341         entity other; // player
342
343 MUTATOR_HOOKABLE(VehicleExit);
344         // called when a player exits a vehicle
345         // allows mutators to set special settings in this event
346         // INPUT
347         entity vh_player; // player
348         entity vh_vehicle; // vehicle
349
350 MUTATOR_HOOKABLE(AbortSpeedrun);
351         // called when a speedrun is aborted and the player is teleported back to start position
352         // INPUT
353         entity self; // player
354
355 MUTATOR_HOOKABLE(ItemTouch);
356         // called at when a item is touched. Called early, can edit item properties.
357         entity self;    // item
358         entity other;   // player
359         #define MUT_ITEMTOUCH_CONTINUE 0 // return this flag to make the function continue as normal
360         #define MUT_ITEMTOUCH_RETURN 1 // return this flag to make the function return (handled entirely by mutator)
361         #define MUT_ITEMTOUCH_PICKUP 2 // return this flag to have the item "picked up" and taken even after mutator handled it
362
363 MUTATOR_HOOKABLE(ClientConnect);
364         // called at when a player connect
365         entity self;    // player
366
367 MUTATOR_HOOKABLE(HavocBot_ChooseRule);
368         entity self;
369
370 MUTATOR_HOOKABLE(AccuracyTargetValid);
371         // called when a target is checked for accuracy
372         entity frag_attacker; // attacker
373         entity frag_target; // target
374         #define MUT_ACCADD_VALID 0 // return this flag to make the function continue if target is a client
375         #define MUT_ACCADD_INVALID 1 // return this flag to make the function always continue
376         #define MUT_ACCADD_INDIFFERENT 2 // return this flag to make the function always return