From: LegendaryGuard Date: Tue, 8 Dec 2020 10:46:26 +0000 (+0000) Subject: Fixed some incorrect example, added more MUTATOR functions X-Git-Url: https://git.xonotic.org/?p=xonotic%2Fxonotic.wiki.git;a=commitdiff_plain;h=369528ad3fe5f9f7a44f1543da60f379b0b0ca61 Fixed some incorrect example, added more MUTATOR functions --- diff --git a/Functions-and-other-programming-QuakeC-things-in-Xonotic.md b/Functions-and-other-programming-QuakeC-things-in-Xonotic.md index b4ff20e..cb5b053 100644 --- a/Functions-and-other-programming-QuakeC-things-in-Xonotic.md +++ b/Functions-and-other-programming-QuakeC-things-in-Xonotic.md @@ -10,57 +10,57 @@ How to use MUTATOR functions: **Attention:** to use a hook, first register your mutator using `REGISTER_MUTATOR`, then create your function using `MUTATOR_HOOKFUNCTION`. -**`REGISTER_MUTATOR`** +- **`REGISTER_MUTATOR`** Registers a new `MUTATOR_HOOKFUNCTION`. -``` +```c REGISTER_MUTATOR(new_mutator_name, some_variable); ``` -**`MUTATOR_HOOKFUNCTION`** +- **`MUTATOR_HOOKFUNCTION`** Creates a function and calls `new_mutator_name` (from `REGISTER_MUTATOR`) and one of `#define MUTATOR()` (from `qcsrc/server/mutators/events.qh` main hooks). Example: +```c +MUTATOR_HOOKFUNCTION(new_mutator_name_or_events.qh_main_hook, PlayerSpawn) +{ + // whatever does +} +``` - MUTATOR_HOOKFUNCTION(helloworld, PlayerSpawn) - { - // whatever does - } - - -**`MUTATOR_CALLHOOK`** +- **`MUTATOR_CALLHOOK`** Calls some `MUTATOR_HOOKFUNCTION`. -``` -MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hooks); +```c +MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook); ``` There are different versions and depends how many variables need to be called in a `MUTATOR_HOOKFUNCTION`: 1 `MUTATOR_HOOKFUNCTION` and 1 variable: -``` -MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hooks, some_variable); +```c +MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable); ``` 1 `MUTATOR_HOOKFUNCTION` and 2 variables: -``` -MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hooks, some_variable, some_variable); +```c +MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable, some_variable); ``` 1 `MUTATOR_HOOKFUNCTION` and 3 variables: -``` -MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hooks, some_variable, some_variable, some_variable); +```c +MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable, some_variable, some_variable); ``` 1 `MUTATOR_HOOKFUNCTION` and multiple variables: -``` -MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hooks, some_variable, some_variable, some_variable, some_variable, ...); +```c +MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable, some_variable, some_variable, some_variable, ...); ```
@@ -69,119 +69,265 @@ MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hooks, some_vari ## List of MUTATOR functions -**`MakePlayerObserver`** +- **`MakePlayerObserver`** Called when a player becomes observer, after shared setup. -``` +```c #define EV_MakePlayerObserver(i, o) \ /** player */ i(entity, MUTATOR_ARGV_0_entity) \ /**/ MUTATOR_HOOKABLE(MakePlayerObserver, EV_MakePlayerObserver) ``` -**`PutClientInServer`** +- **`PutClientInServer`** Called when client spawns in server. (Not sure described) -``` +```c #define EV_PutClientInServer(i, o) \ /** client wanting to spawn */ i(entity, MUTATOR_ARGV_0_entity) \ /**/ MUTATOR_HOOKABLE(PutClientInServer, EV_PutClientInServer); ``` -**`ForbidSpawn`** +- **`ForbidSpawn`** Returns true to prevent a spectator/observer to spawn as player. -``` +```c #define EV_ForbidSpawn(i, o) \ /** player */ i(entity, MUTATOR_ARGV_0_entity) \ /**/ MUTATOR_HOOKABLE(ForbidSpawn, EV_ForbidSpawn); ``` -**`AutoJoinOnConnection`** +- **`AutoJoinOnConnection`** Returns true if client should be put as player on connection. -``` +```c #define EV_AutoJoinOnConnection(i, o) \ /** player */ i(entity, MUTATOR_ARGV_0_entity) \ /**/ MUTATOR_HOOKABLE(AutoJoinOnConnection, EV_AutoJoinOnConnection); ``` -**`ForbidRandomStartWeapons`** +- **`ForbidRandomStartWeapons`** Called when player spawns to determine whether to give them random start weapons. Return true to forbid giving them. -``` +```c #define EV_ForbidRandomStartWeapons(i, o) \ /** player */ i(entity, MUTATOR_ARGV_0_entity) \ /**/ MUTATOR_HOOKABLE(ForbidRandomStartWeapons, EV_ForbidRandomStartWeapons); ``` -**`PlayerSpawn`** +- **`PlayerSpawn`** Called when a player spawns as player, after shared setup, before his weapon is chosen (so items may be changed in here) +```c +#define EV_PlayerSpawn(i, o) \ + /** player spawning */ i(entity, MUTATOR_ARGV_0_entity) \ + /** spot that was used, or NULL */ i(entity, MUTATOR_ARGV_1_entity) \ + /**/ +MUTATOR_HOOKABLE(PlayerSpawn, EV_PlayerSpawn); +``` - #define EV_PlayerSpawn(i, o) \ - /** player spawning */ i(entity, MUTATOR_ARGV_0_entity) \ - /** spot that was used, or NULL */ i(entity, MUTATOR_ARGV_1_entity) \ - /**/ - MUTATOR_HOOKABLE(PlayerSpawn, EV_PlayerSpawn); - - -**`PlayerWeaponSelect`** +- **`PlayerWeaponSelect`** Called after a player's weapon is chosen so it can be overriden here. -``` +```c #define EV_PlayerWeaponSelect(i, o) \ /** player spawning */ i(entity, MUTATOR_ARGV_0_entity) \ /**/ MUTATOR_HOOKABLE(PlayerWeaponSelect, EV_PlayerWeaponSelect); ``` -**`reset_map_global`** +- **`reset_map_global`** Called in reset_map. -``` +```c #define EV_reset_map_global(i, o) \ /**/ MUTATOR_HOOKABLE(reset_map_global, EV_reset_map_global); ``` -**`reset_map_players`** +- **`reset_map_players`** Called in reset_map. -``` +```c #define EV_reset_map_players(i, o) \ /**/ MUTATOR_HOOKABLE(reset_map_players, EV_reset_map_players); ``` +- **`ForbidPlayerScore_Clear`** + +Returns 1 if clearing player score shall not be allowed. +```c +#define EV_ForbidPlayerScore_Clear(i, o) \ + /**/ +MUTATOR_HOOKABLE(ForbidPlayerScore_Clear, EV_ForbidPlayerScore_Clear); +``` + +- **`ClientDisconnect`** + +Called when a player disconnects. +```c +#define EV_ClientDisconnect(i, o) \ + /** player */ i(entity, MUTATOR_ARGV_0_entity) \ + /**/ +MUTATOR_HOOKABLE(ClientDisconnect, EV_ClientDisconnect); +``` + +- **`PlayerDies`** + +Called when a player dies to e.g. remove stuff he was carrying. +```c +#define EV_PlayerDies(i, o) \ + /** inflictor */ i(entity, MUTATOR_ARGV_0_entity) \ + /** attacker */ i(entity, MUTATOR_ARGV_1_entity) \ + /** target */ i(entity, MUTATOR_ARGV_2_entity) \ + /** deathtype */ i(float, MUTATOR_ARGV_3_float) \ + /** damage */ i(float, MUTATOR_ARGV_4_float) \ + /** damage */ o(float, MUTATOR_ARGV_4_float) \ + /**/ +MUTATOR_HOOKABLE(PlayerDies, EV_PlayerDies); +``` + +- **`PlayerDied`** + +Called after a player died. +```c +#define EV_PlayerDied(i, o) \ + /** player */ i(entity, MUTATOR_ARGV_0_entity) \ + /**/ +MUTATOR_HOOKABLE(PlayerDied, EV_PlayerDied); +``` + +- **`ClientObituary`** + +Called when showing an obituary for the player. Returns true to show nothing (workarounds may be needed). +```c +#define EV_ClientObituary(i, o) \ + /** inflictor */ i(entity, MUTATOR_ARGV_0_entity) \ + /** attacker */ i(entity, MUTATOR_ARGV_1_entity) \ + /** target */ i(entity, MUTATOR_ARGV_2_entity) \ + /** deathtype */ i(float, MUTATOR_ARGV_3_float) \ + /** wep entity */ i(entity, MUTATOR_ARGV_4_entity) \ + /** anonymous killer*/ o(bool, MUTATOR_ARGV_5_bool) \ + /**/ +MUTATOR_HOOKABLE(ClientObituary, EV_ClientObituary); +``` + +- **`FragCenterMessage`** + +Allows overriding the frag centerprint messages. +```c +#define EV_FragCenterMessage(i, o) \ + /** attacker */ i(entity, MUTATOR_ARGV_0_entity) \ + /** target */ i(entity, MUTATOR_ARGV_1_entity) \ + /** deathtype */ i(float, MUTATOR_ARGV_2_float) \ + /** attacker kcount*/ i(int, MUTATOR_ARGV_3_int) \ + /** targ killcount */ i(int, MUTATOR_ARGV_4_int) \ + /**/ +MUTATOR_HOOKABLE(FragCenterMessage, EV_FragCenterMessage); +``` + +- **`PlayHitsound`** + +Called when a player dies to e.g. remove stuff he was carrying. +```c +#define EV_PlayHitsound(i, o) \ + /** victim */ i(entity, MUTATOR_ARGV_0_entity) \ + /** attacker */ i(entity, MUTATOR_ARGV_1_entity) \ + /**/ +MUTATOR_HOOKABLE(PlayHitsound, EV_PlayHitsound); +``` + +- **`ItemModel`** + +Called when an item model is about to be set, allows custom paths etc. +```c +#define EV_ItemModel(i, o) \ + /** model */ i(string, MUTATOR_ARGV_0_string) \ + /** output */ i(string, MUTATOR_ARGV_1_string) \ + /**/ o(string, MUTATOR_ARGV_1_string) \ + /**/ +MUTATOR_HOOKABLE(ItemModel, EV_ItemModel); +``` + +- **`ItemSound`** + +Called when an item sound is about to be played, allows custom paths etc. +```c +#define EV_ItemSound(i, o) \ + /** sound */ i(string, MUTATOR_ARGV_0_string) \ + /** output */ i(string, MUTATOR_ARGV_1_string) \ + /**/ o(string, MUTATOR_ARGV_1_string) \ + /**/ +MUTATOR_HOOKABLE(ItemSound, EV_ItemSound); +``` + +- **`GiveFragsForKill`** + +Called when someone was fragged by "self", and is expected to change frag_score to adjust scoring for the kill. +```c +#define EV_GiveFragsForKill(i, o) \ + /** attacker */ i(entity, MUTATOR_ARGV_0_entity) \ + /** target */ i(entity, MUTATOR_ARGV_1_entity) \ + /** frag score */ i(float, MUTATOR_ARGV_2_float) \ + /** */ o(float, MUTATOR_ARGV_2_float) \ + /** deathtype */ i(float, MUTATOR_ARGV_3_float) \ + /** wep entity */ i(entity, MUTATOR_ARGV_4_entity) \ + /**/ +MUTATOR_HOOKABLE(GiveFragsForKill, EV_GiveFragsForKill); +``` + +- **`MatchEnd`** + +Called when the match ends. +```c +MUTATOR_HOOKABLE(MatchEnd, EV_NO_ARGS); +``` + +- **`TeamBalance_CheckAllowedTeams`** + +Allows adjusting allowed teams. Return true to use the bitmask value and set non-empty string to use team entity name. Both behaviors can be active at the same time and will stack allowed teams. +```c +#define EV_TeamBalance_CheckAllowedTeams(i, o) \ + /** mask of teams */ i(float, MUTATOR_ARGV_0_float) \ + /**/ o(float, MUTATOR_ARGV_0_float) \ + /** team entity name */ i(string, MUTATOR_ARGV_1_string) \ + /**/ o(string, MUTATOR_ARGV_1_string) \ + /** player checked */ i(entity, MUTATOR_ARGV_2_entity) \ + /**/ +MUTATOR_HOOKABLE(TeamBalance_CheckAllowedTeams, EV_TeamBalance_CheckAllowedTeams); +``` + +

-**`Damage_Calculate`** +- **`Damage_Calculate`** 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). - - #define EV_Damage_Calculate(i, o) \ - /** inflictor */ i(entity, MUTATOR_ARGV_0_entity) \ - /** attacker */ i(entity, MUTATOR_ARGV_1_entity) \ - /** target */ i(entity, MUTATOR_ARGV_2_entity) \ - /** deathtype */ i(float, MUTATOR_ARGV_3_float) \ - /** damage */ i(float, MUTATOR_ARGV_4_float) \ - /** damage */ o(float, MUTATOR_ARGV_4_float) \ - /** mirrordamage */ i(float, MUTATOR_ARGV_5_float) \ - /** mirrordamage */ o(float, MUTATOR_ARGV_5_float) \ - /** force */ i(vector, MUTATOR_ARGV_6_vector) \ - /** force */ o(vector, MUTATOR_ARGV_6_vector) \ - /**/ - MUTATOR_HOOKABLE(Damage_Calculate, EV_Damage_Calculate); - +```c +#define EV_Damage_Calculate(i, o) \ + /** inflictor */ i(entity, MUTATOR_ARGV_0_entity) \ + /** attacker */ i(entity, MUTATOR_ARGV_1_entity) \ + /** target */ i(entity, MUTATOR_ARGV_2_entity) \ + /** deathtype */ i(float, MUTATOR_ARGV_3_float) \ + /** damage */ i(float, MUTATOR_ARGV_4_float) \ + /** damage */ o(float, MUTATOR_ARGV_4_float) \ + /** mirrordamage */ i(float, MUTATOR_ARGV_5_float) \ + /** mirrordamage */ o(float, MUTATOR_ARGV_5_float) \ + /** force */ i(vector, MUTATOR_ARGV_6_vector) \ + /** force */ o(vector, MUTATOR_ARGV_6_vector) \ + /** weapon entity */ i(entity, MUTATOR_ARGV_7_entity) \ + /**/ +MUTATOR_HOOKABLE(Damage_Calculate, EV_Damage_Calculate); +```