Add more CHECKGLERROR calls, and clean up a few obsolete code scraps.
[xonotic/darkplaces.git] / dpdefs / dpextensions.qc
1
2 //DarkPlaces supported extension list, draft version 1.04
3
4 //definitions that id Software left out:
5 //these are passed as the 'nomonsters' parameter to traceline/tracebox (yes really this was supported in all quake engines, nomonsters is misnamed)
6 float MOVE_NORMAL = 0; // same as FALSE
7 float MOVE_NOMONSTERS = 1; // same as TRUE
8 float MOVE_MISSILE = 2; // save as movement with .movetype == MOVETYPE_FLYMISSILE
9
10 //checkextension function
11 //idea: expected by almost everyone
12 //darkplaces implementation: LordHavoc
13 float(string s) checkextension = #99;
14 //description:
15 //check if (cvar("pr_checkextension")) before calling this, this is the only
16 //guaranteed extension to be present in the extension system, it allows you
17 //to check if an extension is available, by name, to check for an extension
18 //use code like this:
19 //// (it is recommended this code be placed in worldspawn or a worldspawn called function somewhere)
20 //if (cvar("pr_checkextension"))
21 //if (checkextension("DP_SV_SETCOLOR"))
22 //      ext_setcolor = TRUE;
23 //from then on you can check ext_setcolor to know if that extension is available
24
25 //BX_WAL_SUPPORT
26 //idea: id Software
27 //darkplaces implementation: LordHavoc
28 //description:
29 //indicates the engine supports .wal textures for filenames in the textures/ directory
30 //(note: DarkPlaces has supported this since 2001 or 2002, but did not advertise it as an extension, then I noticed Betwix was advertising it and added the extension accordingly)
31
32 //DP_BUTTONCHAT
33 //idea: Vermeulen
34 //darkplaces implementation: LordHavoc
35 //field definitions:
36 .float buttonchat;
37 //description:
38 //true if the player is currently chatting (in messagemode, menus or console)
39
40 //DP_BUTTONUSE
41 //idea: id Software
42 //darkplaces implementation: LordHavoc
43 //field definitions:
44 .float buttonuse;
45 //client console commands:
46 //+use
47 //-use
48 //description:
49 //made +use and -use commands work, they now control the .buttonuse field (.button1 was used by many mods for other purposes).
50
51 //DP_CL_LOADSKY
52 //idea: Nehahra, LordHavoc
53 //darkplaces implementation: LordHavoc
54 //client console commands:
55 //"loadsky" (parameters: "basename", example: "mtnsun_" would load "mtnsun_up.tga" and "mtnsun_rt.tga" and similar names, use "" to revert to quake sky, note: this is the same as Quake2 skybox naming)
56 //description:
57 //sets global skybox for the map for this client (can be stuffed to a client by QC), does not hurt much to repeatedly execute this command, please don't use this in mods if it can be avoided (only if changing skybox is REALLY needed, otherwise please use DP_GFX_SKYBOX).
58
59 //DP_CON_SET
60 //idea: id Software
61 //darkplaces implementation: LordHavoc
62 //description:
63 //indicates this engine supports the "set" console command which creates or sets a non-archived cvar (not saved to config.cfg on exit), it is recommended that set and seta commands be placed in default.cfg for mod-specific cvars.
64
65 //DP_CON_SETA
66 //idea: id Software
67 //darkplaces implementation: LordHavoc
68 //description:
69 //indicates this engine supports the "seta" console command which creates or sets an archived cvar (saved to config.cfg on exit), it is recommended that set and seta commands be placed in default.cfg for mod-specific cvars.
70
71 //DP_CON_ALIASPARAMETERS
72 //idea: many
73 //darkplaces implementation: Black
74 //description:
75 //indicates this engine supports aliases containing $1 through $9 parameter macros (which when called will expand to the parameters passed to the alias, for example alias test "say $2 $1", then you can type test hi there and it will execute say there hi), as well as $0 (name of the alias) and $* (all parameters $1 onward).
76
77 //DP_CON_EXPANDCVAR
78 //idea: many, PHP
79 //darkplaces implementation: Black
80 //description:
81 //indicates this engine supports console commandlines containing $cvarname which will expand to the contents of that cvar as a parameter, for instance say my fov is $fov, will say "my fov is 90", or similar.
82
83 //DP_CON_STARTMAP
84 //idea: LordHavoc
85 //darkplaces implementation: LordHavoc
86 //description:
87 //adds two engine-called aliases named startmap_sp and startmap_dm which are called when the engine tries to start a singleplayer game from the menu (startmap_sp) or the -listen or -dedicated options are used or the engine is a dedicated server (uses startmap_dm), these allow a mod or game to specify their own map instead of start, and also distinguish between singleplayer and -listen/-dedicated, also these need not be a simple "map start" command, they can do other things if desired, startmap_sp and startmap_dm both default to "map start".
88
89 //DP_EF_ADDITIVE
90 //idea: LordHavoc
91 //darkplaces implementation: LordHavoc
92 //effects bit:
93 float   EF_ADDITIVE     = 32;
94 //description:
95 //additive blending when this object is rendered
96
97 //DP_EF_BLUE
98 //idea: id Software
99 //darkplaces implementation: LordHavoc
100 //effects bit:
101 float   EF_BLUE         = 64;
102 //description:
103 //entity emits blue light (used for quad)
104
105 //DP_EF_DOUBLESIDED
106 //idea: LordHavoc
107 //darkplaces implementation: [515] and LordHavoc
108 //effects bit:
109 float EF_DOUBLESIDED = 32768;
110 //description:
111 //render entity as double sided (backfaces are visible, I.E. you see the 'interior' of the model, rather than just the front), can be occasionally useful on transparent stuff.
112
113 //DP_EF_DYNAMICMODELLIGHT
114 //idea: C.Brutail, divVerent, maikmerten
115 //darkplaces implementation: divVerent
116 //effects bit:
117 float   EF_DYNAMICMODELLIGHT     = 131072;
118 //description:
119 //force dynamic model light on the entity, even if it's a BSP model (or anything else with lightmaps or light colors)
120
121 //DP_EF_FLAME
122 //idea: LordHavoc
123 //darkplaces implementation: LordHavoc
124 //effects bit:
125 float   EF_FLAME        = 1024;
126 //description:
127 //entity is on fire
128
129 //DP_EF_FULLBRIGHT
130 //idea: LordHavoc
131 //darkplaces implementation: LordHavoc
132 //effects bit:
133 float   EF_FULLBRIGHT   = 512;
134 //description:
135 //entity is always brightly lit
136
137 //DP_EF_NODEPTHTEST
138 //idea: Supa
139 //darkplaces implementation: LordHavoc
140 //effects bit:
141 float   EF_NODEPTHTEST       = 8192;
142 //description:
143 //makes entity show up to client even through walls, useful with EF_ADDITIVE for special indicators like where team bases are in a map, so that people don't get lost
144
145 //DP_EF_NODRAW
146 //idea: id Software
147 //darkplaces implementation: LordHavoc
148 //effects bit:
149 float   EF_NODRAW       = 16;
150 //description:
151 //prevents server from sending entity to client (forced invisible, even if it would have been a light source or other such things)
152
153 //DP_EF_NOGUNBOB
154 //idea: Chris Page, Dresk
155 //darkplaces implementation: LordHAvoc
156 //effects bit:
157 float   EF_NOGUNBOB     = 256;
158 //description:
159 //this has different meanings depending on the entity it is used on:
160 //player entity - prevents gun bobbing on player.viewmodel
161 //viewmodelforclient entity - prevents gun bobbing on an entity attached to the player's view
162 //other entities - no effect
163 //uses:
164 //disabling gun bobbing on a diving mask or other model used as a .viewmodel.
165 //disabling gun bobbing on view-relative models meant to be part of the heads up display.  (note: if fov is changed these entities may be off-screen, or too near the center of the screen, so use fov 90 in this case)
166
167 //DP_EF_NOSHADOW
168 //idea: LordHavoc
169 //darkplaces implementation: LordHavoc
170 //effects bit:
171 float   EF_NOSHADOW     = 4096;
172 //description:
173 //realtime lights will not cast shadows from this entity (but can still illuminate it)
174
175 //DP_EF_RED
176 //idea: id Software
177 //darkplaces implementation: LordHavoc
178 //effects bit:
179 float   EF_RED          = 128;
180 //description:
181 //entity emits red light (used for invulnerability)
182
183 //DP_EF_RESTARTANIM_BIT
184 //idea: id software
185 //darkplaces implementation: divVerent
186 //effects bit:
187 float   EF_RESTARTANIM_BIT = 1048576;
188 //description:
189 //when toggled, the current animation is restarted. Useful for weapon animation.
190 //to toggle this bit in QC, you can do:
191 //  self.effects += (EF_RESTARTANIM_BIT - 2 * (self.effects & EF_RESTARTANIM_BIT));
192
193 //DP_EF_STARDUST
194 //idea: MythWorks Inc
195 //darkplaces implementation: LordHavoc
196 //effects bit:
197 float   EF_STARDUST     = 2048;
198 //description:
199 //entity emits bouncing sparkles in every direction
200
201 //DP_EF_TELEPORT_BIT
202 //idea: id software
203 //darkplaces implementation: divVerent
204 //effects bit:
205 float   EF_TELEPORT_BIT = 2097152;
206 //description:
207 //when toggled, interpolation of the entity is skipped for one frame. Useful for teleporting.
208 //to toggle this bit in QC, you can do:
209 //  self.effects += (EF_TELEPORT_BIT - 2 * (self.effects & EF_TELEPORT_BIT));
210
211 //DP_ENT_ALPHA
212 //idea: Nehahra
213 //darkplaces implementation: LordHavoc
214 //fields:
215 .float alpha;
216 //description:
217 //controls opacity of the entity, 0.0 is forced to be 1.0 (otherwise everything would be invisible), use -1 if you want to make something invisible, 1.0 is solid (like normal).
218
219 //DP_ENT_COLORMOD
220 //idea: LordHavoc
221 //darkplaces implementation: LordHavoc
222 //field definition:
223 .vector colormod;
224 //description:
225 //controls color of the entity, '0 0 0', is forced to be '1 1 1' (otherwise everything would be black), used for tinting objects, for instance using '1 0.6 0.4' on an ogre would give you an orange ogre (order is red green blue), note the colors can go up to '8 8 8' (8x as bright as normal).
226
227 //DP_ENT_CUSTOMCOLORMAP
228 //idea: LordHavoc
229 //darkplaces implementation: LordHavoc
230 //description:
231 //if .colormap is set to 1024 + pants + shirt * 16, those colors will be used for colormapping the entity, rather than looking up a colormap by player number.
232
233 /*
234 //NOTE: no longer supported by darkplaces because all entities are delta compressed now
235 //DP_ENT_DELTACOMPRESS // no longer supported
236 //idea: LordHavoc
237 //darkplaces implementation: LordHavoc
238 //effects bit:
239 float EF_DELTA = 8388608;
240 //description:
241 //(obsolete) applies delta compression to the network updates of the entity, making updates smaller, this might cause some unreliable behavior in packet loss situations, so it should only be used on numerous (nails/plasma shots/etc) or unimportant objects (gibs/shell casings/bullet holes/etc).
242 */
243
244 //DP_ENT_EXTERIORMODELTOCLIENT
245 //idea: LordHavoc
246 //darkplaces implementation: LordHavoc
247 //fields:
248 .entity exteriormodeltoclient;
249 //description:
250 //the entity is visible to all clients with one exception: if the specified client is using first person view (not using chase_active) the entity will not be shown.  Also if tag attachments are supported any entities attached to the player entity will not be drawn in first person.
251
252 //DP_ENT_GLOW
253 //idea: LordHavoc
254 //darkplaces implementation: LordHavoc
255 //field definitions:
256 .float glow_color;
257 .float glow_size;
258 .float glow_trail;
259 //description:
260 //customizable glowing light effect on the entity, glow_color is a paletted (8bit) color in the range 0-255 (note: 0 and 254 are white), glow_size is 0 or higher (up to the engine what limit to cap it to, darkplaces imposes a 1020 limit), if glow_trail is true it will leave a trail of particles of the same color as the light.
261
262 //DP_ENT_GLOWMOD
263 //idea: LordHavoc
264 //darkplaces implementation: LordHavoc
265 //field definition:
266 .vector glowmod;
267 //description:
268 //controls color of the entity's glow texture (fullbrights), '0 0 0', is forced to be '1 1 1' (otherwise everything would be black), used for tinting objects, see colormod (same color restrictions apply).
269
270 //DP_ENT_LOWPRECISION
271 //idea: LordHavoc
272 //darkplaces implementation: LordHavoc
273 //effects bit:
274 float EF_LOWPRECISION = 4194304;
275 //description:
276 //uses low quality origin coordinates, reducing network traffic compared to the default high precision, intended for numerous objects (projectiles/gibs/bullet holes/etc).
277
278 //DP_ENT_SCALE
279 //idea: LordHavoc
280 //darkplaces implementation: LordHavoc
281 //field definitions:
282 .float scale;
283 //description:
284 //controls rendering scale of the object, 0 is forced to be 1, darkplaces uses 1/16th accuracy and a limit of 15.9375, can be used to make an object larger or smaller.
285
286 //DP_ENT_TRAILEFFECTNUM
287 //idea: LordHavoc
288 //darkplaces implementation: LordHavoc
289 //field definitions:
290 .float traileffectnum;
291 //description:
292 //use a custom effectinfo.txt effect on this entity, assign it like this:
293 //self.traileffectnum = particleeffectnum("mycustomeffect");
294 //this will do both the dlight and particle trail as described in the effect, basically equivalent to trailparticles() in CSQC but performed on a server entity.
295
296 //DP_ENT_VIEWMODEL
297 //idea: LordHavoc
298 //darkplaces implementation: LordHavoc
299 //field definitions:
300 .entity viewmodelforclient;
301 //description:
302 //this is a very special capability, attachs the entity to the view of the client specified, origin and angles become relative to the view of that client, all effects can be used (multiple skins on a weapon model etc)...  the entity is not visible to any other client.
303
304 //DP_GFX_EXTERNALTEXTURES
305 //idea: LordHavoc
306 //darkplaces implementation: LordHavoc
307 //description:
308 //loads external textures found in various directories (tenebrae compatible)...
309 /*
310 in all examples .tga is merely the base texture, it can be any of these:
311 .tga (base texture)
312 _glow.tga (fullbrights or other glowing overlay stuff, NOTE: this is done using additive blend, not alpha)
313 _pants.tga (pants overlay for colormapping on models, this should be shades of grey (it is tinted by pants color) and black wherever the base texture is not black, as this is an additive blend)
314 _shirt.tga (same idea as pants, but for shirt color)
315 _diffuse.tga (this may be used instead of base texture for per pixel lighting)
316 _gloss.tga (specular texture for per pixel lighting, note this can be in color (tenebrae only supports greyscale))
317 _norm.tga (normalmap texture for per pixel lighting)
318 _bump.tga (bumpmap, converted to normalmap at load time, supported only for reasons of tenebrae compatibility)
319 _luma.tga (same as _glow but supported only for reasons of tenebrae compatibility)
320
321 due to glquake's incomplete Targa(r) loader, this section describes
322 required Targa(r) features support:
323 types:
324 type 1 (uncompressed 8bit paletted with 24bit/32bit palette)
325 type 2 (uncompressed 24bit/32bit true color, glquake supported this)
326 type 3 (uncompressed 8bit greyscale)
327 type 9 (RLE compressed 8bit paletted with 24bit/32bit palette)
328 type 10 (RLE compressed 24bit/32bit true color, glquake supported this)
329 type 11 (RLE compressed 8bit greyscale)
330 attribute bit 0x20 (Origin At Top Left, top to bottom, left to right)
331
332 image formats guaranteed to be supported: tga, pcx, lmp
333 image formats that are optional: png, jpg
334
335 mdl/spr/spr32 examples:
336 skins are named _A (A being a number) and skingroups are named like _A_B
337 these act as suffixes on the model name...
338 example names for skin _2_1 of model "progs/armor.mdl":
339 game/override/progs/armor.mdl_2_1.tga
340 game/textures/progs/armor.mdl_2_1.tga
341 game/progs/armor.mdl_2_1.tga
342 example names for skin _0 of the model "progs/armor.mdl":
343 game/override/progs/armor.mdl_0.tga
344 game/textures/progs/armor.mdl_0.tga
345 game/progs/armor.mdl_0.tga
346 note that there can be more skins files (of the _0 naming) than the mdl
347 contains, this is only useful to save space in the .mdl file if classic quake
348 compatibility is not a concern.
349
350 bsp/md2/md3 examples:
351 example names for the texture "quake" of model "maps/start.bsp":
352 game/override/quake.tga
353 game/textures/quake.tga
354 game/quake.tga
355
356 sbar/menu/console textures: for example the texture "conchars" (console font) in gfx.wad
357 game/override/gfx/conchars.tga
358 game/textures/gfx/conchars.tga
359 game/gfx/conchars.tga
360 */
361
362 //DP_GFX_EXTERNALTEXTURES_PERMAPTEXTURES
363 //idea: Fuh?
364 //darkplaces implementation: LordHavoc
365 //description:
366 //Q1BSP and HLBSP map loading loads external textures found in textures/<mapname>/ as well as textures/.
367 //Where mapname is the bsp filename minus the extension (typically .bsp) and minus maps/ if it is in maps/ (any other path is not removed)
368 //example:
369 //maps/e1m1.bsp uses textures in the directory textures/e1m1/ and falls back to textures/
370 //maps/b_batt0.bsp uses textures in the directory textures/b_batt0.bsp and falls back to textures/
371 //as a more extreme example:
372 //progs/something/blah.bsp uses textures in the directory textures/progs/something/blah/ and falls back to textures/
373
374 //DP_GFX_FOG
375 //idea: LordHavoc
376 //darkplaces implementation: LordHavoc
377 //worldspawn fields:
378 //"fog" (parameters: "density red green blue", example: "0.1 0.3 0.3 0.3")
379 //description:
380 //global fog for the map, can not be changed by QC
381
382 //DP_GFX_QUAKE3MODELTAGS
383 //idea: id Software
384 //darkplaces implementation: LordHavoc
385 //field definitions:
386 .entity tag_entity; // entity this is attached to (call setattachment to set this)
387 .float tag_index; // which tag on that entity (0 is relative to the entity, > 0 is an index into the tags on the model if it has any) (call setattachment to set this)
388 //builtin definitions:
389 void(entity e, entity tagentity, string tagname) setattachment = #443; // attachs e to a tag on tagentity (note: use "" to attach to entity origin/angles instead of a tag)
390 //description:
391 //allows entities to be visually attached to model tags (which follow animations perfectly) on other entities, for example attaching a weapon to a player's hand, or upper body attached to lower body, allowing it to change angles and frame separately (note: origin and angles are relative to the tag, use '0 0 0' for both if you want it to follow exactly, this is similar to viewmodelforclient's behavior).
392 //note 2: if the tag is not found, it defaults to "" (attach to origin/angles of entity)
393 //note 3: attaching to world turns off attachment
394 //note 4: the entity that this is attached to must be visible for this to work
395 //note 5: if an entity is attached to the player entity it will not be drawn in first person.
396
397 //DP_GFX_SKINFILES
398 //idea: LordHavoc
399 //darkplaces implementation: LordHavoc
400 //description:
401 //alias models (mdl, md2, md3) can have .skin files to replace conventional texture naming, these have a naming format such as:
402 //progs/test.md3_0.skin
403 //progs/test.md3_1.skin
404 //...
405 //
406 //these files contain replace commands (replace meshname shadername), example:
407 //replace "helmet" "progs/test/helmet1.tga" // this is a mesh shader replacement
408 //replace "teamstripes" "progs/test/redstripes.tga"
409 //replace "visor" "common/nodraw" // this makes the visor mesh invisible
410 ////it is not possible to rename tags using this format
411 //
412 //Or the Quake3 syntax (100% compatible with Quake3's .skin files):
413 //helmet,progs/test/helmet1.tga // this is a mesh shader replacement
414 //teamstripes,progs/test/redstripes.tga
415 //visor,common/nodraw // this makes the visor mesh invisible
416 //tag_camera, // this defines that the first tag in the model is called tag_camera
417 //tag_test, // this defines that the second tag in the model is called tag_test
418 //
419 //any names that are not replaced are automatically show up as a grey checkerboard to indicate the error status, and "common/nodraw" is a special case that is invisible.
420 //this feature is intended to allow multiple skin sets on md3 models (which otherwise only have one skin set).
421 //other commands might be added someday but it is not expected.
422
423 //DP_GFX_SKYBOX
424 //idea: LordHavoc
425 //darkplaces implementation: LordHavoc
426 //worldspawn fields:
427 //"sky" (parameters: "basename", example: "mtnsun_" would load "mtnsun_up.tga" and "mtnsun_rt.tga" and similar names, note: "sky" is also used the same way by Quake2)
428 //description:
429 //global skybox for the map, can not be changed by QC
430
431 //DP_UTF8
432 //idea: Blub\0, divVerent
433 //darkplaces implementation: Blub\0
434 //cvar definitions:
435 //   utf8_enable: enable utf8 encoding
436 //description: utf8 characters are allowed inside cvars, protocol strings, files, progs strings, etc., 
437 //and count as 1 char for string functions like strlen, substring, etc.
438 // note: utf8_enable is run-time cvar, could be changed during execution
439 // note: beware that str2chr() could return value bigger than 255 once utf8 is enabled
440
441 //DP_HALFLIFE_MAP
442 //idea: LordHavoc
443 //darkplaces implementation: LordHavoc
444 //description:
445 //simply indicates that the engine supports HalfLife maps (BSP version 30, NOT the QER RGBA ones which are also version 30).
446
447 //DP_HALFLIFE_MAP_CVAR
448 //idea: LordHavoc
449 //darkplaces implementation: LordHavoc
450 //cvars:
451 //halflifebsp 0/1
452 //description:
453 //engine sets this cvar when loading a map to indicate if it is halflife format or not.
454
455 //DP_HALFLIFE_SPRITE
456 //idea: LordHavoc
457 //darkplaces implementation: LordHavoc
458 //description:
459 //simply indicates that the engine supports HalfLife sprites.
460
461 //DP_INPUTBUTTONS
462 //idea: LordHavoc
463 //darkplaces implementation: LordHavoc
464 //field definitions:
465 .float button3;
466 .float button4;
467 .float button5;
468 .float button6;
469 .float button7;
470 .float button8;
471 .float button9;
472 .float button10;
473 .float button11;
474 .float button12;
475 .float button13;
476 .float button14;
477 .float button15;
478 .float button16;
479 //description:
480 //set to the state of the +button3, +button4, +button5, +button6, +button7, and +button8 buttons from the client, this does not involve protocol changes (the extra 6 button bits were simply not used).
481 //the exact mapping of protocol button bits on the server is:
482 //self.button0 = (bits & 1) != 0;
483 ///* button1 is skipped because mods abuse it as a variable, and accordingly it has no bit */
484 //self.button2 = (bits & 2) != 0;
485 //self.button3 = (bits & 4) != 0;
486 //self.button4 = (bits & 8) != 0;
487 //self.button5 = (bits & 16) != 0;
488 //self.button6 = (bits & 32) != 0;
489 //self.button7 = (bits & 64) != 0;
490 //self.button8 = (bits & 128) != 0;
491
492 // DP_LIGHTSTYLE_STATICVALUE
493 // idea: VorteX
494 // darkplaces implementation: VorteX
495 // description: allows alternative 'static' lightstyle syntax : "=value"
496 // examples: "=0.5", "=2.0", "=2.75"
497 // could be used to control switchable lights or making styled lights with brightness > 2
498 // Warning: this extension is experimental. It safely works in CSQC, but SVQC use is limited by the fact 
499 // that other engines (which do not support this extension) could connect to a game and misunderstand this kind of lightstyle syntax
500
501 //DP_LITSPRITES
502 //idea: LordHavoc
503 //darkplaces implementation: LordHavoc
504 //description:
505 //indicates this engine supports lighting on sprites, any sprite with ! in its filename (both on disk and in the qc) will be lit rather than having forced EF_FULLBRIGHT (EF_FULLBRIGHT on the entity can still force these sprites to not be lit).
506
507 //DP_LITSUPPORT
508 //idea: LordHavoc
509 //darkplaces implementation: LordHavoc
510 //description:
511 //indicates this engine loads .lit files for any quake1 format .bsp files it loads to enhance maps with colored lighting.
512 //implementation description: these files begin with the header QLIT followed by version number 1 (as little endian 32bit), the rest of the file is a replacement lightmaps lump, except being 3x as large as the lightmaps lump of the map it matches up with (and yes the between-lightmap padding is expanded 3x to keep this consistent), so the lightmap offset in each surface is simply multiplied by 3 during loading to properly index the lit data, and the lit file is loaded instead of the lightmap lump, other renderer changes are needed to display these of course...  see the litsupport.zip sample code (almost a tutorial) at http://icculus.org/twilight/darkplaces for more information.
513
514 //DP_MONSTERWALK
515 //idea: LordHavoc
516 //darkplaces implementation: LordHavoc
517 //description:
518 //MOVETYPE_WALK is permitted on non-clients, so bots can move smoothly, run off ledges, etc, just like a real player.
519
520 //DP_MOVETYPEBOUNCEMISSILE
521 //idea: id Software
522 //darkplaces implementation: id Software
523 //movetype definitions:
524 //float MOVETYPE_BOUNCEMISSILE = 11; // already in defs.qc
525 //description:
526 //MOVETYPE_BOUNCE but without gravity, and with full reflection (no speed loss like grenades have), in other words - bouncing laser bolts.
527
528 //DP_MOVETYPEFLYWORLDONLY
529 //idea: Samual
530 //darkplaces implementation: Samual
531 //movetype definitions:
532 float MOVETYPE_FLY_WORLDONLY = 33;
533 //description:
534 //like MOVETYPE_FLY, but does all traces with MOVE_WORLDONLY, and is ignored by MOVETYPE_PUSH. Should only be combined with SOLID_NOT and SOLID_TRIGGER.
535
536 //DP_NULL_MODEL
537 //idea: Chris
538 //darkplaces implementation: divVerent
539 //definitions:
540 //string dp_null_model = "null";
541 //description:
542 //setmodel(e, "null"); makes an entity invisible, have a zero bbox, but
543 //networked. useful for shared CSQC entities.
544
545 //DP_MOVETYPEFOLLOW
546 //idea: id Software, LordHavoc (redesigned)
547 //darkplaces implementation: LordHavoc
548 //movetype definitions:
549 float MOVETYPE_FOLLOW = 12;
550 //description:
551 //MOVETYPE_FOLLOW implemented, this uses existing entity fields in unusual ways:
552 //aiment - the entity this is attached to.
553 //punchangle - the original angles when the follow began.
554 //view_ofs - the relative origin (note that this is un-rotated by punchangle, and that is actually the only purpose of punchangle).
555 //v_angle - the relative angles.
556 //here's an example of how you would set a bullet hole sprite to follow a bmodel it was created on, even if the bmodel rotates:
557 //hole.movetype = MOVETYPE_FOLLOW; // make the hole follow
558 //hole.solid = SOLID_NOT; // MOVETYPE_FOLLOW is always non-solid
559 //hole.aiment = bmodel; // make the hole follow bmodel
560 //hole.punchangle = bmodel.angles; // the original angles of bmodel
561 //hole.view_ofs = hole.origin - bmodel.origin; // relative origin
562 //hole.v_angle = hole.angles - bmodel.angles; // relative angles
563
564 //DP_QC_ASINACOSATANATAN2TAN
565 //idea: Urre
566 //darkplaces implementation: LordHavoc
567 //constant definitions:
568 float DEG2RAD = 0.0174532925199432957692369076848861271344287188854172545609719144;
569 float RAD2DEG = 57.2957795130823208767981548141051703324054724665643215491602438612;
570 float PI      = 3.1415926535897932384626433832795028841971693993751058209749445923;
571 //builtin definitions:
572 float(float s) asin = #471; // returns angle in radians for a given sin() value, the result is in the range -PI*0.5 to PI*0.5
573 float(float c) acos = #472; // returns angle in radians for a given cos() value, the result is in the range 0 to PI
574 float(float t) atan = #473; // returns angle in radians for a given tan() value, the result is in the range -PI*0.5 to PI*0.5
575 float(float c, float s) atan2 = #474; // returns angle in radians for a given cos() and sin() value pair, the result is in the range -PI to PI (this is identical to vectoyaw except it returns radians rather than degrees)
576 float(float a) tan = #475; // returns tangent value (which is simply sin(a)/cos(a)) for the given angle in radians, the result is in the range -infinity to +infinity
577 //description:
578 //useful math functions for analyzing vectors, note that these all use angles in radians (just like the cos/sin functions) not degrees unlike makevectors/vectoyaw/vectoangles, so be sure to do the appropriate conversions (multiply by DEG2RAD or RAD2DEG as needed).
579 //note: atan2 can take unnormalized vectors (just like vectoyaw), and the function was included only for completeness (more often you want vectoyaw or vectoangles), atan2(v_x,v_y) * RAD2DEG gives the same result as vectoyaw(v)
580
581 //DP_QC_AUTOCVARS
582 //idea: divVerent
583 //darkplaces implementation: divVerent
584 //description:
585 //allows QC variables to be bound to cvars
586 //(works for float, string, vector types)
587 //example:
588 // float autocvar_developer;
589 // float autocvar_registered;
590 // string autocvar__cl_name;
591 //NOTE: copying a string-typed autocvar to another variable/field, and then
592 //changing the cvar or returning from progs is UNDEFINED. Writing to autocvar
593 //globals is UNDEFINED. Accessing autocvar globals after changing that cvar in
594 //the same frame by any means other than cvar_set() from the same QC VM is
595 //IMPLEMENTATION DEFINED (an implementation may either yield the previous, or
596 //the current, value). Changing them via cvar_set() in the same QC VM
597 //immediately must reflect on the autocvar globals. Whether autocvar globals,
598 //after restoring a savegame, have the cvar's current value, or the original
599 //value at time of saving, is UNDEFINED. Restoring a savegame however must not
600 //restore the cvar values themselves.
601 //In case the cvar does NOT exist, then it is automatically created with the
602 //value of the autocvar initializer, if given. This is possible with e.g.
603 //frikqcc and fteqcc the following way:
604 // var float autocvar_whatever = 42;
605 //If no initializer is given, the cvar will be initialized to a string
606 //equivalent to the NULL value of the given data type, that is, the empty
607 //string, 0, or '0 0 0'. However, when automatic cvar creation took place, a
608 //warning is printed to the game console.
609 //NOTE: to prevent an ambiguity with float names for vector types, autocvar
610 //names MUST NOT end with _x, _y or _z!
611
612 //DP_QC_CHANGEPITCH
613 //idea: id Software
614 //darkplaces implementation: id Software
615 //field definitions:
616 .float idealpitch;
617 .float pitch_speed;
618 //builtin definitions:
619 void(entity ent) changepitch = #63;
620 //description:
621 //equivalent to changeyaw, ent is normally self. (this was a Q2 builtin)
622
623 //DP_QC_COPYENTITY
624 //idea: LordHavoc
625 //darkplaces implementation: LordHavoc
626 //builtin definitions:
627 void(entity from, entity to) copyentity = #400;
628 //description:
629 //copies all data in the entity to another entity.
630
631 //DP_QC_CRC16
632 //idea: divVerent
633 //darkplaces implementation: divVerent
634 //Some hash function to build hash tables with. This has to be be the CRC-16-CCITT that is also required for the QuakeWorld download protocol.
635 //When caseinsensitive is set, the CRC is calculated of the lower cased string.
636 float(float caseinsensitive, string s, ...) crc16 = #494;
637
638 //DP_QC_CVAR_DEFSTRING
639 //idea: id Software (Doom3), LordHavoc
640 //darkplaces implementation: LordHavoc
641 //builtin definitions:
642 string(string s) cvar_defstring = #482;
643 //description:
644 //returns the default value of a cvar, as a tempstring.
645
646 //DP_QC_CVAR_DESCRIPTION
647 //idea: divVerent
648 //DarkPlaces implementation: divVerent
649 //builtin definitions:
650 string(string name) cvar_description = #518;
651 //description:
652 //returns the description of a cvar
653
654 //DP_QC_CVAR_STRING
655 //idea: VorteX
656 //DarkPlaces implementation: VorteX, LordHavoc
657 //builtin definitions:
658 string(string s) cvar_string = #448;
659 //description:
660 //returns the value of a cvar, as a tempstring.
661
662 //DP_QC_CVAR_TYPE
663 //idea: divVerent
664 //DarkPlaces implementation: divVerent
665 //builtin definitions:
666 float(string name) cvar_type = #495;
667 float CVAR_TYPEFLAG_EXISTS = 1;
668 float CVAR_TYPEFLAG_SAVED = 2;
669 float CVAR_TYPEFLAG_PRIVATE = 4;
670 float CVAR_TYPEFLAG_ENGINE = 8;
671 float CVAR_TYPEFLAG_HASDESCRIPTION = 16;
672 float CVAR_TYPEFLAG_READONLY = 32;
673
674 //DP_QC_DIGEST
675 //idea: motorsep, Spike
676 //DarkPlaces implementation: divVerent
677 //builtin definitions:
678 string(string digest, string data, ...) digest_hex = #639;
679 //description:
680 //returns a given hex digest of given data
681 //the returned digest is always encoded in hexadecimal
682 //only the "MD4" digest is always supported!
683 //if the given digest is not supported, string_null is returned
684 //the digest string is matched case sensitively, use "MD4", not "md4"!
685
686 //DP_QC_DIGEST_SHA256
687 //idea: motorsep, Spike
688 //DarkPlaces implementation: divVerent
689 //description:
690 //"SHA256" is also an allowed digest type
691
692 //DP_QC_EDICT_NUM
693 //idea: 515
694 //DarkPlaces implementation: LordHavoc
695 //builtin definitions:
696 entity(float entnum) edict_num = #459;
697 float(entity ent) wasfreed = #353; // same as in EXT_CSQC extension
698 //description:
699 //edict_num returns the entity corresponding to a given number, this works even for freed entities, but you should call wasfreed(ent) to see if is currently active.
700 //wasfreed returns whether an entity slot is currently free (entities that have never spawned are free, entities that have had remove called on them are also free).
701
702 //DP_QC_ENTITYDATA
703 //idea: KrimZon
704 //darkplaces implementation: KrimZon
705 //builtin definitions:
706 float() numentityfields = #496;
707 string(float fieldnum) entityfieldname = #497;
708 float(float fieldnum) entityfieldtype = #498;
709 string(float fieldnum, entity ent) getentityfieldstring = #499;
710 float(float fieldnum, entity ent, string s) putentityfieldstring = #500;
711 //constants:
712 //Returned by entityfieldtype
713 float FIELD_STRING   = 1;
714 float FIELD_FLOAT    = 2;
715 float FIELD_VECTOR   = 3;
716 float FIELD_ENTITY   = 4;
717 float FIELD_FUNCTION = 6;
718 //description:
719 //Versatile functions intended for storing data from specific entities between level changes, but can be customized for some kind of partial savegame.
720 //WARNING: .entity fields cannot be saved and restored between map loads as they will leave dangling pointers.
721 //numentityfields returns the number of entity fields. NOT offsets. Vectors comprise 4 fields: v, v_x, v_y and v_z.
722 //entityfieldname returns the name as a string, eg. "origin" or "classname" or whatever.
723 //entityfieldtype returns a value that the constants represent, but the field may be of another type in more exotic progs.dat formats or compilers.
724 //getentityfieldstring returns data as would be written to a savegame, eg... "0.05" (float), "0 0 1" (vector), or "Hello World!" (string). Function names can also be returned.
725 //putentityfieldstring puts the data returned by getentityfieldstring back into the entity.
726
727 //DP_QC_ENTITYSTRING
728 void(string s) loadfromdata = #529;
729 void(string s) loadfromfile = #530;
730 void(string s) callfunction = #605;
731 void(float fh, entity e) writetofile = #606;
732 float(string s) isfunction = #607;
733 void(entity e, string s) parseentitydata = #608;
734
735 //DP_QC_ETOS
736 //idea: id Software
737 //darkplaces implementation: id Software
738 //builtin definitions:
739 string(entity ent) etos = #65;
740 //description:
741 //prints "entity 1" or similar into a string. (this was a Q2 builtin)
742
743 //DP_QC_EXTRESPONSEPACKET
744 //idea: divVerent
745 //darkplaces implementation: divVerent
746 //builtin definitions:
747 string(void) getextresponse = #624;
748 //description:
749 //returns a string of the form "\"ipaddress:port\" data...", or the NULL string
750 //if no packet was found. Packets can be queued into the client/server by
751 //sending a packet starting with "\xFF\xFF\xFF\xFFextResponse " to the
752 //listening port.
753
754 //DP_QC_FINDCHAIN
755 //idea: LordHavoc
756 //darkplaces implementation: LordHavoc
757 //builtin definitions:
758 entity(.string fld, string match) findchain = #402;
759 //description:
760 //similar to find() but returns a chain of entities like findradius.
761
762 //DP_QC_FINDCHAIN_TOFIELD
763 //idea: divVerent
764 //darkplaces implementation: divVerent
765 //builtin definitions:
766 entity(.string fld, float match, .entity tofield) findradius_tofield = #22;
767 entity(.string fld, string match, .entity tofield) findchain_tofield = #402;
768 entity(.string fld, float match, .entity tofield) findchainflags_tofield = #450;
769 entity(.string fld, float match, .entity tofield) findchainfloat_tofield = #403;
770 //description:
771 //similar to findchain() etc, but stores the chain into .tofield instead of .chain
772 //actually, the .entity tofield is an optional field of the the existing findchain* functions
773
774 //DP_QC_FINDCHAINFLAGS
775 //idea: Sajt
776 //darkplaces implementation: LordHavoc
777 //builtin definitions:
778 entity(.float fld, float match) findchainflags = #450;
779 //description:
780 //similar to findflags() but returns a chain of entities like findradius.
781
782 //DP_QC_FINDCHAINFLOAT
783 //idea: LordHavoc
784 //darkplaces implementation: LordHavoc
785 //builtin definitions:
786 entity(.entity fld, entity match) findchainentity = #403;
787 entity(.float fld, float match) findchainfloat = #403;
788 //description:
789 //similar to findentity()/findfloat() but returns a chain of entities like findradius.
790
791 //DP_QC_FINDFLAGS
792 //idea: Sajt
793 //darkplaces implementation: LordHavoc
794 //builtin definitions:
795 entity(entity start, .float fld, float match) findflags = #449;
796 //description:
797 //finds an entity with the specified flag set in the field, similar to find()
798
799 //DP_QC_FINDFLOAT
800 //idea: LordHavoc
801 //darkplaces implementation: LordHavoc
802 //builtin definitions:
803 entity(entity start, .entity fld, entity match) findentity = #98;
804 entity(entity start, .float fld, float match) findfloat = #98;
805 //description:
806 //finds an entity or float field value, similar to find(), but for entity and float fields.
807
808 //DP_QC_FS_SEARCH
809 //idea: Black
810 //darkplaces implementation: Black
811 //builtin definitions:
812 float(string pattern, float caseinsensitive, float quiet) search_begin = #444;
813 void(float handle) search_end = #445;
814 float(float handle) search_getsize = #446;
815 string(float handle, float num) search_getfilename = #447;
816 //description:
817 //search_begin performs a filename search with the specified pattern (for example "maps/*.bsp") and stores the results in a search slot (minimum of 128 supported by any engine with this extension), the other functions take this returned search slot number, be sure to search_free when done (they are also freed on progs reload).
818 //search_end frees a search slot (also done at progs reload).
819 //search_getsize returns how many filenames were found.
820 //search_getfilename returns a filename from the search.
821
822 //DP_QC_GETLIGHT
823 //idea: LordHavoc
824 //darkplaces implementation: LordHavoc
825 //builtin definitions:
826 vector(vector org) getlight = #92;
827 //description:
828 //returns the lighting at the requested location (in color), 0-255 range (can exceed 255).
829
830 //DP_QC_GETSURFACE
831 //idea: LordHavoc
832 //darkplaces implementation: LordHavoc
833 //builtin definitions:
834 float(entity e, float s) getsurfacenumpoints = #434;
835 vector(entity e, float s, float n) getsurfacepoint = #435;
836 vector(entity e, float s) getsurfacenormal = #436;
837 string(entity e, float s) getsurfacetexture = #437;
838 float(entity e, vector p) getsurfacenearpoint = #438;
839 vector(entity e, float s, vector p) getsurfaceclippedpoint = #439;
840 //description:
841 //functions to query surface information.
842
843 //DP_QC_GETSURFACEPOINTATTRIBUTE
844 //idea: BlackHC
845 //darkplaces implementation: BlackHC
846 // constants
847 float SPA_POSITION = 0;
848 float SPA_S_AXIS = 1;
849 float SPA_T_AXIS = 2;
850 float SPA_R_AXIS = 3; // same as SPA_NORMAL
851 float SPA_TEXCOORDS0 = 4;
852 float SPA_LIGHTMAP0_TEXCOORDS = 5;
853 float SPA_LIGHTMAP0_COLOR = 6;
854 //builtin definitions:
855 vector(entity e, float s, float n, float a) getsurfacepointattribute = #486;
856
857 //description:
858 //function to query extended information about a point on a certain surface
859
860 //DP_QC_GETSURFACETRIANGLE
861 //idea: divVerent
862 //darkplaces implementation: divVerent
863 //builtin definitions:
864 float(entity e, float s) getsurfacenumtriangles = #628;
865 vector(entity e, float s, float n) getsurfacetriangle = #629;
866 //description:
867 //function to query triangles of a surface
868
869 //DP_QC_GETTAGINFO
870 //idea: VorteX, LordHavoc
871 //DarkPlaces implementation: VorteX
872 //builtin definitions:
873 float(entity ent, string tagname) gettagindex = #451;
874 vector(entity ent, float tagindex) gettaginfo = #452;
875 //description:
876 //gettagindex returns the number of a tag on an entity, this number is the same as set by setattachment (in the .tag_index field), allowing the qc to save a little cpu time by keeping the number around if it wishes (this could already be done by calling setattachment and saving off the tag_index).
877 //gettaginfo returns the origin of the tag in worldspace and sets v_forward, v_right, and v_up to the current orientation of the tag in worldspace, this automatically resolves all dependencies (attachments, including viewmodelforclient), this means you could fire a shot from a tag on a gun entity attached to the view for example.
878
879 //DP_QC_GETTAGINFO_BONEPROPERTIES
880 //idea: daemon
881 //DarkPlaces implementation: divVerent
882 //global definitions:
883 float gettaginfo_parent;
884 string gettaginfo_name;
885 vector gettaginfo_offset;
886 vector gettaginfo_forward;
887 vector gettaginfo_right;
888 vector gettaginfo_up;
889 //description:
890 //when this extension is present, gettaginfo fills in some globals with info about the bone that had been queried
891 //gettaginfo_parent is set to the number of the parent bone, or 0 if it is a root bone
892 //gettaginfo_name is set to the name of the bone whose index had been specified in gettaginfo
893 //gettaginfo_offset, gettaginfo_forward, gettaginfo_right, gettaginfo_up contain the transformation matrix of the bone relative to its parent. Note that the matrix may contain a scaling component.
894
895 //DP_QC_GETTIME
896 //idea: tZork
897 //darkplaces implementation: tZork, divVerent
898 //constant definitions:
899 float GETTIME_FRAMESTART = 0; // time of start of frame relative to an arbitrary point in time
900 float GETTIME_REALTIME = 1; // current absolute time (OS specific)
901 float GETTIME_HIRES = 2; // like REALTIME, but may reset between QC invocations and thus can be higher precision
902 float GETTIME_UPTIME = 3; // time of start of frame since start of the engine
903 //builtin definitions:
904 float(float tmr) gettime = #519;
905 //description:
906 //some timers to query...
907
908 //DP_QC_GETTIME_CDTRACK
909 //idea: divVerent
910 //darkplaces implementation: divVerent
911 //constant definitions:
912 float GETTIME_CDTRACK = 4;
913 //description:
914 //returns the playing time of the current cdtrack when passed to gettime()
915 //see DP_END_GETSOUNDTIME for similar functionality but for entity sound channels
916
917 //DP_QC_I18N
918 //idea: divVerent
919 //darkplaces implementation: divVerent
920 //description:
921 //
922 //The engine supports translating by gettext compatible .po files.
923 //progs.dat uses progs.dat.<LANGUAGE>.po
924 //menu.dat uses menu.dat.<LANGUAGE>.po
925 //csprogs.dat uses csprogs.dat.<LANGUAGE>.po
926 //
927 //To create a string that can be translated, define it as
928 //  string dotranslate_FILENOTFOUND = "File not found";
929 //Note: if the compiler does constant folding, this will only work if there is
930 //no other "File not found" string in the progs!
931 //
932 //Alternatively, if using the Xonotic patched fteqcc compiler, you can simplify
933 //this by using _("File not found") directly in the source code.
934 //
935 //The language is set by the "prvm_language" cvar: if prvm_language is set to
936 //"de", it will read progs.dat.de.po for translating strings in progs.dat.
937 //
938 //If prvm_language is set to the special name "dump", progs.dat.pot will be
939 //written, which is a translation template to be edited by filling out the
940 //msgstr entries.
941
942 //DP_QC_LOG
943 //darkplaces implementation: divVerent
944 //builtin definitions:
945 float log(float f) = #532;
946 //description:
947 //logarithm
948
949 //DP_QC_MINMAXBOUND
950 //idea: LordHavoc
951 //darkplaces implementation: LordHavoc
952 //builtin definitions:
953 float(float a, float b, ...) min = #94;
954 float(float a, float b, float c) min3 = #94;
955 float(float a, float b, float c, float d) min4 = #94;
956 float(float a, float b, float c, float d, float e) min5 = #94;
957 float(float a, float b, float c, float d, float e, float f) min6 = #94;
958 float(float a, float b, float c, float d, float e, float f, float g) min7 = #94;
959 float(float a, float b, float c, float d, float e, float f, float g, float h) min8 = #94;
960 float(float a, float b, ...) max = #95;
961 float(float a, float b, float c) max3 = #95;
962 float(float a, float b, float c, float d) max4 = #95;
963 float(float a, float b, float c, float d, float e) max5 = #95;
964 float(float a, float b, float c, float d, float e, float f) max6 = #95;
965 float(float a, float b, float c, float d, float e, float f, float g) max7 = #95;
966 float(float a, float b, float c, float d, float e, float f, float g, float h) max8 = #95;
967 float(float minimum, float val, float maximum) bound = #96;
968 //description:
969 //min returns the lowest of all the supplied numbers.
970 //max returns the highest of all the supplied numbers.
971 //bound clamps the value to the range and returns it.
972
973 //DP_QC_MULTIPLETEMPSTRINGS
974 //idea: LordHavoc
975 //darkplaces implementation: LordHavoc
976 //description:
977 //this extension makes all builtins returning tempstrings (ftos for example)
978 //cycle through a pool of multiple tempstrings (at least 16), allowing
979 //multiple ftos results to be gathered before putting them to use, normal
980 //quake only had 1 tempstring, causing many headaches.
981 //
982 //Note that for longer term storage (or compatibility on engines having
983 //FRIK_FILE but not this extension) the FRIK_FILE extension's
984 //strzone/strunzone builtins provide similar functionality (slower though).
985 //
986 //NOTE: this extension is superseded by DP_QC_UNLIMITEDTEMPSTRINGS
987
988 //DP_QC_NUM_FOR_EDICT
989 //idea: Blub\0
990 //darkplaces implementation: Blub\0
991 //Function to get the number of an entity - a clean way.
992 float(entity num) num_for_edict = #512;
993
994 //DP_QC_RANDOMVEC
995 //idea: LordHavoc
996 //darkplaces implementation: LordHavoc
997 //builtin definitions:
998 vector() randomvec = #91;
999 //description:
1000 //returns a vector of length < 1, much quicker version of this QC: do {v_x = random()*2-1;v_y = random()*2-1;v_z = random()*2-1;} while(vlen(v) > 1)
1001
1002 //DP_QC_SINCOSSQRTPOW
1003 //idea: id Software, LordHavoc
1004 //darkplaces implementation: id Software, LordHavoc
1005 //builtin definitions:
1006 float(float val) sin = #60;
1007 float(float val) cos = #61;
1008 float(float val) sqrt = #62;
1009 float(float a, float b) pow = #97;
1010 //description:
1011 //useful math functions, sine of val, cosine of val, square root of val, and raise a to power b, respectively.
1012
1013 //DP_QC_SPRINTF
1014 //idea: divVerent
1015 //darkplaces implementation: divVerent
1016 //builtin definitions:
1017 string(string format, ...) sprintf = #627;
1018 //description:
1019 //you know sprintf :P
1020 //supported stuff:
1021 //  %
1022 //  optional: <argpos>$ for the argument to format (the arg counter then is not increased)
1023 //  flags: #0- +
1024 //  optional: <width>, *, or *<argpos>$ for the field width (width is read before value and precision)
1025 //  optional: .<precision>, .*, or .*<argpos>$ for the precision (precision is read before value)
1026 //  length modifiers: h for forcing a float, l for forcing an entity (by default, %d etc. cast a float to int), ll for forcing an int
1027 //  conversions:
1028 //    d takes a float if no length is specified or h is, and an entity if l is specified as length, and an int if ll is specified as length, and cast it to an int
1029 //    i takes an entity if no length is specified or l is, and a float if h is specified as length, and an int if ll is specified as length, and cast it to an int
1030 //    ouxXc take a float if no length is specified or h is, and an entity if l is specified as length, and an int if ll is specified as length, and cast it to an unsigned int
1031 //    eEfFgG take a float if no length is specified or h is, and an entity if l is specified as length, and an int if ll is specified as length, and cast it to a double
1032 //    s takes a string
1033 //    vV takes a vector, and processes the three components as if it were a gG for all three components, separated by space
1034 //    For conversions s and c, the flag # makes precision and width interpreted
1035 //      as byte count, by default it is interpreted as character count in UTF-8
1036 //      enabled engines. No other conversions can create wide characters, and #
1037 //      has another meaning in these. When in character count mode, color codes
1038 //      are ignored. To get UTF-8 semantics WITHOUT color code parsing, use
1039 //      the + flag.
1040
1041 //DP_QC_STRFTIME
1042 //idea: LordHavoc
1043 //darkplaces implementation: LordHavoc
1044 //builtin definitions:
1045 string(float uselocaltime, string format, ...) strftime = #478;
1046 //description:
1047 //provides the ability to get the local (in your timezone) or world (Universal Coordinated Time) time as a string using the formatting of your choice:
1048 //example: "%Y-%m-%d %H:%M:%S"   (result looks like: 2007-02-08 01:03:15)
1049 //note: "%F %T" gives the same result as "%Y-%m-%d %H:%M:%S" (ISO 8601 date format and 24-hour time)
1050 //for more format codes please do a web search for strftime 3 and you should find the man(3) pages for this standard C function.
1051 //
1052 //practical uses:
1053 //changing day/night cycle (shops closing, monsters going on the prowl) in an RPG, for this you probably want to use s = strftime(TRUE, "%H");hour = stof(s);
1054 //printing current date/time for competitive multiplayer games, such as the beginning/end of each round in real world time.
1055 //activating eastereggs in singleplayer games on certain dates.
1056 //
1057 //note: some codes such as %x and %X use your locale settings and thus may not make sense to international users, it is not advisable to use these as the server and clients may be in different countries.
1058 //note: if you display local time to a player, it would be a good idea to note whether it is local time using a string like "%F %T (local)", and otherwise use "%F %T (UTC)".
1059 //note: be aware that if the game is saved and reloaded a week later the date and time will be different, so if activating eastereggs in a singleplayer game or something you may want to only check when a level is loaded and then keep the same easteregg state throughout the level so that the easteregg does not deactivate when reloading from a savegame (also be aware that precaches should not depend on such date/time code because reloading a savegame often scrambles the precaches if so!).
1060 //note: this function can return a NULL string (you can check for it with if (!s)) if the localtime/gmtime functions returned NULL in the engine code, such as if those functions don't work on this platform (consoles perhaps?), so be aware that this may return nothing.
1061
1062 //DP_QC_STRINGCOLORFUNCTIONS
1063 //idea: Dresk
1064 //darkplaces implementation: Dresk
1065 //builtin definitions:
1066 float(string s) strlennocol = #476; // returns how many characters are in a string, minus color codes
1067 string(string s) strdecolorize = #477; // returns a string minus the color codes of the string provided
1068 //description:
1069 //provides additional functionality to strings by supporting functions that isolate and identify strings with color codes
1070
1071 //DP_QC_STRING_CASE_FUNCTIONS
1072 //idea: Dresk
1073 //darkplaces implementation: LordHavoc / Dresk
1074 //builtin definitions:
1075 string(string s) strtolower = #480; // returns the passed in string in pure lowercase form
1076 string(string s) strtoupper = #481; // returns the passed in string in pure uppercase form
1077 //description:
1078 //provides simple string uppercase and lowercase functions
1079
1080 //DP_QC_TOKENIZEBYSEPARATOR
1081 //idea: Electro, SavageX, LordHavoc
1082 //darkplaces implementation: LordHavoc
1083 //builtin definitions:
1084 float(string s, string separator1, ...) tokenizebyseparator = #479;
1085 //description:
1086 //this function returns tokens separated by any of the supplied separator strings, example:
1087 //numnumbers = tokenizebyseparator("10.2.3.4", ".");
1088 //returns 4 and the tokens are "10" "2" "3" "4"
1089 //possibly useful for parsing IPv4 addresses (such as "1.2.3.4") and IPv6 addresses (such as "[1234:5678:9abc:def0:1234:5678:9abc:def0]:26000")
1090
1091 //DP_QC_TOKENIZE_CONSOLE
1092 //idea: divVerent
1093 //darkplaces implementation: divVerent
1094 //builtin definitions:
1095 float(string s) tokenize_console = #514;
1096 float(float i) argv_start_index = #515;
1097 float(float i) argv_end_index = #516;
1098 //description:
1099 //this function returns tokens separated just like the console does
1100 //also, functions are provided to get the index of the first and last character of each token in the original string
1101 //Passing negative values to them, or to argv, will be treated as indexes from the LAST token (like lists work in Perl). So argv(-1) will return the LAST token.
1102
1103 //DP_QC_TRACEBOX
1104 //idea: id Software
1105 //darkplaces implementation: id Software
1106 //builtin definitions:
1107 void(vector v1, vector min, vector max, vector v2, float nomonsters, entity forent) tracebox = #90;
1108 //description:
1109 //similar to traceline but much more useful, traces a box of the size specified (technical note: in quake1 and halflife bsp maps the mins and maxs will be rounded up to one of the hull sizes, quake3 bsp does not have this problem, this is the case with normal moving entities as well).
1110
1111 //DP_QC_TRACETOSS
1112 //idea: id Software
1113 //darkplaces implementation: id Software
1114 //builtin definitions:
1115 void(entity ent, entity ignore) tracetoss = #64;
1116 //description:
1117 //simulates movement of the entity as if it is MOVETYPE_TOSS and starting with it's current state (location, velocity, etc), returns relevant trace_ variables (trace_fraction is always 0, all other values are supported - trace_ent, trace_endpos, trace_plane_normal), does not actually alter the entity.
1118
1119 //DP_QC_TRACE_MOVETYPE_HITMODEL
1120 //idea: LordHavoc
1121 //darkplaces implementation: LordHavoc
1122 //constant definitions:
1123 float MOVE_HITMODEL = 4;
1124 //description:
1125 //allows traces to hit alias models (not sprites!) instead of entity boxes, use as the nomonsters parameter to trace functions, note that you can hit invisible model entities (alpha < 0 or EF_NODRAW or model "", it only checks modelindex)
1126
1127 //DP_QC_TRACE_MOVETYPE_WORLDONLY
1128 //idea: LordHavoc
1129 //darkplaces implementation: LordHavoc
1130 //constant definitions:
1131 float MOVE_WORLDONLY = 3;
1132 //description:
1133 //allows traces to hit only world (ignoring all entities, unlike MOVE_NOMONSTERS which hits all bmodels), use as the nomonsters parameter to trace functions
1134
1135 //DP_QC_UNLIMITEDTEMPSTRINGS
1136 //idea: divVerent
1137 //darkplaces implementation: LordHavoc
1138 //description:
1139 //this extension alters Quake behavior such that instead of reusing a single
1140 //tempstring (or multiple) there are an unlimited number of tempstrings, which
1141 //are removed only when a QC function invoked by the engine returns,
1142 //eliminating almost all imaginable concerns with string handling in QuakeC.
1143 //
1144 //in short:
1145 //you can now use and abuse tempstrings as much as you like, you still have to
1146 //use strzone (FRIK_FILE) for permanent storage however.
1147 //
1148 //
1149 //
1150 //implementation notes for other engine coders:
1151 //these tempstrings are expected to be stored in a contiguous buffer in memory
1152 //which may be fixed size or controlled by a cvar, or automatically grown on
1153 //demand (in the case of DarkPlaces).
1154 //
1155 //this concept is similar to quake's Zone system, however these are all freed
1156 //when the QC interpreter returns.
1157 //
1158 //this is basically a poor man's garbage collection system for strings.
1159
1160 //DP_QC_VECTOANGLES_WITH_ROLL
1161 //idea: LordHavoc
1162 //darkplaces implementation: LordHavoc
1163 //builtin definitions:
1164 vector(vector forward, vector up) vectoangles2 = #51; // same number as vectoangles
1165 //description:
1166 //variant of vectoangles that takes an up vector to calculate roll angle (also uses this to calculate yaw correctly if the forward is straight up or straight down)
1167 //note: just like normal vectoangles you need to negate the pitch of the returned angles if you want to feed them to makevectors or assign to self.v_angle
1168
1169 //DP_QC_VECTORVECTORS
1170 //idea: LordHavoc
1171 //darkplaces implementation: LordHavoc
1172 //builtin definitions:
1173 void(vector dir) vectorvectors = #432;
1174 //description:
1175 //creates v_forward, v_right, and v_up vectors given a forward vector, similar to makevectors except it takes a forward direction vector instead of angles.
1176
1177 //DP_QC_WHICHPACK
1178 //idea: divVerent
1179 //darkplaces implementation: divVerent
1180 //builtin definitions:
1181 string(string filename) whichpack = #503;
1182 //description:
1183 //for files in a pak/pk3/whatever, returns the pack's file name in FRIK_FILE name space.
1184 //for physical files, returns "".
1185 //in case of error, returns string_null.
1186
1187 //DP_QC_URI_ESCAPE
1188 //idea: divVerent
1189 //darkplaces implementation: divVerent
1190 //URI::Escape's functionality
1191 string(string in) uri_escape = #510;
1192 string(string in) uri_unescape = #511;
1193
1194 //DP_QC_URI_GET
1195 //idea: divVerent
1196 //darkplaces implementation: divVerent
1197 //loads text from an URL into a string
1198 //returns 1 on success of initiation, 0 if there are too many concurrent
1199 //connections already or if the URL is invalid
1200 //the following callback will receive the data and MUST exist!
1201 //  void(float id, float status, string data) URI_Get_Callback;
1202 //status is either
1203 //  negative for an internal error,
1204 //  0 for success, or
1205 //  the HTTP response code on server error (e.g. 404)
1206 //if 1 is returned by uri_get, the callback will be called in the future
1207 float(string url, float id) uri_get = #513;
1208
1209 //DP_QC_URI_POST
1210 //idea: divVerent
1211 //darkplaces implementation: divVerent
1212 //loads text from an URL into a string after POSTing via HTTP
1213 //works like uri_get, but uri_post sends data with Content-Type: content_type to the server
1214 //and uri_post sends the string buffer buf, joined using the delimiter delim
1215 float(string url, float id, string content_type, string data) uri_post = #513;
1216 float(string url, float id, string content_type, string delim, float buf) uri_postbuf = #513;
1217
1218 //DP_SKELETONOBJECTS
1219 //idea: LordHavoc
1220 //darkplaces implementation: LordHavoc
1221 //description:
1222 //this extension indicates that FTE_CSQC_SKELETONOBJECTS functionality is available in server QC (as well as CSQC).
1223
1224 //DP_SV_SPAWNFUNC_PREFIX
1225 //idea: divVerent
1226 //darkplaces implementation: divVerent
1227 //Make functions whose name start with spawnfunc_ take precedence as spawn function for loading entities.
1228 //Useful if you have a field ammo_shells (required in any Quake mod) but want to support spawn functions called ammo_shells (like in Q3A).
1229 //Optionally, you can declare a global "float require_spawnfunc_prefix;" which will require ANY spawn function to start with that prefix.
1230
1231
1232 //DP_QUAKE2_MODEL
1233 //idea: quake community
1234 //darkplaces implementation: LordHavoc
1235 //description:
1236 //shows that the engine supports Quake2 .md2 files.
1237
1238 //DP_QUAKE2_SPRITE
1239 //idea: LordHavoc
1240 //darkplaces implementation: Elric
1241 //description:
1242 //shows that the engine supports Quake2 .sp2 files.
1243
1244 //DP_QUAKE3_MAP
1245 //idea: quake community
1246 //darkplaces implementation: LordHavoc
1247 //description:
1248 //shows that the engine supports Quake3 .bsp files.
1249
1250 //DP_QUAKE3_MODEL
1251 //idea: quake community
1252 //darkplaces implementation: LordHavoc
1253 //description:
1254 //shows that the engine supports Quake3 .md3 files.
1255
1256 //DP_REGISTERCVAR
1257 //idea: LordHavoc
1258 //darkplaces implementation: LordHavoc
1259 //builtin definitions:
1260 float(string name, string value) registercvar = #93;
1261 //description:
1262 //adds a new console cvar to the server console (in singleplayer this is the player's console), the cvar exists until the mod is unloaded or the game quits.
1263 //NOTE: DP_CON_SET is much better.
1264
1265 //DP_SND_DIRECTIONLESSATTNNONE
1266 //idea: LordHavoc
1267 //darkplaces implementation: LordHavoc
1268 //description:
1269 //make sounds with ATTN_NONE have no spatialization (enabling easy use as music sources).
1270
1271 //DP_SND_FAKETRACKS
1272 //idea: requested
1273
1274 //darkplaces implementation: Elric
1275 //description:
1276 //the engine plays sound/cdtracks/track001.wav instead of cd track 1 and so on if found, this allows games and mods to have music tracks without using ambientsound.
1277 //Note: also plays .ogg with DP_SND_OGGVORBIS extension.
1278
1279 //DP_SND_SOUND7_WIP1
1280 //DP_SND_SOUND7_WIP2
1281 //idea: divVerent
1282 //darkplaces implementation: divVerent
1283 //builtin definitions:
1284 void(entity e, float chan, string samp, float vol, float atten, float speed, float flags) sound7 = #8;
1285 float SOUNDFLAG_RELIABLE = 1;
1286 //description:
1287 //plays a sound, with some more flags
1288 //extensions to sound():
1289 //- channel may be in the range from -128 to 127; channels -128 to 0 are "auto",
1290 //  i.e. support multiple sounds at once, but cannot be stopped/restarted
1291 //- a value 0 in the speed parameter means no change; otherwise, it is a
1292 //  percentage of playback speed ("pitch shifting"). 100 is normal pitch, 50 is
1293 //  half speed, 200 is double speed, etc. (DP_SND_SOUND7_WIP2)
1294 //- the flag SOUNDFLAG_RELIABLE can be specified, which makes the sound send
1295 //  to MSG_ALL (reliable) instead of MSG_BROADCAST (unreliable, default);
1296 //  similarily, SOUNDFLAG_RELIABLE_TO_ONE sends to MSG_ONE
1297 //- channel 0 is controlled by snd_channel0volume; channel 1 and -1 by
1298 //  snd_channel1volume, etc. (so, a channel shares the cvar with its respective
1299 //  auto-channel); however, the mod MUST define snd_channel8volume and upwards
1300 //  in default.cfg if they are to be used, as the engine does not create them
1301 //  to not litter the cvar list
1302 //- this extension applies to CSQC as well; CSQC_Event_Sound will get speed and
1303 //  flags as extra 7th and 8th argument
1304 //- WIP2 ideas: SOUNDFLAG_RELIABLE_TO_ONE, SOUNDFLAG_NOPHS, SOUNDFLAG_FORCELOOP
1305 //- NOTE: to check for this, ALSO OR a check with DP_SND_SOUND7 to also support
1306 //  the finished extension once done
1307
1308 //DP_SND_OGGVORBIS
1309 //idea: Transfusion
1310 //darkplaces implementation: Elric
1311 //description:
1312 //the engine supports loading Ogg Vorbis sound files.  Use either the .ogg filename directly, or a .wav of the same name (will try to load the .wav first and then .ogg).
1313
1314 //DP_SND_STEREOWAV
1315 //idea: LordHavoc
1316 //darkplaces implementation: LordHavoc
1317 //description:
1318 //the engine supports stereo WAV files.  (useful with DP_SND_DIRECTIONLESSATTNNONE for music)
1319
1320 //DP_SND_GETSOUNDTIME
1321 //idea: VorteX
1322 //darkplaces implementation: VorteX
1323 //constant definitions:
1324 float(entity e, float channel) getsoundtime = #533; // get currently sound playing position on entity channel, -1 if not playing or error
1325 float(string sample) soundlength = #534; // returns length of sound sample in seconds, -1 on error (sound not precached, sound system not initialized etc.)
1326 //description: provides opportunity to query length of sound samples and realtime tracking of sound playing on entities (similar to DP_GETTIME_CDTRACK)
1327 //note: beware dedicated server not running sound engine at all, so in dedicated mode this builtins will not work in server progs
1328 //note also: menu progs not supporting getsoundtime() (will give a warning) since it has no sound playing on entities
1329 //examples of use:
1330 //  - QC-driven looped sounds
1331 //  - QC events when sound playing is finished
1332 //  - toggleable ambientsounds
1333 //  - subtitles
1334
1335 //DP_VIDEO_DPV
1336 //idea: LordHavoc
1337 //darkplaces implementation: LordHavoc
1338 //console commands:
1339 //  playvideo <videoname> - start playing video
1340 //  stopvideo - stops current video
1341 //description: indicated that engine support playing videos in DPV format
1342
1343 //DP_VIDEO_SUBTITLES
1344 //idea: VorteX
1345 //darkplaces implementation: VorteX
1346 //cvars:
1347 //  cl_video_subtitles - toggles subtitles showing
1348 //  cl_video_subtitles_lines - how many lines to reserve for subtitles
1349 //  cl_video_subtitles_textsize - font size
1350 //console commands:
1351 //  playvideo <videoname> <custom_subtitles_file> - start playing video
1352 //  stopvideo - stops current video
1353 //description: indicates that engine support subtitles on videos
1354 //subtitles stored in external text files, each video file has it's default subtitles file ( <videoname>.dpsubs )
1355 //example: for video/act1.dpv default subtitles file will be video/act1.dpsubs
1356 //also video could be played with custom subtitles file by utilizing second parm of playvideo command
1357 //syntax of .dpsubs files: each line in .dpsubs file defines 1 subtitle, there are three tokens:
1358 //   <start> <end> "string"
1359 //   start: subtitle start time in seconds
1360 //     end: subtitle time-to-show in seconds, if 0 - subtitle will be showed until next subtitle is started, 
1361 //          if below 0 - show until next subtitles minus this number of seconds
1362 //    text: subtitle text, color codes (Q3-style and ^xRGB) are allowed
1363 //example of subtitle file:
1364 //   3  0       "Vengeance! Vengeance for my eternity of suffering!"
1365 //   9  0       "Whelp! As if you knew what eternity was!"
1366 //   13 0       "Grovel before your true master."
1367 //   17 0       "Never!" 
1368 //   18 7       "I'll hack you from crotch to gizzard and feed what's left of you to your brides..."
1369
1370 //DP_SOLIDCORPSE
1371 //idea: LordHavoc
1372 //darkplaces implementation: LordHavoc
1373 //solid definitions:
1374 float SOLID_CORPSE = 5;
1375 //description:
1376 //the entity will not collide with SOLID_CORPSE and SOLID_SLIDEBOX entities (and likewise they will not collide with it), this is useful if you want dead bodies that are shootable but do not obstruct movement by players and monsters, note that if you traceline with a SOLID_SLIDEBOX entity as the ignoreent, it will ignore SOLID_CORPSE entities, this is desirable for visibility and movement traces, but not for bullets, for the traceline to hit SOLID_CORPSE you must temporarily force the player (or whatever) to SOLID_BBOX and then restore to SOLID_SLIDEBOX after the traceline.
1377
1378 //DP_SPRITE32
1379 //idea: LordHavoc
1380 //darkplaces implementation: LordHavoc
1381 //description:
1382 //the engine supports .spr32 sprites.
1383
1384 //DP_SV_BOTCLIENT
1385 //idea: LordHavoc
1386 //darkplaces implementation: LordHavoc
1387 //constants:
1388 float CLIENTTYPE_DISCONNECTED = 0;
1389 float CLIENTTYPE_REAL = 1;
1390 float CLIENTTYPE_BOT = 2;
1391 float CLIENTTYPE_NOTACLIENT = 3;
1392 //builtin definitions:
1393 entity() spawnclient = #454; // like spawn but for client slots (also calls relevant connect/spawn functions), returns world if no clients available
1394 float(entity clent) clienttype = #455; // returns one of the CLIENTTYPE_* constants
1395 //description:
1396 //spawns a client with no network connection, to allow bots to use client slots with no hacks.
1397 //How to use:
1398 /*
1399         // to spawn a bot
1400         local entity oldself;
1401         oldself = self;
1402         self = spawnclient();
1403         if (!self)
1404         {
1405                 bprint("Can not add bot, server full.\n");
1406                 self = oldself;
1407                 return;
1408         }
1409         self.netname = "Yoyobot";
1410         self.clientcolors = 12 * 16 + 4; // yellow (12) shirt and red (4) pants
1411         ClientConnect();
1412         PutClientInServer();
1413         self = oldself;
1414
1415         // to remove all bots
1416         local entity head;
1417         head = find(world, classname, "player");
1418         while (head)
1419         {
1420                 if (clienttype(head) == CLIENTTYPE_BOT)
1421                         dropclient(head);
1422                 head = find(head, classname, "player");
1423         }
1424
1425         // to identify if a client is a bot (for example in PlayerPreThink)
1426         if (clienttype(self) == CLIENTTYPE_BOT)
1427                 botthink();
1428 */
1429 //see also DP_SV_CLIENTCOLORS DP_SV_CLIENTNAME DP_SV_DROPCLIENT
1430 //How it works:
1431 //creates a new client, calls SetNewParms and stores the parms, and returns the client.
1432 //this intentionally does not call SV_SendServerinfo to allow the QuakeC a chance to set the netname and clientcolors fields before actually spawning the bot by calling ClientConnect and PutClientInServer manually
1433 //on level change ClientConnect and PutClientInServer are called by the engine to spawn in the bot (this is why clienttype() exists to tell you on the next level what type of client this is).
1434 //parms work the same on bot clients as they do on real clients, and do carry from level to level
1435
1436 //DP_SV_BOUNCEFACTOR
1437 //idea: divVerent
1438 //darkplaces implementation: divVerent
1439 //field definitions:
1440 .float bouncefactor; // velocity multiplier after a bounce
1441 .float bouncestop; // bounce stops if velocity to bounce plane is < bouncestop * gravity AFTER the bounce
1442 //description:
1443 //allows qc to customize MOVETYPE_BOUNCE a bit
1444
1445 //DP_SV_CLIENTCAMERA
1446 //idea: LordHavoc, others
1447 //darkplaces implementation: Black
1448 //field definitions:
1449 .entity clientcamera; // override camera entity
1450 //description:
1451 //allows another entity to be the camera for a client, for example a remote camera, this is similar to sending svc_setview manually except that it also changes the network culling appropriately.
1452
1453 //DP_SV_CLIENTCOLORS
1454 //idea: LordHavoc
1455 //darkplaces implementation: LordHavoc
1456 //field definitions:
1457 .float clientcolors; // colors of the client (format: pants + shirt * 16)
1458 //description:
1459 //allows qc to read and modify the client colors associated with a client entity (not particularly useful on other entities), and automatically sends out any appropriate network updates if changed
1460
1461 //DP_SV_CLIENTNAME
1462 //idea: LordHavoc
1463 //darkplaces implementation: LordHavoc
1464 //description:
1465 //allows qc to modify the client's .netname, and automatically sends out any appropriate network updates if changed
1466
1467 //DP_SV_CUSTOMIZEENTITYFORCLIENT
1468 //idea: LordHavoc
1469 //darkplaces implementation: [515] and LordHavoc
1470 //field definitions:
1471 .float() customizeentityforclient; // self = this entity, other = client entity
1472 //description:
1473 //allows qc to modify an entity before it is sent to each client, the function returns TRUE if it should send, FALSE if it should not, and is fully capable of editing the entity's fields, this allows cloaked players to appear less transparent to their teammates, navigation markers to only show to their team, etc
1474 //tips on writing customize functions:
1475 //it is a good idea to return FALSE early in the function if possible to reduce cpu usage, because this function may be called many thousands of times per frame if there are many customized entities on a 64+ player server.
1476 //you are free to change anything in self, but please do not change any other entities (the results may be very inconsistent).
1477 //example ideas for use of this extension:
1478 //making icons over teammates' heads which are only visible to teammates.  for exasmple: float() playericon_customizeentityforclient = {return self.owner.team == other.team;};
1479 //making cloaked players more visible to their teammates than their enemies.  for example: float() player_customizeentityforclient = {if (self.items & IT_CLOAKING) {if (self.team == other.team) self.alpha = 0.6;else self.alpha = 0.1;} return TRUE;};
1480 //making explosion models that face the viewer (does not work well with chase_active).  for example: float() explosion_customizeentityforclient = {self.angles = vectoangles(other.origin + other.view_ofs - self.origin);self.angles_x = 0 - self.angles_x;};
1481 //implementation notes:
1482 //entity customization is done before per-client culling (visibility for instance) because the entity may be doing setorigin to display itself in different locations on different clients, may be altering its .modelindex, .effects and other fields important to culling, so customized entities increase cpu usage (non-customized entities can use all the early culling they want however, as they are not changing on a per client basis).
1483
1484 //DP_SV_DISABLECLIENTPREDICTION
1485 //idea: LordHavoc, Mario
1486 //darkplaces implementation: LordHavoc, Mario
1487 //field definitions:
1488 .float disableclientprediction;
1489 //description:
1490 //By default, player entities are enabled for prediction by the engine if the
1491 //engine assumes the client can sensibly predict them. As the NQ and DarkPlaces
1492 //protocol does not network movetype, this in particular allows for client
1493 //prediction only if movetype == MOVETYPE_WALK.
1494 //Setting this field to 1 disables prediction in any case - this is useful when
1495 //the client cannot sensibly predict the server's idea of how the player moves
1496 //(common in case of pure serverside grappling hook or jetpack
1497 //implementations).
1498 //Setting this field to -1 forces prediction even if the server assumes the
1499 //client cannot predict the current movetype of a player entity (obviously,
1500 //this then requires matching client-side prediction code in CSQC, as the
1501 //engine's own client prediction will sure not handle these cases right due to
1502 //not knowing the serverside value of movetype). This is allowed in combination
1503 //with the following movetypes:
1504 // MOVETYPE_NONE (useful to have full QC control over movement)
1505 // MOVETYPE_WALK (redundant but harmless)
1506 // MOVETYPE_STEP
1507 // MOVETYPE_FLY (useful for spectators)
1508 // MOVETYPE_TOSS
1509 // MOVETYPE_NOCLIP (useful for spectators)
1510 // MOVETYPE_FLYMISSILE
1511 // MOVETYPE_BOUNCE
1512 // MOVETYPE_BOUNCEMISSILE
1513 // MOVETYPE_FLY_WORLDONLY (useful for spectators)
1514
1515 //DP_SV_DISCARDABLEDEMO
1516 //idea: parasti
1517 //darkplaces implementation: parasti
1518 //field definitions:
1519 .float discardabledemo;
1520 //description:
1521 //when this field is set to a non-zero value on a player entity, a possibly recorded server-side demo for the player is discarded
1522 //Note that this extension only works if:
1523 //  auto demos are enabled (the cvar sv_autodemo_perclient is set)
1524 //  discarding demos is enabled (the cvar sv_autodemo_perclient_discardable is set)
1525
1526 //DP_SV_DRAWONLYTOCLIENT
1527 //idea: LordHavoc
1528 //darkplaces implementation: LordHavoc
1529 //field definitions:
1530 .entity drawonlytoclient;
1531 //description:
1532 //the entity is only visible to the specified client.
1533
1534 //DP_SV_DROPCLIENT
1535 //idea: FrikaC
1536 //darkplaces implementation: LordHavoc
1537 //builtin definitions:
1538 void(entity clent) dropclient = #453;
1539 //description:
1540 //causes the server to immediately drop the client, more reliable than stuffcmd(clent, "disconnect\n"); which could be intentionally ignored by the client engine
1541
1542 //DP_SV_EFFECT
1543 //idea: LordHavoc
1544 //darkplaces implementation: LordHavoc
1545 //builtin definitions:
1546 void(vector org, string modelname, float startframe, float endframe, float framerate) effect = #404;
1547 //SVC definitions:
1548 //float svc_effect = #52; // [vector] org [byte] modelindex [byte] startframe [byte] framecount [byte] framerate
1549 //float svc_effect2 = #53; // [vector] org [short] modelindex [byte] startframe [byte] framecount [byte] framerate
1550 //description:
1551 //clientside playback of simple custom sprite effects (explosion sprites, etc).
1552
1553 //DP_SV_ENTITYCONTENTSTRANSITION
1554 //idea: Dresk
1555 //darkplaces implementation: Dresk
1556 //field definitions:
1557 .void(float nOriginalContents, float nNewContents) contentstransition;
1558 //description:
1559 //This field function, when provided, is triggered on an entity when the contents (ie. liquid / water / etc) is changed.
1560 //The first parameter provides the entities original contents, prior to the transition.  The second parameter provides the new contents.
1561 //NOTE: If this field function is provided on an entity, the standard watersplash sound IS SUPPRESSED to allow for authors to create their own transition sounds.
1562
1563 //DP_SV_MOVETYPESTEP_LANDEVENT
1564 //idea: Dresk
1565 //darkplaces implementation: Dresk
1566 //field definitions:
1567 .void(vector vImpactVelocity) movetypesteplandevent;
1568 //description:
1569 //This field function, when provided, is triggered on a MOVETYPE_STEP entity when it experiences  "land event".
1570 // The standard engine behavior for this event is to play the sv_sound_land CVar sound.
1571 //The parameter provides the velocity of the entity at the time of the impact.  The z value may therefore be used to calculate how "hard" the entity struck the surface.
1572 //NOTE: If this field function is provided on a MOVETYPE_STEP entity, the standard sv_sound_land sound IS SUPPRESSED to allow for authors to create their own feedback.
1573
1574 //DP_SV_POINTSOUND
1575 //idea: Dresk
1576 //darkplaces implementation: Dresk
1577 //builtin definitions:
1578 void(vector origin, string sample, float volume, float attenuation) pointsound = #483;
1579 //description:
1580 //Similar to the standard QC sound function, this function takes an origin instead of an entity and omits the channel parameter.
1581 // This allows sounds to be played at arbitrary origins without spawning entities.
1582
1583 //DP_SV_ONENTITYNOSPAWNFUNCTION
1584 //idea: Dresk
1585 //darkplaces implementation: Dresk
1586 //engine-called QC prototypes:
1587 //void() SV_OnEntityNoSpawnFunction;
1588 //description:
1589 // This function is called whenever an entity on the server has no spawn function, and therefore has no defined QC behavior.
1590 // You may as such dictate the behavior as to what happens to the entity.
1591 // To mimic the engine's default behavior, simply call remove(self).
1592
1593 //DP_SV_ONENTITYPREPOSTSPAWNFUNCTION
1594 //idea: divVerent
1595 //darkplaces implementation: divVerent
1596 //engine-called QC prototypes:
1597 //void() SV_OnEntityPreSpawnFunction;
1598 //void() SV_OnEntityPostSpawnFunction;
1599 //description:
1600 // These functions are called BEFORE or AFTER an entity is spawned the regular way.
1601 // You may as such dictate the behavior as to what happens to the entity.
1602 // SV_OnEntityPreSpawnFunction is called before even looking for the spawn function, so you can even change its classname in there. If it remove()s the entity, the spawn function will not be looked for.
1603 // SV_OnEntityPostSpawnFunction is called ONLY after its spawn function or SV_OnEntityNoSpawnFunction was called, and skipped if the entity got removed by either.
1604
1605 //DP_SV_MODELFLAGS_AS_EFFECTS
1606 //idea: LordHavoc, Dresk
1607 //darkplaces implementation: LordHavoc
1608 //field definitions:
1609 .float modelflags;
1610 //constant definitions:
1611 float EF_NOMODELFLAGS = 8388608; // ignore any effects in a model file and substitute your own
1612 float MF_ROCKET  =   1; // leave a trail
1613 float MF_GRENADE =   2; // leave a trail
1614 float MF_GIB     =   4; // leave a trail
1615 float MF_ROTATE  =   8; // rotate (bonus items)
1616 float MF_TRACER  =  16; // green split trail
1617 float MF_ZOMGIB  =  32; // small blood trail
1618 float MF_TRACER2 =  64; // orange split trail
1619 float MF_TRACER3 = 128; // purple trail
1620 //description:
1621 //this extension allows model flags to be specified on entities so you can add a rocket trail and glow to any entity, etc.
1622 //setting any of these will override the flags the model already has, to disable the model's flags without supplying any of your own you must use EF_NOMODELFLAGS.
1623 //
1624 //silly example modification #1 to W_FireRocket in weapons.qc:
1625 //missile.effects = EF_NOMODELFLAGS; // rocket without a glow/fire trail
1626 //silly example modification #2 to W_FireRocket in weapons.qc:
1627 //missile.modelflags = MF_GIB; // leave a blood trail instead of glow/fire trail
1628 //
1629 //note: you can not combine multiple kinds of trail, only one of them will be active, you can combine MF_ROTATE and the other MF_ flags however, and using EF_NOMODELFLAGS along with these does no harm.
1630 //
1631 //note to engine coders: they are internally encoded in the protocol as extra EF_ flags (shift the values left 24 bits and send them in the protocol that way), so no protocol change was required (however 32bit effects is a protocol extension itself), within the engine they are referred to as EF_ for the 24bit shifted values.
1632
1633 //DP_SV_NETADDRESS
1634 //idea: Dresk
1635 //darkplaces implementation: Dresk
1636 //field definitions:
1637 .string netaddress;
1638 //description:
1639 // provides the netaddress of the associated entity (ie. 127.0.0.1) and "null/botclient" if the netconnection of the entity is invalid
1640
1641 //DP_SV_NODRAWTOCLIENT
1642 //idea: LordHavoc
1643 //darkplaces implementation: LordHavoc
1644 //field definitions:
1645 .entity nodrawtoclient;
1646 //description:
1647 //the entity is not visible to the specified client.
1648
1649 //DP_SV_PING
1650 //idea: LordHavoc
1651 //darkplaces implementation: LordHavoc
1652 //field definitions:
1653 .float ping;
1654 //description:
1655 //continuously updated field indicating client's ping (based on average of last 16 packet time differences).
1656
1657 //DP_SV_PING_PACKETLOSS
1658 //idea: LordHavoc
1659 //darkplaces implementation: LordHavoc
1660 //field definitions:
1661 .float ping_packetloss;
1662 .float ping_movementloss;
1663 //description:
1664 //continuously updated field indicating client's packet loss, and movement loss (i.e. packet loss affecting player movement).
1665
1666 //DP_SV_POINTPARTICLES
1667 //idea: Spike
1668 //darkplaces implementation: LordHavoc
1669 //function definitions:
1670 float(string effectname) particleeffectnum = #335; // same as in CSQC
1671 void(entity ent, float effectnum, vector start, vector end) trailparticles = #336; // same as in CSQC
1672 void(float effectnum, vector org, vector vel, float howmany) pointparticles = #337; // same as in CSQC
1673 //SVC definitions:
1674 //float svc_trailparticles = 60; // [short] entnum [short] effectnum [vector] start [vector] end
1675 //float svc_pointparticles = 61; // [short] effectnum [vector] start [vector] velocity [short] count
1676 //float svc_pointparticles1 = 62; // [short] effectnum [vector] start, same as svc_pointparticles except velocity is zero and count is 1
1677 //description:
1678 //provides the ability to spawn non-standard particle effects, typically these are defined in a particle effect information file such as effectinfo.txt in darkplaces.
1679 //this is a port of particle effect features from clientside QC (EXT_CSQC) to server QC, as these effects are potentially useful to all games even if they do not make use of EXT_CSQC.
1680 //warning: server must have same order of effects in effectinfo.txt as client does or the numbers would not match up, except for standard quake effects which are always the same numbers.
1681
1682 //DP_SV_PUNCHVECTOR
1683 //idea: LordHavoc
1684 //darkplaces implementation: LordHavoc
1685 //field definitions:
1686 .vector punchvector;
1687 //description:
1688 //offsets client view in worldspace, similar to view_ofs but all 3 components are used and are sent with at least 8 bits of fraction, this allows the view to be kicked around by damage or hard landings or whatever else, note that unlike punchangle this is not faded over time, it is up to the mod to fade it (see also DP_SV_PLAYERPHYSICS).
1689
1690 //DP_SV_PLAYERPHYSICS
1691 //idea: LordHavoc
1692 //darkplaces implementation: LordHavoc
1693 //field definitions:
1694 .vector movement;
1695 //cvar definitions:
1696 //"sv_playerphysicsqc" (0/1, default 1, allows user to disable qc player physics)
1697 //engine-called QC prototypes:
1698 //void() SV_PlayerPhysics;
1699 //description:
1700 //.movement vector contains the movement input from the player, allowing QC to do as it wishs with the input, and SV_PlayerPhysics will completely replace the player physics if present (works for all MOVETYPE's), see darkplaces mod source for example of this function (in playermovement.qc, adds HalfLife ladders support, as well as acceleration/deceleration while airborn (rather than the quake sudden-stop while airborn), and simplifies the physics a bit)
1701
1702 //DP_PHYSICS_ODE
1703 //idea: LordHavoc
1704 //darkplaces implementation: LordHavoc
1705 //globals:
1706 //new movetypes:
1707 const float MOVETYPE_PHYSICS = 32; // need to be set before any physics_* builtins applied
1708 //new solid types (deprecated):
1709 const float SOLID_PHYSICS_BOX = 32;
1710 const float SOLID_PHYSICS_SPHERE = 33;
1711 const float SOLID_PHYSICS_CAPSULE = 34;
1712 const float SOLID_PHYSICS_TRIMESH = 35;
1713 const float SOLID_PHYSICS_CYLINDER = 36;
1714 //geometry types:
1715 const float GEOMTYPE_NONE = -1;       // entity will be entirely skipped by ODE
1716 const float GEOMTYPE_SOLID = 0;       // geometry type will be set based on .solid field
1717 const float GEOMTYPE_BOX = 1;         // entity bound box
1718 const float GEOMTYPE_SPHERE = 2;      // sphere with radius picked from x axis of entity bound box
1719 const float GEOMTYPE_CAPSULE = 3;     // with leading axis automatically determined from longest one, radius is picked as minimal of the rest 2 axes
1720 const float GEOMTYPE_TRIMESH = 4;     // triangle mesh
1721 const float GEOMTYPE_CYLINDER = 5;    // like capsule but not capped
1722                                       // note that ODE's builtin cylinder support is experimental, somewhat bugged and unfinished (no cylinder-cylinder collision)
1723                                                                           // to use properly working cylinder should build ODE with LIBCCD extension
1724 const float GEOMTYPE_CAPSULE_X = 6;   // capsule with fixed leading axis
1725 const float GEOMTYPE_CAPSULE_Y = 7;
1726 const float GEOMTYPE_CAPSULE_Z = 8;
1727 const float GEOMTYPE_CYLINDER_X = 9;  // cylinder with fixed leading axis
1728 const float GEOMTYPE_CYLINDER_Y = 10;
1729 const float GEOMTYPE_CYLINDER_Z = 11;
1730 //joint types:
1731 const float JOINTTYPE_NONE = 0;
1732 const float JOINTTYPE_POINT = 1;
1733 const float JOINTTYPE_HINGE = 2;
1734 const float JOINTTYPE_SLIDER = 3;
1735 const float JOINTTYPE_UNIVERSAL = 4;
1736 const float JOINTTYPE_HINGE2 = 5;
1737 const float JOINTTYPE_FIXED = -1;
1738 //force types:
1739 const float FORCETYPE_NONE = 0;
1740 const float FORCETYPE_FORCE = 1; // applied at center of mass
1741 const float FORCETYPE_FORCEATPOS = 2;
1742 const float FORCETYPE_TORQUE = 3;
1743 // common joint properties:
1744 // .entity aiment; // connected objects
1745 // .entity enemy; // connected objects, forces
1746 // .vector movedir;
1747 //   for a spring:
1748 //     movedir_x = spring constant (force multiplier, must be > 0)
1749 //     movedir_y = spring dampening constant to prevent oscillation (must be > 0)
1750 //     movedir_z = spring stop position (+/-)
1751 //   for a motor:
1752 //     movedir_x = desired motor velocity
1753 //     movedir_y = -1 * max motor force to use
1754 //     movedir_z = stop position (+/-), set to 0 for no stop
1755 //   note that ODE does not support both in one anyway
1756 //   for a force:
1757 //     force vector to apply
1758 //field definitions:
1759 .float  geomtype;     // see GEOMTYPE_*, a more correct way to set collision shape, allows to set SOLID_CORPSE and trimesh collisions
1760 .float  maxcontacts;  // maximum number of contacts to make for this object, lesser = faster (but setting it too low will could make object pass though walls), default is 16, maximum is 32
1761 .float  mass;         // ODE mass, standart value is 1
1762 .vector massofs;      // offsets a mass center out of object center, if not set a center of model bounds is used
1763 .float  friction;     // a friction of object, get multiplied by second objects's friction on contact
1764 .float  bouncefactor;
1765 .float  bouncestop; 
1766 .float  jointtype;    // type of joint
1767 .float  forcetype;    // type of force
1768 .float  erp;          // error restitution parameter, makes ODE solver attempt to fix errors in contacts, 
1769                       // bringing together 2 joints or fixing object being stuch in other object, 
1770                                   // a value of 0.1 will fix slightly, a value of 1.0 attempts to fix whole error in one frame
1771                                   // use with care as high values makes system unstable and likely to explode
1772 //builtin definitions:
1773 void(entity e, float physics_enabled) physics_enable = #540; // enable or disable physics on object
1774 void(entity e, vector force, vector force_pos) physics_addforce = #541; // deprecated, apply a force from certain origin, length of force vector is power of force
1775 void(entity e, vector torque) physics_addtorque = #542; // deprecated, add relative torque
1776 //description: provides Open Dynamics Engine support, requires extenal dll to be present or engine compiled with statical link option
1777 //be sure to checkextension for it to know if library is loaded and ready, also to enable physics set "physics_ode" cvar to 1
1778 //note: this extension is highly experimental and may be unstable
1779
1780 //DP_SV_PRINT
1781 //idea: id Software (QuakeWorld Server)
1782 //darkplaces implementation: Black, LordHavoc
1783 void(string s, ...) print = #339; // same number as in EXT_CSQC
1784 //description:
1785 //this is identical to dprint except that it always prints regardless of the developer cvar.
1786
1787 //DP_SV_PRECACHEANYTIME
1788 //idea: id Software (Quake2)
1789 //darkplaces implementation: LordHavoc
1790 //description:
1791 //this extension allows precache_model and precache_sound (and any variants) to be used during the game (with automatic messages to clients to precache the new model/sound indices), also setmodel/sound/ambientsound can be called without precaching first (they will cause an automatic precache).
1792
1793 //DP_SV_QCSTATUS
1794 //idea: divVerent
1795 //darkplaces implementation: divVerent
1796 //1. A global variable
1797 string worldstatus;
1798 //Its content is set as "qcstatus" field in the rules.
1799 //It may be at most 255 characters, and must not contain newlines or backslashes.
1800 //2. A per-client field
1801 .string clientstatus;
1802 //It is sent instead of the "frags" in status responses.
1803 //It should always be set in a way so that stof(player.clientstatus) is a meaningful score value. Other info may be appended. If used this way, the cvar sv_status_use_qcstatus may be set to 1, and then this value will replace the frags in "status".
1804 //Currently, qstat does not support this and will not show player info if used and set to anything other than ftos(some integer).
1805
1806 //DP_SV_ROTATINGBMODEL
1807 //idea: id Software
1808 //darkplaces implementation: LordHavoc
1809 //description:
1810 //this extension merely indicates that MOVETYPE_PUSH supports avelocity, allowing rotating brush models to be created, they rotate around their origin (needs rotation supporting qbsp/light utilities because id ones expected bmodel entity origins to be '0 0 0', recommend setting "origin" key in the entity fields in the map before compiling, there may be other methods depending on your qbsp, most are more complicated however).
1811 //tip: level designers can create a func_wall with an origin, and avelocity (for example "avelocity" "0 90 0"), and "nextthink" "99999999" to make a rotating bmodel without any qc modifications, such entities will be solid in stock quake but will not rotate)
1812
1813 //DP_SV_SETCOLOR
1814 //idea: LordHavoc
1815 //darkplaces implementation: LordHavoc
1816 //builtin definitions:
1817 void(entity ent, float colors) setcolor = #401;
1818 //engine called QC functions (optional):
1819 //void(float color) SV_ChangeTeam;
1820 //description:
1821 //setcolor sets the color on a client and updates internal color information accordingly (equivalent to stuffing a "color" command but immediate)
1822 //SV_ChangeTeam is called by the engine whenever a "color" command is recieved, it may decide to do anything it pleases with the color passed by the client, including rejecting it (by doing nothing), or calling setcolor to apply it, preventing team changes is one use for this.
1823 //the color format is pants + shirt * 16 (0-255 potentially)
1824
1825 //DP_SV_SLOWMO
1826 //idea: LordHavoc
1827 //darkplaces implementation: LordHavoc
1828 //cvars:
1829 //"slowmo" (0+, default 1)
1830 //description:
1831 //sets the time scale of the server, mainly intended for use in singleplayer by the player, however potentially useful for mods, so here's an extension for it.
1832 //range is 0 to infinite, recommended values to try are 0.1 (very slow, 10% speed), 1 (normal speed), 5 (500% speed).
1833
1834 //DP_SV_WRITEPICTURE
1835 //idea: divVerent
1836 //darkplaces implementation: divVerent
1837 //builtin definitions:
1838 void(float to, string s, float sz) WritePicture = #501;
1839 //description:
1840 //writes a picture to the data stream so CSQC can read it using ReadPicture, which has the definition
1841 //  string(void) ReadPicture = #501;
1842 //The picture data is sent as at most sz bytes, by compressing to low quality
1843 //JPEG. The data being sent will be equivalent to:
1844 //  WriteString(to, s);
1845 //  WriteShort(to, imagesize);
1846 //  for(i = 0; i < imagesize; ++i)
1847 //    WriteByte(to, [the i-th byte of the compressed JPEG image]);
1848
1849 //DP_SV_WRITEUNTERMINATEDSTRING
1850 //idea: FrikaC
1851 //darkplaces implementation: Sajt
1852 //builtin definitions:
1853 void(float to, string s) WriteUnterminatedString = #456;
1854 //description:
1855 //like WriteString, but does not write a terminating 0 after the string. This means you can include things like a player's netname in the middle of a string sent over the network. Just be sure to end it up with either a call to WriteString (which includes the trailing 0) or WriteByte(0) to terminate it yourself.
1856 //A historical note: this extension was suggested by FrikaC years ago, more recently Shadowalker has been badmouthing LordHavoc and Spike for stealing 'his' extension writestring2 which does exactly the same thing but uses a different builtin number and name and extension string, this argument hinges on the idea that it was his idea in the first place, which is incorrect as FrikaC first suggested it and used a rough equivalent of it in his FrikBot mod years ago involving WriteByte calls on each character.
1857
1858 //DP_TE_BLOOD
1859 //idea: LordHavoc
1860 //darkplaces implementation: LordHavoc
1861 //builtin definitions:
1862 void(vector org, vector velocity, float howmany) te_blood = #405;
1863 //temp entity definitions:
1864 float TE_BLOOD = 50;
1865 //protocol:
1866 //vector origin
1867 //byte xvelocity (-128 to +127)
1868 //byte yvelocity (-128 to +127)
1869 //byte zvelocity (-128 to +127)
1870 //byte count (0 to 255, how much blood)
1871 //description:
1872 //creates a blood effect.
1873
1874 //DP_TE_BLOODSHOWER
1875 //idea: LordHavoc
1876 //darkplaces implementation: LordHavoc
1877 //builtin definitions:
1878 void(vector mincorner, vector maxcorner, float explosionspeed, float howmany) te_bloodshower = #406;
1879 //temp entity definitions:
1880 //float TE_BLOODSHOWER = 52;
1881 //protocol:
1882 //vector mins (minimum corner of the cube)
1883 //vector maxs (maximum corner of the cube)
1884 //coord explosionspeed (velocity of blood particles flying out of the center)
1885 //short count (number of blood particles)
1886 //description:
1887 //creates an exploding shower of blood, for making gibbings more convincing.
1888
1889 //DP_TE_CUSTOMFLASH
1890 //idea: LordHavoc
1891 //darkplaces implementation: LordHavoc
1892 //builtin definitions:
1893 void(vector org, float radius, float lifetime, vector color) te_customflash = #417;
1894 //temp entity definitions:
1895 //float TE_CUSTOMFLASH = 73;
1896 //protocol:
1897 //vector origin
1898 //byte radius ((MSG_ReadByte() + 1) * 8, meaning 8-2048 unit radius)
1899 //byte lifetime ((MSG_ReadByte() + 1) / 256.0, meaning approximately 0-1 second lifetime)
1900 //byte red (0.0 to 1.0 converted to 0-255)
1901 //byte green (0.0 to 1.0 converted to 0-255)
1902 //byte blue (0.0 to 1.0 converted to 0-255)
1903 //description:
1904 //creates a customized light flash.
1905
1906 //DP_TE_EXPLOSIONRGB
1907 //idea: LordHavoc
1908 //darkplaces implementation: LordHavoc
1909 //builtin definitions:
1910 void(vector org, vector color) te_explosionrgb = #407;
1911 //temp entity definitions:
1912 //float TE_EXPLOSIONRGB = 53;
1913 //protocol:
1914 //vector origin
1915 //byte red (0.0 to 1.0 converted to 0 to 255)
1916 //byte green (0.0 to 1.0 converted to 0 to 255)
1917 //byte blue (0.0 to 1.0 converted to 0 to 255)
1918 //description:
1919 //creates a colored explosion effect.
1920
1921 //DP_TE_FLAMEJET
1922 //idea: LordHavoc
1923 //darkplaces implementation: LordHavoc
1924 //builtin definitions:
1925 void(vector org, vector vel, float howmany) te_flamejet = #457;
1926 //temp entity definitions:
1927 //float TE_FLAMEJET = 74;
1928 //protocol:
1929 //vector origin
1930 //vector velocity
1931 //byte count (0 to 255, how many flame particles)
1932 //description:
1933 //creates a single puff of flame particles.  (not very useful really)
1934
1935 //DP_TE_PARTICLECUBE
1936 //idea: LordHavoc
1937 //darkplaces implementation: LordHavoc
1938 //builtin definitions:
1939 void(vector mincorner, vector maxcorner, vector vel, float howmany, float color, float gravityflag, float randomveljitter) te_particlecube = #408;
1940 //temp entity definitions:
1941 //float TE_PARTICLECUBE = 54;
1942 //protocol:
1943 //vector mins (minimum corner of the cube)
1944 //vector maxs (maximum corner of the cube)
1945 //vector velocity
1946 //short count
1947 //byte color (palette color)
1948 //byte gravity (TRUE or FALSE, FIXME should this be a scaler instead?)
1949 //coord randomvel (how much to jitter the velocity)
1950 //description:
1951 //creates a cloud of particles, useful for forcefields but quite customizable.
1952
1953 //DP_TE_PARTICLERAIN
1954 //idea: LordHavoc
1955 //darkplaces implementation: LordHavoc
1956 //builtin definitions:
1957 void(vector mincorner, vector maxcorner, vector vel, float howmany, float color) te_particlerain = #409;
1958 //temp entity definitions:
1959 //float TE_PARTICLERAIN = 55;
1960 //protocol:
1961 //vector mins (minimum corner of the cube)
1962 //vector maxs (maximum corner of the cube)
1963 //vector velocity (velocity of particles)
1964 //short count (number of particles)
1965 //byte color (8bit palette color)
1966 //description:
1967 //creates a shower of rain, the rain will appear either at the top (if falling down) or bottom (if falling up) of the cube.
1968
1969 //DP_TE_PARTICLESNOW
1970 //idea: LordHavoc
1971 //darkplaces implementation: LordHavoc
1972 //builtin definitions:
1973 void(vector mincorner, vector maxcorner, vector vel, float howmany, float color) te_particlesnow = #410;
1974 //temp entity definitions:
1975 //float TE_PARTICLERAIN = 56;
1976 //protocol:
1977 //vector mins (minimum corner of the cube)
1978 //vector maxs (maximum corner of the cube)
1979 //vector velocity (velocity of particles)
1980 //short count (number of particles)
1981 //byte color (8bit palette color)
1982 //description:
1983 //creates a shower of snow, the snow will appear either at the top (if falling down) or bottom (if falling up) of the cube, low velocities are advisable for convincing snow.
1984
1985 //DP_TE_PLASMABURN
1986 //idea: LordHavoc
1987 //darkplaces implementation: LordHavoc
1988 //builtin definitions:
1989 void(vector org) te_plasmaburn = #433;
1990 //temp entity definitions:
1991 //float TE_PLASMABURN = 75;
1992 //protocol:
1993 //vector origin
1994 //description:
1995 //creates a small light flash (radius 200, time 0.2) and marks the walls.
1996
1997 //DP_TE_QUADEFFECTS1
1998 //idea: LordHavoc
1999 //darkplaces implementation: LordHavoc
2000 //builtin definitions:
2001 void(vector org) te_gunshotquad = #412;
2002 void(vector org) te_spikequad = #413;
2003 void(vector org) te_superspikequad = #414;
2004 void(vector org) te_explosionquad = #415;
2005 //temp entity definitions:
2006 //float   TE_GUNSHOTQUAD  = 57; // [vector] origin
2007 //float   TE_SPIKEQUAD    = 58; // [vector] origin
2008 //float   TE_SUPERSPIKEQUAD = 59; // [vector] origin
2009 //float   TE_EXPLOSIONQUAD = 70; // [vector] origin
2010 //protocol:
2011 //vector origin
2012 //description:
2013 //all of these just take a location, and are equivalent in function (but not appearance :) to the original TE_GUNSHOT, etc.
2014
2015 //DP_TE_SMALLFLASH
2016 //idea: LordHavoc
2017 //darkplaces implementation: LordHavoc
2018 //builtin definitions:
2019 void(vector org) te_smallflash = #416;
2020 //temp entity definitions:
2021 //float TE_SMALLFLASH = 72;
2022 //protocol:
2023 //vector origin
2024 //description:
2025 //creates a small light flash (radius 200, time 0.2).
2026
2027 //DP_TE_SPARK
2028 //idea: LordHavoc
2029 //darkplaces implementation: LordHavoc
2030 //builtin definitions:
2031 void(vector org, vector vel, float howmany) te_spark = #411;
2032 //temp entity definitions:
2033 //float TE_SPARK = 51;
2034 //protocol:
2035 //vector origin
2036 //byte xvelocity (-128 to 127)
2037 //byte yvelocity (-128 to 127)
2038 //byte zvelocity (-128 to 127)
2039 //byte count (number of sparks)
2040 //description:
2041 //creates a shower of sparks and a smoke puff.
2042
2043 //DP_TE_STANDARDEFFECTBUILTINS
2044 //idea: LordHavoc
2045 //darkplaces implementation: LordHavoc
2046 //builtin definitions:
2047 void(vector org) te_gunshot = #418;
2048 void(vector org) te_spike = #419;
2049 void(vector org) te_superspike = #420;
2050 void(vector org) te_explosion = #421;
2051 void(vector org) te_tarexplosion = #422;
2052 void(vector org) te_wizspike = #423;
2053 void(vector org) te_knightspike = #424;
2054 void(vector org) te_lavasplash = #425;
2055 void(vector org) te_teleport = #426;
2056 void(vector org, float color, float colorlength) te_explosion2 = #427;
2057 void(entity own, vector start, vector end) te_lightning1 = #428;
2058 void(entity own, vector start, vector end) te_lightning2 = #429;
2059 void(entity own, vector start, vector end) te_lightning3 = #430;
2060 void(entity own, vector start, vector end) te_beam = #431;
2061 //description:
2062 //to make life easier on mod coders.
2063
2064 //DP_TRACE_HITCONTENTSMASK_SURFACEINFO
2065 //idea: LordHavoc
2066 //darkplaces implementation: LordHavoc
2067 //globals:
2068 .float dphitcontentsmask; // if non-zero on the entity passed to traceline/tracebox/tracetoss this will override the normal collidable contents rules and instead hit these contents values (for example AI can use tracelines that hit DONOTENTER if it wants to, by simply changing this field on the entity passed to traceline), this affects normal movement as well as trace calls
2069 float trace_dpstartcontents; // DPCONTENTS_ value at start position of trace
2070 float trace_dphitcontents; // DPCONTENTS_ value of impacted surface (not contents at impact point, just contents of the surface that was hit)
2071 float trace_dphitq3surfaceflags; // Q3SURFACEFLAG_ value of impacted surface
2072 string trace_dphittexturename; // texture name of impacted surface
2073 //constants:
2074 float DPCONTENTS_SOLID = 1; // hit a bmodel, not a bounding box
2075 float DPCONTENTS_WATER = 2;
2076 float DPCONTENTS_SLIME = 4;
2077 float DPCONTENTS_LAVA = 8;
2078 float DPCONTENTS_SKY = 16;
2079 float DPCONTENTS_BODY = 32; // hit a bounding box, not a bmodel
2080 float DPCONTENTS_CORPSE = 64; // hit a SOLID_CORPSE entity
2081 float DPCONTENTS_NODROP = 128; // an area where backpacks should not spawn
2082 float DPCONTENTS_PLAYERCLIP = 256; // blocks player movement
2083 float DPCONTENTS_MONSTERCLIP = 512; // blocks monster movement
2084 float DPCONTENTS_DONOTENTER = 1024; // AI hint brush
2085 float DPCONTENTS_LIQUIDSMASK = 14; // WATER | SLIME | LAVA
2086 float DPCONTENTS_BOTCLIP = 2048; // AI hint brush
2087 float DPCONTENTS_OPAQUE = 4096; // only fully opaque brushes get this (may be useful for line of sight checks)
2088 float Q3SURFACEFLAG_NODAMAGE = 1;
2089 float Q3SURFACEFLAG_SLICK = 2; // low friction surface
2090 float Q3SURFACEFLAG_SKY = 4; // sky surface (also has NOIMPACT and NOMARKS set)
2091 float Q3SURFACEFLAG_LADDER = 8; // climbable surface
2092 float Q3SURFACEFLAG_NOIMPACT = 16; // projectiles should remove themselves on impact (this is set on sky)
2093 float Q3SURFACEFLAG_NOMARKS = 32; // projectiles should not leave marks, such as decals (this is set on sky)
2094 float Q3SURFACEFLAG_FLESH = 64; // projectiles should do a fleshy effect (blood?) on impact
2095 float Q3SURFACEFLAG_NODRAW = 128; // compiler hint (not important to qc)
2096 //float Q3SURFACEFLAG_HINT = 256; // compiler hint (not important to qc)
2097 //float Q3SURFACEFLAG_SKIP = 512; // compiler hint (not important to qc)
2098 //float Q3SURFACEFLAG_NOLIGHTMAP = 1024; // compiler hint (not important to qc)
2099 //float Q3SURFACEFLAG_POINTLIGHT = 2048; // compiler hint (not important to qc)
2100 float Q3SURFACEFLAG_METALSTEPS = 4096; // walking on this surface should make metal step sounds
2101 float Q3SURFACEFLAG_NOSTEPS = 8192; // walking on this surface should not make footstep sounds
2102 float Q3SURFACEFLAG_NONSOLID = 16384; // compiler hint (not important to qc)
2103 //float Q3SURFACEFLAG_LIGHTFILTER = 32768; // compiler hint (not important to qc)
2104 //float Q3SURFACEFLAG_ALPHASHADOW = 65536; // compiler hint (not important to qc)
2105 //float Q3SURFACEFLAG_NODLIGHT = 131072; // compiler hint (not important to qc)
2106 //float Q3SURFACEFLAG_DUST = 262144; // translucent 'light beam' effect (not important to qc)
2107 //description:
2108 //adds additional information after a traceline/tracebox/tracetoss call.
2109 //also (very important) sets trace_* globals before calling .touch functions,
2110 //this allows them to inspect the nature of the collision (for example
2111 //determining if a projectile hit sky), clears trace_* variables for the other
2112 //object in a touch event (that is to say, a projectile moving will see the
2113 //trace results in its .touch function, but the player it hit will see very
2114 //little information in the trace_ variables as it was not moving at the time)
2115
2116 //DP_VIEWZOOM
2117 //idea: LordHavoc
2118 //darkplaces implementation: LordHavoc
2119 //field definitions:
2120 .float viewzoom;
2121 //description:
2122 //scales fov and sensitivity of player, valid range is 0 to 1 (intended for sniper rifle zooming, and such)
2123
2124 //EXT_BITSHIFT
2125 //idea: Spike
2126 //darkplaces implementation: [515]
2127 //builtin definitions:
2128 float(float number, float quantity) bitshift = #218;
2129 //description:
2130 //multiplies number by a power of 2 corresponding to quantity (0 = *1, 1 = *2, 2 = *4, 3 = *8, -1 = /2, -2 = /4x, etc), and rounds down (due to integer math) like other bit operations do (& and | and the like).
2131 //note: it is faster to use multiply if you are shifting by a constant, avoiding the quakec function call cost, however that does not do a floor for you.
2132
2133 //FRIK_FILE
2134 //idea: FrikaC
2135 //darkplaces implementation: LordHavoc
2136 //builtin definitions:
2137 float(string s) stof = #81; // get numerical value from a string
2138 float(string filename, float mode) fopen = #110; // opens a file inside quake/gamedir/data/ (mode is FILE_READ, FILE_APPEND, or FILE_WRITE), returns fhandle >= 0 if successful, or fhandle < 0 if unable to open file for any reason
2139 void(float fhandle) fclose = #111; // closes a file
2140 string(float fhandle) fgets = #112; // reads a line of text from the file and returns as a tempstring
2141 void(float fhandle, string s, ...) fputs = #113; // writes a line of text to the end of the file
2142 float(string s) strlen = #114; // returns how many characters are in a string
2143 string(string s1, string s2, ...) strcat = #115; // concatenates two or more strings (for example "abc", "def" would return "abcdef") and returns as a tempstring
2144 string(string s, float start, float length) substring = #116; // returns a section of a string as a tempstring - see FTE_STRINGS for enhanced version
2145 vector(string s) stov = #117; // returns vector value from a string
2146 string(string s, ...) strzone = #118; // makes a copy of a string into the string zone and returns it, this is often used to keep around a tempstring for longer periods of time (tempstrings are replaced often)
2147 void(string s) strunzone = #119; // removes a copy of a string from the string zone (you can not use that string again or it may crash!!!)
2148 //constants:
2149 float FILE_READ = 0;
2150 float FILE_APPEND = 1;
2151 float FILE_WRITE = 2;
2152 //cvars:
2153 //pr_zone_min_strings : default 64 (64k), min 64 (64k), max 8192 (8mb)
2154 //description:
2155 //provides text file access functions and string manipulation functions, note that you may want to set pr_zone_min_strings in the worldspawn function if 64k is not enough string zone space.
2156 //
2157 //NOTE: strzone functionality is partially superseded by
2158 //DP_QC_UNLIMITEDTEMPSTRINGS when longterm storage is not needed
2159 //NOTE: substring is upgraded by FTE_STRINGS extension with negative start/length handling identical to php 5.2.0
2160
2161 //FTE_CSQC_SKELETONOBJECTS
2162 //idea: Spike, LordHavoc
2163 //darkplaces implementation: LordHavoc
2164 //builtin definitions:
2165 // all skeleton numbers are 1-based (0 being no skeleton)
2166 // all bone numbers are 1-based (0 being invalid)
2167 float(float modlindex) skel_create = #263; // create a skeleton (be sure to assign this value into .skeletonindex for use), returns skeleton index (1 or higher) on success, returns 0 on failure (for example if the modelindex is not skeletal), it is recommended that you create a new skeleton if you change modelindex, as the skeleton uses the hierarchy from the model.
2168 float(float skel, entity ent, float modlindex, float retainfrac, float firstbone, float lastbone) skel_build = #264; // blend in a percentage of standard animation, 0 replaces entirely, 1 does nothing, 0.5 blends half, etc, and this only alters the bones in the specified range for which out of bounds values like 0,100000 are safe (uses .frame, .frame2, .frame3, .frame4, .lerpfrac, .lerpfrac3, .lerpfrac4, .frame1time, .frame2time, .frame3time, .frame4time), returns skel on success, 0 on failure
2169 float(float skel) skel_get_numbones = #265; // returns how many bones exist in the created skeleton, 0 if skeleton does not exist
2170 string(float skel, float bonenum) skel_get_bonename = #266; // returns name of bone (as a tempstring), "" if invalid bonenum (< 1 for example) or skeleton does not exist
2171 float(float skel, float bonenum) skel_get_boneparent = #267; // returns parent num for supplied bonenum, 0 if bonenum has no parent or bone does not exist (returned value is always less than bonenum, you can loop on this)
2172 float(float skel, string tagname) skel_find_bone = #268; // get number of bone with specified name, 0 on failure, bonenum (1-based) on success, same as using gettagindex but takes modelindex instead of entity
2173 vector(float skel, float bonenum) skel_get_bonerel = #269; // get matrix of bone in skeleton relative to its parent - sets v_forward, v_right, v_up, returns origin (relative to parent bone)
2174 vector(float skel, float bonenum) skel_get_boneabs = #270; // get matrix of bone in skeleton in model space - sets v_forward, v_right, v_up, returns origin (relative to entity)
2175 void(float skel, float bonenum, vector org) skel_set_bone = #271; // set matrix of bone relative to its parent, reads v_forward, v_right, v_up, takes origin as parameter (relative to parent bone)
2176 void(float skel, float bonenum, vector org) skel_mul_bone = #272; // transform bone matrix (relative to its parent) by the supplied matrix in v_forward, v_right, v_up, takes origin as parameter (relative to parent bone)
2177 void(float skel, float startbone, float endbone, vector org) skel_mul_bones = #273; // transform bone matrices (relative to their parents) by the supplied matrix in v_forward, v_right, v_up, takes origin as parameter (relative to parent bones)
2178 void(float skeldst, float skelsrc, float startbone, float endbone) skel_copybones = #274; // copy bone matrices (relative to their parents) from one skeleton to another, useful for copying a skeleton to a corpse
2179 void(float skel) skel_delete = #275; // deletes skeleton at the beginning of the next frame (you can add the entity, delete the skeleton, renderscene, and it will still work)
2180 float(float modlindex, string framename) frameforname = #276; // finds number of a specified frame in the animation, returns -1 if no match found
2181 float(float modlindex, float framenum) frameduration = #277; // returns the intended play time (in seconds) of the specified framegroup, if it does not exist the result is 0, if it is a single frame it may be a small value around 0.1 or 0.
2182 //fields:
2183 .float skeletonindex; // active skeleton overriding standard animation on model
2184 .float frame; // primary framegroup animation (strength = 1 - lerpfrac - lerpfrac3 - lerpfrac4)
2185 .float frame2; // secondary framegroup animation (strength = lerpfrac)
2186 .float frame3; // tertiary framegroup animation (strength = lerpfrac3)
2187 .float frame4; // quaternary framegroup animation (strength = lerpfrac4)
2188 .float lerpfrac; // strength of framegroup blend
2189 .float lerpfrac3; // strength of framegroup blend
2190 .float lerpfrac4; // strength of framegroup blend
2191 .float frame1time; // start time of framegroup animation
2192 .float frame2time; // start time of framegroup animation
2193 .float frame3time; // start time of framegroup animation
2194 .float frame4time; // start time of framegroup animation
2195 //description:
2196 //this extension provides a way to do complex skeletal animation on an entity.
2197 //
2198 //see also DP_SKELETONOBJECTS (this extension implemented on server as well as client)
2199 //
2200 //notes:
2201 //each model contains its own skeleton, reusing a skeleton with incompatible models will yield garbage (or not render).
2202 //each model contains its own animation data, you can use animations from other model files (for example saving out all character animations as separate model files).
2203 //if an engine supports loading an animation-only file format such as .md5anim in FTEQW, it can be used to animate any model with a compatible skeleton.
2204 //proper use of this extension may require understanding matrix transforms (v_forward, v_right, v_up, origin), and you must keep in mind that v_right is negative for this purpose.
2205 //
2206 //features include:
2207 //multiple animations blended together.
2208 //animating a model with animations from another model with a compatible skeleton.
2209 //restricting animation blends to certain bones of a model - for example independent animation of legs, torso, head.
2210 //custom bone controllers - for example making eyes track a target location.
2211 //
2212 //
2213 //
2214 //example code follows...
2215 //
2216 //this helper function lets you identify (by parentage) what group a bone
2217 //belongs to - for example "torso", "leftarm", would return 1 ("torso") for
2218 //all children of the bone named "torso", unless they are children of
2219 //"leftarm" (which is a child of "torso") which would return 2 instead...
2220 float(float skel, float bonenum, string g1, string g2, string g3, string g4, string g5, string g6) example_skel_findbonegroup =
2221 {
2222         local string bonename;
2223         while (bonenum >= 0)
2224         {
2225                 bonename = skel_get_bonename(skel, bonenum);
2226                 if (bonename == g1) return 1;
2227                 if (bonename == g2) return 2;
2228                 if (bonename == g3) return 3;
2229                 if (bonename == g4) return 4;
2230                 if (bonename == g5) return 5;
2231                 if (bonename == g6) return 6;
2232                 bonenum = skel_get_boneparent(skel, bonenum);
2233         }
2234         return 0;
2235 };
2236 // create a skeletonindex for our player using current modelindex
2237 void() example_skel_player_setup =
2238 {
2239         self.skeletonindex = skel_create(self.modelindex);
2240 };
2241 // setup bones of skeleton based on an animation
2242 // note: animmodelindex can be a different model than self.modelindex
2243 void(float animmodelindex, float framegroup, float framegroupstarttime) example_skel_player_update_begin =
2244 {
2245         // start with our standard animation
2246         self.frame = framegroup;
2247         self.frame2 = 0;
2248         self.frame3 = 0;
2249         self.frame4 = 0;
2250         self.frame1time = framegroupstarttime;
2251         self.frame2time = 0;
2252         self.frame3time = 0;
2253         self.frame4time = 0;
2254         self.lerpfrac = 0;
2255         self.lerpfrac3 = 0;
2256         self.lerpfrac4 = 0;
2257         skel_build(self.skeletonindex, self, animmodelindex, 0, 0, 100000);
2258 };
2259 // apply a different framegroup animation to bones with a specified parent
2260 void(float animmodelindex, float framegroup, float framegroupstarttime, float blendalpha, string groupbonename, string excludegroupname1, string excludegroupname2) example_skel_player_update_applyoverride =
2261 {
2262         local float bonenum;
2263         local float numbones;
2264         self.frame = framegroup;
2265         self.frame2 = 0;
2266         self.frame3 = 0;
2267         self.frame4 = 0;
2268         self.frame1time = framegroupstarttime;
2269         self.frame2time = 0;
2270         self.frame3time = 0;
2271         self.frame4time = 0;
2272         self.lerpfrac = 0;
2273         self.lerpfrac3 = 0;
2274         self.lerpfrac4 = 0;
2275         bonenum = 0;
2276         numbones = skel_get_numbones(self.skeletonindex);
2277         while (bonenum < numbones)
2278         {
2279                 if (example_skel_findbonegroup(self.skeletonindex, bonenum, groupbonename, excludegroupname1, excludegroupname2, "", "", "") == 1)
2280                         skel_build(self.skeletonindex, self, animmodelindex, 1 - blendalpha, bonenum, bonenum + 1);
2281                 bonenum = bonenum + 1;
2282         }
2283 };
2284 // make eyes point at a target location, be sure v_forward, v_right, v_up are set correctly before calling
2285 void(vector eyetarget, string bonename) example_skel_player_update_eyetarget =
2286 {
2287         local float bonenum;
2288         local vector ang;
2289         local vector oldforward, oldright, oldup;
2290         local vector relforward, relright, relup, relorg;
2291         local vector boneforward, boneright, boneup, boneorg;
2292         local vector parentforward, parentright, parentup, parentorg;
2293         local vector u, v;
2294         local vector modeleyetarget;
2295         bonenum = skel_find_bone(self.skeletonindex, bonename) - 1;
2296         if (bonenum < 0)
2297                 return;
2298         oldforward = v_forward;
2299         oldright = v_right;
2300         oldup = v_up;
2301         v = eyetarget - self.origin;
2302         modeleyetarget_x =   v * v_forward;
2303         modeleyetarget_y = 0-v * v_right;
2304         modeleyetarget_z =   v * v_up;
2305         // this is an eyeball, make it point at the target location
2306         // first get all the data we can...
2307         relorg = skel_get_bonerel(self.skeletonindex, bonenum);
2308         relforward = v_forward;
2309         relright = v_right;
2310         relup = v_up;
2311         boneorg = skel_get_boneabs(self.skeletonindex, bonenum);
2312         boneforward = v_forward;
2313         boneright = v_right;
2314         boneup = v_up;
2315         parentorg = skel_get_boneabs(self.skeletonindex, skel_get_boneparent(self.skeletonindex, bonenum));
2316         parentforward = v_forward;
2317         parentright = v_right;
2318         parentup = v_up;
2319         // get the vector from the eyeball to the target
2320         u = modeleyetarget - boneorg;
2321         // now transform it inversely by the parent matrix to produce new rel vectors
2322         v_x = u * parentforward;
2323         v_y = u * parentright;
2324         v_z = u * parentup;
2325         ang = vectoangles2(v, relup);
2326         ang_x = 0 - ang_x;
2327         makevectors(ang);
2328         // set the relative bone matrix
2329         skel_set_bone(self.skeletonindex, bonenum, relorg);
2330         // restore caller's v_ vectors
2331         v_forward = oldforward;
2332         v_right = oldright;
2333         v_up = oldup;
2334 };
2335 // delete skeleton when we're done with it
2336 // note: skeleton remains valid until next frame when it is really deleted
2337 void() example_skel_player_delete =
2338 {
2339         skel_delete(self.skeletonindex);
2340         self.skeletonindex = 0;
2341 };
2342 //
2343 // END OF EXAMPLES FOR FTE_CSQC_SKELETONOBJECTS
2344 //
2345
2346 //KRIMZON_SV_PARSECLIENTCOMMAND
2347 //idea: KrimZon
2348 //darkplaces implementation: KrimZon, LordHavoc
2349 //engine-called QC prototypes:
2350 //void(string s) SV_ParseClientCommand;
2351 //builtin definitions:
2352 void(entity e, string s) clientcommand = #440;
2353 float(string s) tokenize = #441;
2354 string(float n) argv = #442;
2355 //description:
2356 //provides QC the ability to completely control server interpretation of client commands ("say" and "color" for example, clientcommand is necessary for this and substring (FRIK_FILE) is useful) as well as adding new commands (tokenize, argv, and stof (FRIK_FILE) are useful for this)), whenever a clc_stringcmd is received the QC function is called, and it is up to the QC to decide what (if anything) to do with it
2357
2358 //NEH_CMD_PLAY2
2359 //idea: Nehahra
2360 //darkplaces implementation: LordHavoc
2361 //description:
2362 //shows that the engine supports the "play2" console command (plays a sound without spatialization).
2363
2364 //NEH_RESTOREGAME
2365 //idea: Nehahra
2366 //darkplaces implementation: LordHavoc
2367 //engine-called QC prototypes:
2368 //void() RestoreGame;
2369 //description:
2370 //when a savegame is loaded, this function is called
2371
2372 //NEXUIZ_PLAYERMODEL
2373 //idea: Nexuiz
2374 //darkplaces implementation: Black
2375 //console commands:
2376 //playermodel <name> - FIXME: EXAMPLE NEEDED
2377 //playerskin <name> - FIXME: EXAMPLE NEEDED
2378 //field definitions:
2379 .string playermodel; // name of player model sent by client
2380 .string playerskin; // name of player skin sent by client
2381 //description:
2382 //these client properties are used by Nexuiz.
2383
2384 //NXQ_GFX_LETTERBOX
2385 //idea: nxQuake
2386 //darkplaces implementation: LordHavoc
2387 //description:
2388 //shows that the engine supports the "r_letterbox" console variable, set to values in the range 0-100 this restricts the view vertically (and turns off sbar and crosshair), value is a 0-100 percentage of how much to constrict the view, <=0 = normal view height, 25 = 75% of normal view height, 50 = 50%, 75 = 25%, >=100 = no view
2389
2390 //PRYDON_CLIENTCURSOR
2391 //idea: FrikaC
2392 //darkplaces implementation: LordHavoc
2393 //effects bit:
2394 float EF_SELECTABLE = 16384; // allows cursor to highlight entity (brighten)
2395 //field definitions:
2396 .float cursor_active; // true if cl_prydoncursor mode is on
2397 .vector cursor_screen; // screen position of cursor as -1 to +1 in _x and _y (_z unused)
2398 .vector cursor_trace_start; // position of camera
2399 .vector cursor_trace_endpos; // position of cursor in world (as traced from camera)
2400 .entity cursor_trace_ent; // entity the cursor is pointing at (server forces this to world if the entity is currently free at time of receipt)
2401 //cvar definitions:
2402 //cl_prydoncursor (0/1+, default 0, 1 and above use cursors named gfx/prydoncursor%03i.lmp - or .tga and such if DP_GFX_EXTERNALTEXTURES is implemented)
2403 //description:
2404 //shows that the engine supports the cl_prydoncursor cvar, this puts a clientside mouse pointer on the screen and feeds input to the server for the QuakeC to use as it sees fit.
2405 //the mouse pointer triggers button4 if cursor is at left edge of screen, button5 if at right edge of screen, button6 if at top edge of screen, button7 if at bottom edge of screen.
2406 //the clientside trace skips transparent entities (except those marked EF_SELECTABLE).
2407 //the selected entity highlights only if EF_SELECTABLE is set, a typical selection method would be doubling the brightness of the entity by some means (such as colormod[] *= 2).
2408 //intended to be used by Prydon Gate.
2409
2410 //TENEBRAE_GFX_DLIGHTS
2411 //idea: Tenebrae
2412 //darkplaces implementation: LordHavoc
2413 //fields:
2414 .float light_lev; // radius (does not affect brightness), typical value 350
2415 .vector color; // color (does not affect radius), typical value '1 1 1' (bright white), can be up to '255 255 255' (nuclear blast)
2416 .float style; // light style (like normal light entities, flickering torches or switchable, etc)
2417 .float pflags; // flags (see PFLAGS_ constants)
2418 .vector angles; // orientation of the light
2419 .float skin; // cubemap filter number, can be 1-255 (0 is assumed to be none, and tenebrae only allows 16-255), this selects a projective light filter, a value of 1 loads cubemaps/1posx.tga and cubemaps/1negx.tga and posy, negy, posz, and negz, similar to skybox but some sides need to be rotated or flipped
2420 //constants:
2421 float PFLAGS_NOSHADOW = 1; // light does not cast shadows
2422 float PFLAGS_CORONA = 2; // light has a corona flare
2423 float PFLAGS_FULLDYNAMIC = 128; // light enable (without this set no light is produced!)
2424 //description:
2425 //more powerful dynamic light settings
2426 //warning: it is best not to use cubemaps on a light entity that has a model, as using a skin number that a model does not have will cause issues in glquake, and produce warnings in darkplaces (use developer 1 to see them)
2427 //changes compared to tenebrae (because they're too 'leet' for standards):
2428 //note: networking should send entities with PFLAGS_FULLDYNAMIC set even if they have no model (lights in general do not have a model, nor should they)
2429 //EF_FULLDYNAMIC effects flag replaced by PFLAGS_FULLDYNAMIC flag (EF_FULLDYNAMIC conflicts with EF_NODRAW)
2430
2431 //TW_SV_STEPCONTROL
2432 //idea: Transfusion
2433 //darkplaces implementation: LordHavoc
2434 //cvars:
2435 //sv_jumpstep (0/1, default 1)
2436 //sv_stepheight (default 18)
2437 //description:
2438 //sv_jumpstep allows stepping up onto stairs while airborn, sv_stepheight controls how high a single step can be.
2439
2440 //FTE_QC_CHECKPVS
2441 //idea: Urre
2442 //darkplaces implementation: divVerent
2443 //builtin definitions:
2444 float checkpvs(vector viewpos, entity viewee) = #240;
2445 //description:
2446 //returns true if viewee can be seen from viewpos according to PVS data
2447
2448 //FTE_STRINGS
2449 //idea: many
2450 //darkplaces implementation: KrimZon
2451 //builtin definitions:
2452 float(string str, string sub, float startpos) strstrofs = #221; // returns the offset into a string of the matching text, or -1 if not found, case sensitive
2453 float(string str, float ofs) str2chr = #222; // returns the character at the specified offset as an integer, or 0 if an invalid index, or byte value - 256 if the engine supports UTF8 and the byte is part of an extended character
2454 string(float c, ...) chr2str = #223; // returns a string representing the character given, if the engine supports UTF8 this may be a multi-byte sequence (length may be more than 1) for characters over 127.
2455 string(float ccase, float calpha, float cnum, string s, ...) strconv = #224; // reformat a string with special color characters in the font, DO NOT USE THIS ON UTF8 ENGINES (if you are lucky they will emit ^4 and such color codes instead), the parameter values are 0=same/1=lower/2=upper for ccase, 0=same/1=white/2=red/5=alternate/6=alternate-alternate for redalpha, 0=same/1=white/2=red/3=redspecial/4=whitespecial/5=alternate/6=alternate-alternate for rednum.
2456 string(float chars, string s, ...) strpad = #225; // pad string with spaces to a specified length, < 0 = left padding, > 0 = right padding
2457 string(string info, string key, string value, ...) infoadd = #226; // sets or adds a key/value pair to an infostring - note: forbidden characters are \ and "
2458 string(string info, string key) infoget = #227; // gets a key/value pair in an infostring, returns value or null if not found
2459 float(string s1, string s2) strcmp = #228; // compare two strings
2460 float(string s1, string s2, float len) strncmp = #228; // compare two strings up to the specified number of characters, if their length differs and is within the specified limit the result will be negative, otherwise it is the difference in value of their first non-matching character.
2461 float(string s1, string s2) strcasecmp = #229; // compare two strings with case-insensitive matching, characters a-z are considered equivalent to the matching A-Z character, no other differences, and this does not consider special characters equal even if they look similar
2462 float(string s1, string s2, float len) strncasecmp = #230; // same as strcasecmp but with a length limit, see strncmp
2463 //string(string s, float start, float length) substring = #116; // see note below
2464 //description:
2465 //various string manipulation functions
2466 //note: substring also exists in FRIK_FILE but this extension adds negative start and length as valid cases (see note above), substring is consistent with the php 5.2.0 substr function (not 5.2.3 behavior)
2467 //substring returns a section of a string as a tempstring, if given negative
2468 // start the start is measured back from the end of the string, if given a
2469 // negative length the length is the offset back from the end of the string to
2470 // stop at, rather than being relative to start, if start is negative and
2471 // larger than length it is treated as 0.
2472 // examples of substring:
2473 // substring("blah", -3, 3) returns "lah"
2474 // substring("blah", 3, 3) returns "h"
2475 // substring("blah", -10, 3) returns "bla"
2476 // substring("blah", -10, -3) returns "b"
2477
2478 //DP_CON_BESTWEAPON
2479 //idea: many
2480 //darkplaces implementation: divVerent
2481 //description:
2482 //allows QC to register weapon properties for use by the bestweapon command, for mods that change required ammo count or type for the weapons
2483 //it is done using console commands sent via stuffcmd:
2484 //  register_bestweapon quake
2485 //  register_bestweapon clear
2486 //  register_bestweapon <shortname> <impulse> <itemcode> <activeweaponcode> <ammostat> <ammomin>
2487 //for example, this is what Quake uses:
2488 //  register_bestweapon 1 1 4096 4096 6 0 // STAT_SHELLS is 6
2489 //  register_bestweapon 2 2    1    1 6 1
2490 //  register_bestweapon 3 3    2    2 6 1
2491 //  register_bestweapon 4 4    4    4 7 1 // STAT_NAILS is 7
2492 //  register_bestweapon 5 5    8    8 7 1
2493 //  register_bestweapon 6 6   16   16 8 1 // STAT_ROCKETS is 8
2494 //  register_bestweapon 7 7   32   32 8 1
2495 //  register_bestweapon 8 8   64   64 9 1 // STAT_CELLS is 9
2496 //after each map client initialization, this is reset back to Quake settings. So you should send these data in ClientConnect.
2497 //also, this extension introduces a new "cycleweapon" command to the user.
2498
2499 //DP_QC_STRINGBUFFERS
2500 //idea: ??
2501 //darkplaces implementation: LordHavoc
2502 //functions to manage string buffer objects - that is, arbitrary length string arrays that are handled by the engine
2503 float() buf_create = #460;
2504 void(float bufhandle) buf_del = #461;
2505 float(float bufhandle) buf_getsize = #462;
2506 void(float bufhandle_from, float bufhandle_to) buf_copy = #463;
2507 void(float bufhandle, float sortpower, float backward) buf_sort = #464;
2508 string(float bufhandle, string glue) buf_implode = #465;
2509 string(float bufhandle, float string_index) bufstr_get = #466;
2510 void(float bufhandle, float string_index, string str) bufstr_set = #467;
2511 float(float bufhandle, string str, float order) bufstr_add = #468;
2512 void(float bufhandle, float string_index) bufstr_free = #469;
2513
2514 //DP_QC_STRINGBUFFERS_CVARLIST
2515 //idea: divVerent
2516 //darkplaces implementation: divVerent
2517 //functions to list cvars and store their names into a stringbuffer
2518 //cvars that start with pattern but not with antipattern will be stored into the buffer
2519 void(float bufhandle, string pattern, string antipattern) buf_cvarlist = #517;
2520
2521 //DP_QC_STRINGBUFFERS_EXT_WIP
2522 //idea: VorteX
2523 //darkplaces implementation: VorteX
2524 //constant definitions:
2525 const float MATCH_AUTO = 0;
2526 const float MATCH_WHOLE = 1;
2527 const float MATCH_LEFT = 2;
2528 const float MATCH_RIGHT = 3;
2529 const float MATCH_MIDDLE = 4;
2530 const float MATCH_PATTERN = 5;
2531 //builtin definitions:
2532 float(string filename, float bufhandle) buf_loadfile = #535; // append each line of file as new buffer string, return 1 if succesful
2533 float(float filehandle, float bufhandle, float startpos, float numstrings) buf_writefile = #536; // writes buffer strings as lines, returns 1 if succesful
2534 float(float bufhandle, string match, float matchrule, float startpos, float step) bufstr_find = #537; // returns string index
2535 float(string s, string pattern, float matchrule) matchpattern = #538; // returns 0/1
2536 float(string s, string pattern, float matchrule, float pos) matchpatternofs = #538;
2537 //description:
2538 //provides a set of functions to manipulate with string buffers
2539 //pattern wildcards: * - any character (or no characters), ? - any 1 character
2540 //Warning: This extension is work-in-progress, it may be changed/revamped/removed at any time, dont use it if you dont want any trouble
2541 //wip note: UTF8 is not supported yet
2542
2543 //DP_QC_STRREPLACE
2544 //idea: Sajt
2545 //darkplaces implementation: Sajt
2546 //builtin definitions:
2547 string(string search, string replace, string subject) strreplace = #484;
2548 string(string search, string replace, string subject) strireplace = #485;
2549 //description:
2550 //strreplace replaces all occurrences of 'search' with 'replace' in the string 'subject', and returns the result as a tempstring.
2551 //strireplace does the same but uses case-insensitive matching of the 'search' term
2552
2553 //DP_SV_SHUTDOWN
2554 //idea: divVerent
2555 //darkplaces implementation: divVerent
2556 //A function that gets called just before progs exit. To save persistent data from.
2557 //It is not called on a crash or error.
2558 //void SV_Shutdown();
2559
2560 //EXT_CSQC
2561 // #232 void(float index, float type, .void field) SV_AddStat (EXT_CSQC)
2562 void(float index, float type, ...) addstat = #232;
2563
2564 //ZQ_PAUSE
2565 //idea: ZQuake
2566 //darkplaces implementation: GreEn`mArine
2567 //builtin definitions:
2568 void(float pause) setpause = #531;
2569 //function definitions:
2570 //void(float elapsedtime) SV_PausedTic;
2571 //description:
2572 //during pause the world is not updated (time does not advance), SV_PausedTic is the only function you can be sure will be called at regular intervals during the pause, elapsedtime is the current system time in seconds since the pause started (not affected by slowmo or anything else).
2573 //
2574 //calling setpause(0) will end a pause immediately.
2575 //
2576 //Note: it is worth considering that network-related functions may be called during the pause (including customizeentityforclient for example), and it is also important to consider the continued use of the KRIMZON_SV_PARSECLIENTCOMMAND extension while paused (chatting players, etc), players may also join/leave during the pause.  In other words, the only things that are not called are think and other time-related functions.
2577
2578 //DP_COVERAGE
2579 //idea: divVerent
2580 //darkplaces implementation: divVerent
2581 //function definitions:
2582 void coverage() = #642;  // Reports a coverage event. The engine counts for each of the calls to this builtin whether it has been called.
2583
2584
2585 // EXPERIMENTAL (not finalized) EXTENSIONS:
2586
2587 //DP_CRYPTO
2588 //idea: divVerent
2589 //darkplaces implementation: divVerent
2590 //field definitions: (SVQC)
2591 .string crypto_keyfp; // fingerprint of CA key the player used to authenticate
2592 .string crypto_mykeyfp; // fingerprint of CA key the server used to authenticate to the player
2593 .string crypto_idfp; // fingerprint of ID used by the player entity, or string_null if not identified
2594 .float crypto_idfp_signed; // set if the player's ID has been signed
2595 .string crypto_encryptmethod; // the string "AES128" if encrypting, and string_null if plaintext
2596 .string crypto_signmethod; // the string "HMAC-SHA256" if signing, and string_null if plaintext
2597 // there is no field crypto_myidfp, as that info contains no additional information the QC may have a use for
2598 //builtin definitions: (SVQC)
2599 float(string url, float id, string content_type, string delim, float buf, float keyid) crypto_uri_postbuf = #513;
2600 //description:
2601 //use -1 as buffer handle to justs end delim as postdata
2602
2603 //DP_USERMOVETYPES
2604 //idea: divVerent
2605 //darkplaces implementation: Mario
2606 //movetype definitions:
2607 float MOVETYPE_USER_FIRST = 128;
2608 float MOVETYPE_USER_LAST = 191;
2609 //description:
2610 //user defined movetypes can be added between the start and end points, without producing unknown movetype warnings