Update Programming Tips
[xonotic/xonotic.wiki.git] / Introduction-to-QuakeC.md
1 QuakeC
2 ======
3
4 Article TODO
5 ------------
6
7 -   expand explanations
8
9 About QuakeC
10 ------------
11
12 QuakeC is a very simplified dialect of the well-known C programming language, and is used by the Quake I engine and its derivatives. Xonotic uses the GMQCC dialect of QuakeC, so only this dialect will be described (as well as some common extensions among Quake engines).
13
14 Example code
15 ------------
16
17 To see what QuakeC looks like, here is a piece of example code:
18
19 ```c
20 // needed declarations:
21 float vlen(vector v) = #12;
22 entity nextent(entity e) = #47;
23 .string classname;
24 .vector origin;
25 // ...
26 entity findchain(.string fld, string match)
27 {
28     entity first, prev;
29     first = prev = world;
30     for(entity e = world; (e = nextent(e)); e++) {
31         if (e.fld == match) {
32             e.chain = world;
33             if (prev) {
34                 prev.chain = e;
35             } else {
36                 first = e;
37             }
38             prev = e;
39         }
40     }
41     return first;
42 }
43 // ...
44 entity findnearestspawn(vector v)
45 {
46     entity nearest;
47     for (entity e = findchain(classname, "info_player_deathmatch"); e; e = e.chain) {
48         if (!nearest) {
49             nearest = e;
50         } else if(vlen(e.origin - v) < vlen(nearest.origin - v)) {
51             nearest = e;
52         }
53     }
54     return nearest;
55 }
56 ```
57
58 **Note:** *findchain* is implemented in QuakeC for demonstration purposes only so one can see how to build a linked list, as this function is already built in to the engine and can be used directly
59
60 Other resources
61 ---------------
62
63 Here is a forum on Inside3D where you can read more about QuakeC and ask questions:
64 -   QuakeC Forum on Inside3D: http://forums.inside3d.com/viewforum.php?f=2
65 -   QC Tutorial for Absolute Beginners: http://forums.inside3d.com/viewtopic.php?t=1286
66
67 For available functions in QuakeC, look in the following places:
68 -   The Quakery: http://quakery.quakedev.com/qwiki/index.php/List_of_builtin_functions
69 -   Xonotic source: [builtins.qh](http://git.xonotic.org/?p=xonotic/xonotic-data.pk3dir.git;a=blob_plain;f=qcsrc/server/builtins.qh;hb=HEAD) for Quake functions, [extensions.qh](http://git.xonotic.org/?p=xonotic/xonotic-data.pk3dir.git;a=blob_plain;f=qcsrc/server/extensions.qh;hb=HEAD) for DarkPlaces extensions
70
71 Variables
72 =========
73
74 Declaring
75 ---------
76
77 To declare a variable, the syntax is the same as in C:
78
79 ```c
80 float i;
81 ```
82
83 Whenever a variable declaration could be interpreted as something else by the compiler, the *var* keyword helps disambiguating. For example,
84
85 ```c
86 float(float a, float b) myfunc;
87 ```
88
89 is an old-style function declaration, while
90
91 ```c
92 var float(float a, float b) myfunc;
93 ```
94
95 declares a variable of function type. An alternate and often more readable way to disambiguate variable declarations is using a *typedef*, like so:
96
97 ```c
98 typedef float(float, float) myfunc_t;
99 myfunc_t myfunc;
100 ```
101
102 Scope
103 -----
104
105 A variable declared in the global scope has global scope, and is visible starting from its declaration to the end of the code. The order the code is read in by the compiler is defined in the file %progs.src%.
106 A variable declared inside a function has block scope, and is visible starting from its declaration to the end of the smallest block that contains its declaration.
107
108 Some variables are declared in [sys.qh](http://git.xonotic.org/?p=xonotic/xonotic-data.pk3dir.git;a=blob_plain;f=qcsrc/server/sys.qh;hb=HEAD). Their declarations or names should never be changed, as they have to match the order and names of the variables in the file file [progdefs.h](http://svn.icculus.org/twilight/trunk/darkplaces/progdefs.h?view=markup) of the engine exactly, or the code won’t load. The special markers *end\_sys\_globals* and *end\_sys\_fields* are placed to denote the end of this shared declaration section.
109
110 Types
111 =====
112
113 Quake only knows four elementary data types: the basic types `float`, `vector`, `string`, and the object type `entity`. Also, there is a very special type of types, `fields`, and of course `functions`. GMQCC also adds `arrays`, although these are slow. Note that there are no pointers!
114
115 There are also `int` and `bool` typedefs, but no guarantees are made on the range of values as they are currently not supported by GMQCC.
116
117 float
118 -----
119
120 This is the basic numeric type in QuakeC. It represents the standard 32bit floating point type as known from C. It has 23 bits of mantissa, 8 bits of exponent, and one sign bit. The numeric range goes from about `1.175e-38` to about `3.403e+38`, and the number of significant decimal digits is about six.
121
122 As float has 23 bits of mantissa, it can also be used to safely represent integers in the range from `–16777216` to `16777216`. `16777217` is the first integer *float* can not represent.
123
124 Common functions for `float` are especially **ceil**, **floor** (working just like in C, rounding up/down to the next integer), and **random**, which yields a random number `r` with `0 <= r < 1`.
125
126 vector
127 ------
128
129 This type is basically three floats together. By declaring a `vector v`, you also create three floats `v_x`, `v_y` and `v_z` (note the underscore) that contain the components of the vector. GMQCC also accepts dot notation to access these components: `v.x`, `v.y` and `v.z`
130
131 **COMPILER BUG:** Always use `entity.vector_x = float` instead of `entity.vector.x = float`, as the latter creates incorrect code! Reading from vectors is fine, however.
132
133 Vectors can be used with the usual mathematical operators in the usual way used in mathematics. For example, `vector + vector` simply returns the sum of the vectors, and `vector * float` scales the vector by the given factor. Multiplying two vectors yields their dot product of type float.
134
135 Common functions to be used on vectors are `vlen` (vector length), `normalize` (vector divided by its length, i.e. a unit vector).
136
137 Vector literals are written like `'1 0 0'`.
138
139 string
140 ------
141
142 A *string* in QuakeC is an immutable reference to a null-terminated character string stored in the engine. It is not possible to change a character in a string, but there are various functions to create new strings:
143 -  **ftos** and **vtos** convert *floats* and *vectors* to strings. Their inverses are, of course, **stof** and **stov**, which parse a *string* into a *float* or a *vector*.
144
145 -   **strcat** concatenates 2 to 8 strings together, as in:
146     ```c
147     strcat("a", "b", "c") == "abc";
148     ```
149
150 -   **strstrofs(haystack, needle, offset)** searches for an occurrence of one string in another, as in:
151     ```c
152     strstrofs("haystack", "ac", 0) == 5;
153     ```
154
155 The offset defines from which starting position to search, and the return value is `–1` if no match is found. The offset returned is *0*-based, and to search in the whole string, a start offset of *0* would be used.
156
157 -   **substring(string, startpos, length)** returns part of a string. The offset is *0*-based here, too.
158
159 Note that there are different kinds of *strings*, regarding memory management:
160
161 -   **Temporary strings** are strings returned by built-in string handling functions such as **substring**, **strcat**. They last only for the duration of the function call from the engine. That means it is safe to return a temporary string in a function you wrote, but not to store them in global variables or objects as their storage will be overwritten soon.
162 -   **Allocated strings** are strings that are explicitly allocated. They are returned by *strzone* and persist until they are freed (using **strunzone**). Note that **strzone** does not change the string given as a parameter, but returns the newly allocated string and keeps the passed temporary string the same way! That means:
163     +   To allocate a string, do for example:
164         ```c
165         myglobal = strzone(strcat("hello ", "world"));
166         ```
167
168     +   To free the string when it is no longer needed, do:
169         ```c
170         strunzone(myglobal);
171         ```
172
173 -   **Engine-owned strings**, such as *netname*. These should be treated just like temporary strings: if you want to keep them in your own variables, *strzone* them.
174 -   **Constant strings:** A string literal like *“foo”* gets permanent storage assigned by the compiler. There is no need to *strzone* such strings.
175 -   **The null string:** A global uninitialized *string* variable has the special property that is is usually treated like the constant, empty, string *“”* (so using it does not constitute an error), but it is the only string that evaluates to FALSE in an if expression (but not in the ! operator~~ in boolean context, the string “” counts as FALSE too). As this is a useful property, Xonotic code declares such a string variable of the name *string\_null*. That means that the following patterns are commonly used for allocating strings:
176     +   Assigning to a global string variable:
177         ```c
178         if (myglobal) {
179             strunzone(myglobal);
180         }
181
182         myglobal = strzone(...);
183         ```
184
185     +   Freeing the global string variable:
186         ```c
187         if (myglobal) {
188             strunzone(myglobal);
189         }
190
191         myglobal = string_null;
192         ```
193
194     +   Checking if a global string value has been set:
195         ```c
196         if (myglobal) {
197             value has been set;
198         } else {
199             string has not yet been set;
200         }
201         ```
202
203 entity
204 ------
205
206 The main object type in QuakeC is *entity*, a reference to an engine internal object. An *entity* can be imagined as a huge struct, containing many *fields*. This is the only object type in the language. However, *fields* can be added to the *entity* type by the following syntax:
207
208 ```c
209 .float myfield;
210 ```
211
212 and then all objects *e* get a field that can be accessed like in *e.myfield*.
213
214 The special entity *world* also doubles as the *null* reference. It can not be written to other than in the *spawnfunc\_worldspawn* function that is run when the map is loaded, and is the only entity value that counts as *false* in an *if* expression. Thus, functions that return *entities* tend to return *world* to indicate failure (e.g. *find* returns *world* to indicate no more entity can be found).
215
216 If a field has not been set, it gets the usual zero value of the type when the object is created (i.e. *0* for *float*, *string\_null* for *string*, *’0 0 0’* for *vector*, and *world* for *entity*).
217
218 fields
219 ------
220
221 A reference to such a field can be stored too, in a field variable. It is declared and used like
222
223 ```c
224 .float myfield;
225 // ...
226 // and in some function:
227 var .float myfieldvar;
228 myfieldvar = myfield;
229 e.myfieldvar = 42;
230 ```
231
232 Field variables can be used as function parameters too - in that case you leave the *var* keyword out, as it is not needed for disambiguation.
233
234 functions
235 ---------
236
237 Functions work just like in C:
238
239 ```c
240 float sum3(float a, float b, float c)
241 {
242     return a + b + c;
243 }
244 ```
245
246 However, the syntax to declare function pointers is simplified:
247
248 ```c
249 typedef float(float, float, float) op3func_t;
250 var float(float a, float b, float c) f;
251 op3func_t g;
252 f = sum3;
253 g = f;
254 print(ftos(g(1, 2, 3)), "\n"); // prints 6
255 ```
256
257 Also note that the *var* keyword is used again to disambiguate from a global function declaration.
258
259 In original QuakeC by iD Software, this simplified function pointer syntax also was the only way to define functions (you may still encounter this in Xonotic’s code in a few places):
260
261 ```c
262 float(float a, float b) sum2 = {
263     return a + b;
264 }
265 ```
266
267 A special kind of functions are the built-in functions, which are defined by the engine. These are imported using so-called built-in numbers, with a syntax like:
268
269 ```c
270 string strcat(string a, string b, ...) = #115;
271 ```
272
273 void
274 ----
275
276 Just like in C, the *void* type is a special placeholder type to declare that a function returns nothing. However, unlike in C, it is possible to declare variables of this type, although the only purpose of this is to declare a variable name without allocating space for it. The only occasion where this is used is the special *end\_sys\_globals* and *end\_sys\_fields* marker variables.
277
278 arrays
279 ------
280
281 As the QuakeC virtual machine provides no pointers or similar ways to handle arrays, array support is added by GMQCC and very limited. Arrays can only be global, must have a fixed size (not dynamically allocated), and are a bit slow. Almost as great as in FORTRAN, except they can’t be multidimensional either!
282
283 You declare arrays like in C:
284
285 ```c
286 #define MAX_ASSASSINS 16
287 entity assassins[MAX_ASSASSINS];
288 #define BTREE_MAX_CHILDREN 5
289 .entity btree_child[BTREE_MAX_CHILDREN];
290 #define MAX_FLOATFIELDS 3
291 var .float myfloatfields[MAX_FLOATFIELDS];
292 ```
293
294 The former is a global array of entities and can be used the usual way:
295
296 ```c
297 assassins[self.assassin_index] = self;
298 ```
299
300 The middle one is a global array of (allocated and constant) entity fields and **not** a field of array type (which does not exist), so its usage looks a bit strange:
301
302 ```c
303 for (int i = 0; i < BTREE_MAX_CHILDREN; i++)
304     self.(btree_child[i]) = world;
305 ```
306
307 Note that this works:
308
309 ```c
310 var .entity indexfield;
311 indexfield = btree_child[i];
312 self.indexfield = world;
313 ```
314
315 The latter one is a global array of (assignable) entity field variables, and looks very similar:
316
317 ```c
318 myfloatfields[2] = health;
319 self.(myfloatfields[2]) = 0;
320 // equivalent to self.health = 0;
321 ```
322
323 Do not use arrays when you do not need to - using both arrays and function calls in the same expression can get messed up (**COMPILER BUG**), and arrays are slowly emulated using functions `ArrayGet*myfloatfields` and `ArraySet*myfloatfields` the compiler generates that internally do a binary search for the array index.
324
325 Peculiar language constructs
326 ============================
327
328 This section deals with language constructs in QuakeC that are not similar to anything in other languages.
329
330 if not (deprecated)
331 -------------------
332
333 There is a second way to do a negated *if*:
334
335 ```c
336 if not(expression)
337     ...
338 ```
339
340 It compiles to the same code as
341
342 ```c
343 if (!expression)
344     ...
345 ```
346
347 and has the notable difference that
348
349 ```c
350 if not("")
351     ...
352 ```
353
354 will not execute (as *“”* counts as true in an *if* expression), but
355
356 ```c
357 if (!"")
358     ...
359 ```
360
361 will execute (as both `""` and `string_null` is false when boolean operators are used on it).
362
363 Common patterns
364 ===============
365
366 Some patterns in code that are often encountered in Xonotic are listed here, in no particular order.
367
368 Classes in Quake
369 ----------------
370
371 The usual way to handle classes in Quake is using *fields*, function pointers and the special property *classname*.
372
373 But first, let’s look at how the engine creates entities when the map is loaded.
374
375 Assume you have the following declarations in your code:
376
377 ```c
378 entity self;
379     .string classname;
380     .vector origin;
381     .float height;
382 ```
383
384 and the engine encounters the entity
385
386 ```c
387 {
388     "classname" "func_bobbing"
389     "height" "128"
390     "origin" "0 32 –64"
391 }
392 ```
393
394 then it will, during loading the map, behave as if the following QuakeC code was executed:
395
396 ```c
397 self = spawn();
398 self.classname = "func_bobbing";
399 self.height = 128;
400 self.origin = '0 32 -64';
401 spawnfunc_func_bobbing();
402 ```
403
404 We learn from this:
405 -   The special global *entity* variable *self* is used when “methods” of an object are called, like - in this case - the “constructor” or spawn function `spawnfunc_func_bobbing`.
406 -   Before calling the spawn function, the engine sets the mapper specified fields to the values. String values can be treated by the QC code as if they are constant strings, that means there is no need to **strzone** them.
407 -   Spawn functions always have the *spawnfunc\_* name prefix and take no arguments.
408 -   The *string* field *classname* always contains the name of the entity class when it was created by the engine.
409 -   As the engine uses this pattern when loading maps and this can’t be changed, it makes very much sense to follow this pattern for all entities, even for internal use. Especially making sure *classname* is set to a sensible value is very helpful.
410
411 Methods are represented as fields of function type:
412
413 ```c
414 .void() think;
415 ```
416
417 and are assigned to the function to be called in the spawn function, like:
418
419 ```c
420 void func_bobbing_think()
421 {
422     // lots of stuff
423 }
424 ```
425
426 ```c
427 void spawnfunc_func_bobbing()
428 {
429     // ... even more stuff ...
430     self.think = func_bobbing_think;
431 }
432 ```
433
434 To call a method of the same object, you would use
435
436 ```c
437 self.think();
438 ```
439
440 but to call a method of another object, you first have to set *self* to that other object, but you typically need to restore *self* to its previous value when done:
441
442 ```c
443 entity oldself;
444 // ...
445 oldself = self;
446 self.think();
447 self = oldself;
448 ```
449
450 Think functions
451 ---------------
452
453 A very common entry point to QuakeC functions are so-called think functions.
454
455 They use the following declarations:
456
457 ```c
458 .void() think;
459 .float nextthink;
460 ```
461
462 If *nextthink* is not zero, the object gets an attached timer: as soon as *time* reaches *nextthink*, the *think* method is called with *self* set to the object. Before that, *nextthink* is set to zero. So a typical use is a periodic timer, like this:
463
464 ```c
465 void func_awesome_think()
466 {
467     bprint("I am awesome!");
468     self.nextthink = time + 2;
469 }
470 ```
471
472 ```c
473 void spawnfunc_func_awesome()
474 {
475     // ...
476     self.think = func_awesome_think;
477     self.nextthink = time + 2;
478 }
479 ```
480
481 Find loops
482 ----------
483
484 One common way to loop through entities is the find loop. It works by calling a built-in function like
485
486 ```c
487 entity find(entity start, .string field, string match) = #18;
488 ```
489
490 repeatedly. This function is defined as follows:
491
492 -   if *start* is *world*, the first entity *e* with `e.field==match` is returned
493 -   otherwise, the entity *e* **after** *start* in the entity order with `e.field==match` is returned
494 -   if no such entity exists, *world* is returned
495
496 It can be used to enumerate all entities of a given type, for example `"info_player_deathmatch"`:
497
498 ```c
499 for (entity e = world; (e = find(e, classname, "info_player_deathmatch")); )
500     print("Spawn point found at ", vtos(e.origin), "\n");
501 ```
502
503 There are many other functions that can be used in find loops, for example *findfloat*, *findflags*, *findentity*.
504
505 Note that the function *findradius* is misnamed and is not used as part of a find loop, but instead sets up a linked list of the entities found.
506
507 Linked lists
508 ------------
509
510 An alternate way to loop through a set of entities is a linked list. I assume you are already familiar with the concept, so I’ll skip information about how to manage them.
511
512 It is however noteworthy that some built-in functions create such linked lists using the *entity* field *chain* as list pointer. Some of these functions are the aforementioned *findradius*, and *findchain*, *findchainfloat*, *findchainflags* and *findchainentity*.
513
514 A loop like the following could be used with these:
515
516 ```c
517 for (entity e = findchain(classname, "info_player_deathmatch"); e; e = e.chain)
518         print("Spawn point found at ", vtos(e.origin), "\n");
519 ```
520
521 The main advantage of linked lists however is that you can keep them in memory by using other fields than *chain* for storing their pointers. That way you can avoid having to search all entities over and over again (which is what *find* does internally) when you commonly need to work with the same type of entities.
522
523 Error handling
524 --------------
525
526 Error handling is virtually non-existent in QuakeC code. There is no way to throw and handle exceptions.
527
528 However, built-in functions like *fopen* return `-1` on error.
529 To report an error condition, the following means are open to you:
530 -   Use the *print* function to spam it to the console. Hopefully someone will read that something went wrong. After that, possibly use *remove* to delete the entity that caused the error (but make sure there are no leftover references to it!).
531 -   Use the *error* function to abort the program code and report a fatal error with a backtrace showing how it came to it.
532 -   Use the *objerror* function to abort spawning an entity (i.e. removing it again). This also prints an error message, and the entity that caused the error will not exist in game. Do not forget to *return* from the spawn function directly after calling *objerror*!
533
534 target and targetname
535 ---------------------
536
537 In the map editor, entities can be connected by assigning a name to them in the *target* field of the targeting entity and the *targetname* field of the targeted entity.
538 To QuakeC, these are just strings - to actually use the connection, one would use a find loop:
539
540 ```c
541 entity oldself = self;
542 for (self = world; (self = find(self, targetname, oldself.target)); )
543     self.use();
544 self = oldself;
545 ```
546
547 the enemy field and its friends
548 -------------------------------
549
550 As the find loop for *target* and *targetname* causes the engine to loop through all entities and compare their *targetname* field, it may make sense to do this only once when the map is loaded.
551
552 For this, a common pattern is using the pre-defined *enemy* field to store the target of an entity.
553
554 However, this can’t be done during spawning of the entities yet, as the order in which entities are loaded is defined by the map editor and tends to be random. So instead, one should do that at a later time, for example when the entity is first used, in a think function, or - the preferred way in the Xonotic code base - in an *InitializeEntity* function:
555
556 ```c
557 void teleport_findtarget()
558 {
559     // ...
560     self.enemy = find(world, targetname, self.target);
561     if (!self.enemy)
562         // some error handling...
563     // ...
564 }
565 ```
566
567 ```c
568 void spawnfunc_trigger_teleport()
569 {
570     // ...
571     InitializeEntity(self, teleport_findtarget, INITPRIO_FINDTARGET);
572     // ...
573 }
574 ```
575
576 *InitializeEntity* functions are guaranteed to be executed at the beginning of the next frame, before the *think* functions are run, and are run in an order according to their priorities (the *INITPRIO*\_ constants).
577
578 Tracing
579 -------
580
581 Pitfalls and compiler bugs
582 ==========================
583
584 variable shadowing
585 ------------------
586
587 ```c
588 .float height;
589 void update_height(entity e, float height) {
590     e.height = height;
591 }
592 ```
593 `error: invalid types in assignment: cannot assign .float to float`
594
595 The height *field* overrides the height *parameter*; change the parameter name somehow (`_height`).
596
597 complex operators
598 -----------------
599
600 Do not count on the modifying and reading operators like *+=* or *++* to always work. Using them in simple cases like:
601 ```c
602 a += 42;
603 for (int i = 0; i < n; i++) {
604     ...
605 }
606 ```
607 is generally safe, but complex constructs like:
608 ```c
609 self.enemy.frags += self.value--;
610 ```
611 are doomed. Instead, split up such expressions into simpler steps:
612 ```c
613 self.enemy.frags = self.enemy.frags + self.value;
614 self.value -= 1;
615 ```
616 The compiler warning **RETURN VALUE ALREADY IN USE** is a clear indicator that an expression was too complex for it to deal with it correctly. If you encounter the warning, do make sure you change the code to no longer cause it, as the generated code **will** be incorrect then.
617 Also, do not use the *+=* like operators on *vector*s, as they are known to create incorrect code and only operate on the *x* component of the vector.
618
619 functions VS. arrays
620 --------------------
621
622 Mixing function calls with array dereferencing, or doing more than one array dereferencing in the same expression, is known to create incorrect code. Avoid constructs like:
623
624 ```c
625 print(ftos(floatarray[i]), " --> ", stringarray[i], anotherstringarray[i], "\n");
626 ```
627
628 as the array dereferencings and the *ftos* return value are likely to overwrite each other. Instead, simplify it:
629 ```c
630 float f;
631 string s, s2;
632 // ...
633 f = floatarray[i];
634 s = stringarray[i];
635 s2 = anotherstringarray[i];
636 print(ftos(f), " --> ", s, s2, "\n");
637 ```
638
639 vectoangles does not match makevectors
640 --------------------------------------
641
642 The pitch angle is inverted between these two functions. You have to negate the pitch (i.e. the *x* component of the vector representing the euler angles) to make it fit the other function.
643 As a rule of thumb, *vectoangles* returns angles as stored in the *angles* field (used to rotate entities for display), while *makevectors* expects angles as stored in the *v\_angle* field (used to transmit the direction the player is aiming). There is about just as much good reason in this as there is for 1:1 patch cables. Just deal with it.
644
645 Entry points
646 ============
647
648 The server-side code calls the following entry points of the QuakeC code:
649
650 -   **void ClientDisconnect()**: called when a player leaves the server. Do not forget to *strunzone* all *strings* stored in the player entity here, and do not forget to clear all references to the player!
651 -   **void SV\_Shutdown()**: called when the map changes or the server is quit. A good place to store persistent data like the database of race records.
652 -   **void SV\_ChangeTeam(float newteam)**: called when a player changes his team. Can be used to disallow team changes, or to clear the player’s scores.
653 -   **void ClientKill()**: called when the player uses the ”kill" console command to suicide.
654 -   **void RestoreGame()**: called directly after loading a save game. Useful to, for example, load the databases from disk again.
655 -   **void ClientConnect()**: called as soon as a client has connected, downloaded everything, and is ready to play. This is the typical place to initialize the player entity.
656 -   **void PutClientInServer()**: called when the client requests to spawn. Typically puts the player somewhere on the map and lets him play.
657 -   **.float SendEntity(entity to, float sendflags)**: called when the engine requires a CSQC networked entity to send itself to a client, referenced by *to*. Should write some data to *MSG\_ENTITY*. *FALSE* can be returned to make the entity not send. See *EXT\_CSQC* for information on this.
658 -   **void URI\_Get\_Callback(...)**:
659 -   **void GameCommand(string command)**: called when the “sv\_cmd” console command is used, which is commonly used to add server console commands to the game. It should somehow handle the command, and print results to the server console.
660 -   **void SV\_OnEntityNoSpawnFunction()**: called when there is no matching spawn function for an entity. Just ignore this...
661 -   **void SV\_OnEntityPreSpawnFunction**: 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.
662 -   **void SV\_OnEntityPostSpawnFunction**: called ONLY after its spawn function or SV\_OnEntityNoSpawnFunction was called, and skipped if the entity got removed by either.
663 -   **void SetNewParms()**:
664 -   **void SetChangeParms()**:
665 -   **.float customizeentityforclient()**: called for an entity before it is going to be sent to the player specified by *other*. Useful to change properties of the entity right before sending, e.g. to make an entity appear only to some players, or to make it have a different appearance to different players.
666 -   **.void touch()**: called when two entities touch; the other entity can be found in *other*. It is, of course, called two times (the second time with *self* and *other* reversed).
667 -   **.void contentstransition()**:
668 -   **.void think()**: described above, basically a timer function.
669 -   **.void blocked()**: called when a *MOVETYPE\_PUSH* entity is blocked by another entity. Typically does either nothing, reverse the direction of the door moving, or kills the player who dares to step in the way of the Mighty Crusher Door.
670 -   **.void movetypesteplandevent()**: called when a player hits the floor.
671 -   **.void PlayerPreThink()**: called before a player runs his physics. As a special exception, *frametime* is set to 0 if this is called for a client-side prediction frame, as it still will get called for server frames.
672 -   **.void PlayerPreThink()**: called after a player runs his physics. As a special exception, *frametime* is set to 0 if this is called for a client-side prediction frame, as it still will get called for server frames.
673 -   **void StartFrame()**: called at the beginning of each server frame, before anything else is done.
674 -   **void EndFrame()**: called at the end of each server frame, just before waiting until the next frame is due.
675 -   **void SV\_PlayerPhysics()**: allows to replace the player physics with your own code. The movement the player requests can be found in the *vector* field *movement*, and the currently pressed buttons are found in various fields, whose names are aliased to the *BUTTON*\_ macros.
676 -   **void SV\_ParseClientCommand(string command)**: handles commands sent by the client to the server using “cmd ...”. Unhandled commands can be passed to the built-in function *clientcommand* to execute the normal engine behaviour.
677