1 **Note:** The article is written as developer notes to ease developer tasks and save QuakeC terms here.
3 # CSQC, MENUQC, SVQC and GAMEQC blocks
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).
7 Menu and HUD code are actually separated as they run in 2 distinct programs: ***csprogs.dat*** and ***menu.dat***
9 Server program is ***progs.dat***
11 - Code inside a **`#ifdef CSQC`** block is part of the client code and will be compiled to **csprogs.dat**
13 - Code inside a **`#ifdef MENUQC`** block is part of the menu code and will be compiled to **menu.dat**
15 - Code inside a **`#ifdef SVQC`** block is part of the menu code and will be compiled to **progs.dat**
17 - Also, code inside a **`#ifdef GAMEQC`** block is part of both client (not menu) and server code.
19 ### A bit of explanation about the use of each type of cvars
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).
27 Example: `sv_campcheck` is clearly a server cvar (**sv_*** cvars are server cvars), only can be declared inside a **`#ifdef SVQC`** block.
31 Example: `cl_chatsound` is clearly a client cvar (**cl_*** cvars are client cvars), only can be declared inside a **`#ifdef CSQC`** block.
35 Example: `hud_progressbar_alpha` is a client cvar (**hud_*** cvars belong to client cvars), only can be declared inside a **`#ifdef CSQC`** block.
40 # 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))
42 ### How to use MUTATOR functions:
44 You can look the following link if you're trying/testing your own mutator: [Writing your first mutator](writing-your-first-mutator)
46 **Attention:** to use a hook, first register your mutator using `REGISTER_MUTATOR`, then create your function using `MUTATOR_HOOKFUNCTION`.
49 - **`REGISTER_MUTATOR`**
51 Registers a new `MUTATOR_HOOKFUNCTION`.
53 REGISTER_MUTATOR(new_mutator_name, some_variable);
57 - **`MUTATOR_HOOKFUNCTION`**
59 Creates a function and calls `new_mutator_name` (from `REGISTER_MUTATOR`) and one of `#define MUTATOR()` (from `qcsrc/server/mutators/events.qh` main hooks).
63 MUTATOR_HOOKFUNCTION(new_mutator_name, events.qh_main_hook)
69 - **`MUTATOR_CALLHOOK`**
71 Calls some `MUTATOR_HOOKFUNCTION`.
73 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook);
76 There are different versions and depends how many variables need to be called in a `MUTATOR_HOOKFUNCTION`:
78 1 `MUTATOR_HOOKFUNCTION` and 1 variable:
81 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable);
84 1 `MUTATOR_HOOKFUNCTION` and 2 variables:
87 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable, some_variable);
90 1 `MUTATOR_HOOKFUNCTION` and 3 variables:
93 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable, some_variable, some_variable);
96 1 `MUTATOR_HOOKFUNCTION` and multiple variables:
99 MUTATOR_CALLHOOK(name_of_MUTATOR_HOOKFUNCTION_or_events.qh_main_hook, some_variable, some_variable, some_variable, some_variable, ...);
104 ## List of MUTATOR functions
106 You can look the MUTATOR functions in:
108 - **COMMON:** [`qcsrc/common/mutators/events.qh`](https://timepath.github.io/scratchspace/d4/d95/common_2mutators_2events_8qh.html)
110 - **CLIENT:** [`qcsrc/client/mutators/events.qh`](https://timepath.github.io/scratchspace/d8/d0e/client_2mutators_2events_8qh.html)
112 - **SERVER:** [`qcsrc/server/mutators/events.qh`](https://timepath.github.io/scratchspace/d6/ddd/server_2mutators_2events_8qh.html)
119 ## A bit of introduction
121 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.
123 - **Think** function makes the weapon shot react on what to do.
124 - **Touch** function makes the weapon shot react against some element where touch (like player, monster, vehicle, ...).
125 - **Explode** function makes the weapon explosion react.
126 - **Attack/Whatever** function is where the weapon attack executes, keep in mind that it has the other functions attached to be executed.
128 You can look the example of this weapon code:
129 - [**devastator.qh**](https://timepath.github.io/scratchspace/d9/dfa/devastator_8qh_source.html)
130 - [**devastator.qc**](https://timepath.github.io/scratchspace/d9/d5d/devastator_8qc_source.html)
134 ## List of weapon functions
136 This is a created list of functions to modify/create weapons. There may be incomplete explanations for each function.
138 There are contents taken from [`qcsrc/common/weapons/all.qh`](https://timepath.github.io/scratchspace/d0/ddd/weapons_2all_8qh_source.html)
140 **WARNING:** The contents may content wonky code, and the interactions can change and not do the same what happens here.
144 - [**W_SetupShot_Dir**](https://timepath.github.io/scratchspace/d4/d3f/tracing_8qh.html#aff0ea351757ee6caf83b25d12d18656c)
160 - [**W_SetupProjVelocity_Explicit**](https://timepath.github.io/scratchspace/d7/d31/tracing_8qc.html#a55f8f2b1828413bfb123a5fcb61b9f8e)
163 void W_SetupProjVelocity_Explicit(
175 - [**W_MuzzleFlash**](https://timepath.github.io/scratchspace/d0/ddd/weapons_2all_8qh_source.html)(located in **`qcsrc/common/weapons/all.qh`** line 406)
177 In the moment when player shots the weapon, weapon flashes.
179 **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 needs to be executed, although maybe you need more functions/things in the code inside this).
182 void W_MuzzleFlash(Weapon thiswep, entity actor, .entity weaponentity, vector shotorg, vector shotdir);
185 - [**Weapon selection functions**](https://timepath.github.io/scratchspace/d8/d6b/selection_8qh.html)
186 (located in **`qcsrc/server/weapons/selection.qh`**)
188 - [**Weapon decrease ammo, speed factor, rate factor, reload functions**](https://timepath.github.io/scratchspace/d5/de0/weaponsystem_8qc.html)
189 (located in **`qcsrc/server/weapons/weaponsystem.qh`**)
193 # HUD, Menu and Draw functions
195 You can look the draw functions where HUD is being drawn:
196 - [**Draw functions and macros (`qcsrc/client/draw.qh`)**](https://timepath.github.io/scratchspace/d5/d8d/client_2draw_8qh_source.html)
198 More info inside the code where you can draw/print HUD and menu:
199 - [**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)
205 Keep in mind that to develop a gamemode, you need a map having enabled inside its *name_of_map.mapinfo* file this: `gametype shortcut_of_gamemode`. (example: `gametype tdm` (tdm is Team Deathmatch). After modifying the map file, compress the map contents, save as `.zip` and rename the extension to `.pk3`
207 Making gamemodes doesn't seem easy. There's a little explanation of what does each element.
209 ### Generated files for gamemodes:
211 [`qcsrc/common/gamemodes/gamemode/_mod.inc`](https://timepath.github.io/scratchspace/d9/d67/common_2gamemodes_2__mod_8inc_source.html) generated file where the includes of each gamemode are stored.
213 [`qcsrc/common/gamemodes/gamemode/_mod.qh`](https://timepath.github.io/scratchspace/d7/d0b/common_2gamemodes_2__mod_8qh_source.html) generated file where the includes of each gamemode are stored.
221 `qcsrc/common/gamemodes/gamemode/name_of_gamemode/sv_name_of_gamemode.qc`
223 `qcsrc/common/gamemodes/gamemode/name_of_gamemode/sv_name_of_gamemode.qh`
229 `qcsrc/common/gamemodes/gamemode/name_of_gamemode/cl_name_of_gamemode.qc`
231 `qcsrc/common/gamemodes/gamemode/name_of_gamemode/cl_name_of_gamemode.qh`
237 `qcsrc/common/gamemodes/gamemode/name_of_gamemode/name_of_gamemode.qc`
239 `qcsrc/common/gamemodes/gamemode/name_of_gamemode/name_of_gamemode.qh`
241 `qcsrc/common/gamemodes/gamemode/name_of_gamemode/_mod.inc` generated file where the includes of a gamemode is generated.
243 `qcsrc/common/gamemodes/gamemode/name_of_gamemode/_mod.qh` generated file where the includes of a gamemode is generated.
247 ### Optional things (if necessary):
249 [`qcsrc/common/ent_cs.qc`](https://timepath.github.io/scratchspace/d5/dff/ent__cs_8qc_source.html) (if an `ENTCS_PROP()` is needed for a gamemode)
251 [`qcsrc/common/mutators/mutator/waypoints/all.inc`](https://timepath.github.io/scratchspace/d2/d2b/mutators_2mutator_2waypoints_2all_8inc_source.html) where `REGISTER_WAYPOINT` can interact the situation of waypoints.
255 ### Notifications, applying BADCVAR and displaying gamemode in the menu:
257 [`qcsrc/common/notifications/all.inc`](https://timepath.github.io/scratchspace/d9/d09/notifications_2all_8inc_source.html) where notifications output appears in the scenario.
259 [`qcsrc/common/notifications/all.qh`](https://timepath.github.io/scratchspace/dc/d8f/notifications_2all_8qh_source.html) where `CASE(CPID, NAME_OF_ELEMENT)` is needed for a gamemode.
261 [`qcsrc/menu/xonotic/util.qc`](https://timepath.github.io/scratchspace/df/d9b/menu_2xonotic_2util_8qc_source.html) where gamemodes can appear in the main menu (Multiplayer > Create). `GAMETYPE(MAPINFO_TYPE_NAME_OF_GAMEMODE) \`
263 [`qcsrc/server/world.qc`](https://timepath.github.io/scratchspace/dd/dbe/world_8qc_source.html) where `BADCVAR(g_*)` for each gamemode are stored.
267 ### Configuration files where gamemodes interact:
269 `xonotic-data.pk3dir/gamemodes-server.cfg` where server gamestart hooks, gametype vote hooks, respawn delay/waves/weapon_stay cvars and gamemode game/server cvars connect.
271 `xonotic-data.pk3dir/gamemodes-client.cfg` where client gamestart hooks cvars connect.
273 `xonotic-data.pk3dir/notifications.cfg` where notifications need to be activated in the scenario.
277 ### Menu and HUD icons:
279 `gfx/menu/luma/gametype_nameshortcut.tga`
281 `gfx/menu/luminos/gametype_nameshortcut.tga`
283 `gfx/menu/wickedx/gametype_nameshortcut.tga`
285 `gfx/menu/xaw/gametype_nameshortcut.tga`
287 (Example: `gametype_tdm.tga` is an icon of Team Deathmatch)
293 There are good examples of the commits and repositories of people who developed gamemodes:
295 - [**Lyberta's GunGame gametype commits**](https://gitlab.com/xonotic/xonotic-data.pk3dir/-/merge_requests/482/diffs)
297 Taken from: https://forums.xonotic.org/showthread.php?tid=7314
299 You can look and test the [**Lyberta's GunGame gametype repository**](https://gitlab.com/xonotic/xonotic-data.pk3dir/-/tree/Lyberta/GunGame)
301 - [**How Survival gamemode was developed (first commit)**](https://gitlab.com/xonotic/xonotic-data.pk3dir/-/commit/8f61a40877542ac94baa74c5ed653c77b77bd855)
303 It's recommended use the final product in this [**repository**](https://gitlab.com/xonotic/xonotic-data.pk3dir/-/tree/Mario/survival). Many changes have been influenced.
305 [**SMB modpack repository**](https://github.com/MarioSMB/modpack/tree/master/mod/common/gamemodes/survival) has added Survival gamemode and others.
309 Spawns effect particle in-game.
311 The effects can be used with `Send_Effect(effect, org, vel, howmany)` function to test the effects from [**qcsrc/common/effects/all.inc**](https://timepath.github.io/scratchspace/d9/d95/effects_2all_8inc_source.html)
313 **Send_Effect** function definition is inside: [**qcsrc/common/effects/effect.qh**](https://timepath.github.io/scratchspace/d5/de6/effect_8qh_source.html)
315 For example, you can test the smokes, using `EFFECT_SMOKE_LARGE`:
317 Send_Effect(EFFECT_SMOKE_LARGE, this.origin, '0 0 0', 1);
320 EFFECT list: [**qcsrc/common/effects/all.inc**](https://timepath.github.io/scratchspace/d9/d95/effects_2all_8inc_source.html)