11 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 FTEQCC dialect of QuakeC, so only this dialect will be described (as well as some common extensions among Quake engines).
15 To see what QuakeC looks like, here is a piece of example code:
18 // needed declarations:
19 float vlen(vector v) = #12;
20 entity nextent(entity e) = #47;
24 entity findchain(.string fld, string match)
29 for(e = world; (e = nextent(e)); ++e)
42 entity findnearestspawn(vector v)
46 for(e = findchain(classname, "info_player_deathmatch"); e; e = e.chain)
49 else if(vlen(e.origin - v) < vlen(nearest.origin - v))
54 *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
58 Here is a forum on Inside3D where you can read more about QuakeC and ask questions:
59 * QuakeC Forum on Inside3D: http://forums.inside3d.com/viewforum.php?f=2
60 * QC Tutorial for Absolute Beginners: http://forums.inside3d.com/viewtopic.php?t=1286
62 For available functions in QuakeC, look in the following places:
63 * The Quakery: http://quakery.quakedev.com/qwiki/index.php/List_of_builtin_functions
64 * 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
71 To declare a variable, the syntax is the same as in C:
77 However, variables cannot be initialized in their declaration for historical reasons, and trying to do so would define a constant.
79 Whenever a variable declaration could be interpreted as something else by the compiler, the _var_ keyword helps disambiguating. For example,
82 float(float a, float b) myfunc;
85 is an old-style function declaration, while
88 var float(float a, float b) myfunc;
91 declares a variable of function type. An alternate and often more readable way to disambiguate variable declarations is using a _typedef_, like so:
94 typedef float(float, float) myfunc_t;
100 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%%.
101 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.
103 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.
107 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_. FTEQCC also adds _arrays_, although these are slow and a bit buggy. Note that there are no pointers!
111 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.
113 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.
115 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_.
119 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.
121 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. Note however that dividing a vector by a float is NOT supported, one has to use _vector * (1 / float)_ instead. Multiplying two vectors yields their dot product of type float.
123 Common functions to be used on vectors are _vlen_ (vector length), _normalize_ (vector divided by its length, i.e. a unit vector).
125 Vector literals are written like '1 0 0'.
127 **COMPILER BUG:** Always use _vector = vector * float_ instead of _vector *= float_, as the latter creates incorrect code!
131 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:
133 * *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_.
135 * *strcat* concatenates 2 to 8 strings together, as in:
136 <pre><code class="c">
137 strcat("a", "b", "c")=="abc";
140 * *strstrofs(haystack, needle, offset)* searches for an occurrence of one string in another, as in:
141 <pre><code class="c">
142 strstrofs("haystack", "ac", 0)==5;
145 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.
147 * *substring(string, startpos, length)* returns part of a string. The offset is _0_-based here, too.
149 Note that there are different kinds of _strings_, regarding memory management:
150 * *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.
152 * *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:
153 ** To allocate a string, do for example:
154 <pre><code class="c">
155 myglobal = strzone(strcat("hello ", "world"));
157 ** To free the string when it is no longer needed, do:
158 <pre><code class="c">
162 * *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.
164 * *Constant strings:* A string literal like _"foo"_ gets permanent storage assigned by the compiler. There is no need to _strzone_ such strings.
166 * *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:
167 ** Assigning to a global string variable:
172 myglobal = strzone(...);
174 ** Freeing the global string variable:
179 myglobal = string_null;
181 ** Checking if a global string value has been set:
187 string has not yet been set;
193 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:
199 and then all objects _e_ get a field that can be accessed like in _e.myfield_.
201 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).
203 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_).
207 A reference to such a field can be stored too, in a field variable. It is declared and used like
211 // and in some function:
212 var .float myfieldvar;
213 myfieldvar = myfield;
215 </pre>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.
219 Functions work just like in C:
221 float sum3(float a, float b, float c)
226 However, the syntax to declare function pointers is simplified:
228 typedef float(float, float, float) op3func_t;
229 var float(float a, float b, float c) f;
233 print(ftos(g(1, 2, 3)), "\n"); // prints 6
236 Also note that the _var_ keyword is used again to disambiguate from a global function declaration.
238 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):
241 float(float a, float b) sum2 = {
246 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:
248 string strcat(string a, string b, ...) = #115;
253 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.
257 As the QuakeC virtual machine provides no pointers or similar ways to handle arrays, array support is added by FTEQCC and very limited. Arrays can only be global, must have a fixed size (not dynamically allocated), and are a bit buggy and slow. Almost as great as in FORTRAN, except they can't be multidimensional either!
259 You declare arrays like in C:
261 #define MAX_ASSASSINS 16
262 entity assassins[MAX_ASSASSINS];
263 #define BTREE_MAX_CHILDREN 5
264 .entity btree_child[BTREE_MAX_CHILDREN];
265 #define MAX_FLOATFIELDS 3
266 var .float myfloatfields[MAX_FLOATFIELDS];
268 The former is a global array of entities and can be used the usual way:
270 assassins[self.assassin_index] = self;
272 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:
274 for(i = 0; i < BTREE_MAX_CHILDREN; ++i)
275 self.(btree_child[i]) = world;
277 Note that this works:
279 var .entity indexfield;
280 indexfield = btree_child[i];
281 self.indexfield = world;
283 The latter one is a global array of (assignable) entity field variables, and looks very similar:
285 myfloatfields[2] = health;
286 self.(myfloatfields[2]) = 0;
287 // equivalent to self.health = 0;
289 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.
291 h1. Peculiar language constructs
293 This section deals with language constructs in FTEQCC that are not similar to anything in other languages.
297 There is a second way to do a negated _if_:
302 It compiles to slightly more efficient code than
307 and has the notable difference that
312 will not execute (as _""_ counts as true in an _if_ expression), but
317 will execute (as both _""_ and _string_null_ is false when boolean operators are used on it).
322 Some patterns in code that are often encountered in Xonotic are listed here, in no particular order.
326 The usual way to handle classes in Quake is using _fields_, function pointers and the special property _classname_.
328 But first, let's look at how the engine creates entities when the map is loaded.
330 Assume you have the following declarations in your code:
337 and the engine encounters the entity
340 "classname" "func_bobbing"
345 then it will, during loading the map, behave as if the following QuakeC code was executed:
348 self.classname = "func_bobbing";
350 self.origin = '0 32 -64';
351 spawnfunc_func_bobbing();
354 * 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_.
355 * 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.
356 * Spawn functions always have the _spawnfunc__ name prefix and take no arguments.
357 * The _string_ field _classname_ always contains the name of the entity class when it was created by the engine.
358 * 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.
360 Methods are represented as fields of function type:
364 and are assigned to the function to be called in the spawn function, like:
366 void func_bobbing_think()
371 void spawnfunc_func_bobbing()
373 // ... even more stuff ...
374 self.think = func_bobbing_think;
377 To call a method of the same object, you would use
381 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:
391 A very common entry point to QuakeC functions are so-called think functions.
393 They use the following declarations:
398 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:
400 void func_awesome_think()
402 bprint("I am awesome!\n");
403 self.nextthink = time + 2;
406 void spawnfunc_func_awesome()
409 self.think = func_awesome_think;
410 self.nextthink = time + 2;
415 One common way to loop through entities is the find loop. It works by calling a built-in function like
417 entity find(entity start, .string field, string match) = #18;
419 repeatedly. This function is defined as follows:
421 * if _start_ is _world_, the first entity _e_ with _e.field==match_ is returned
422 * otherwise, the entity _e_ **after** _start_ in the entity order with _e.field==match_ is returned
423 * if no such entity exists, _world_ is returned
425 It can be used to enumerate all entities of a given type, for example _"info_player_deathmatch"_:
428 for(e = world; (e = find(e, classname, "info_player_deathmatch")); )
429 print("Spawn point found at ", vtos(e.origin), "\n");
431 There are many other functions that can be used in find loops, for example _findfloat_, _findflags_, _findentity_.
433 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.
437 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.
439 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_.
441 A loop like the following could be used with these:
444 for(e = findchain(classname, "info_player_deathmatch"); e; e = e.chain)
445 print("Spawn point found at ", vtos(e.origin), "\n");
447 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.
451 Error handling is virtually non-existent in QuakeC code. There is no way to throw and handle exceptions.
453 However, built-in functions like _fopen_ return _-1_ on error.
455 To report an error condition, the following means are open to you:
456 * 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!).
457 * Use the _error_ function to abort the program code and report a fatal error with a backtrace showing how it came to it.
458 * 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_!
460 h2. target and targetname
462 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.
464 To QuakeC, these are just strings - to actually use the connection, one would use a find loop:
468 for(self = world; (self = find(self, targetname, oldself.target)); )
473 h2. the enemy field and its friends
475 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.
477 For this, a common pattern is using the pre-defined _enemy_ field to store the target of an entity.
479 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:
481 void teleport_findtarget()
484 self.enemy = find(world, targetname, self.target);
486 // some error handling...
490 void spawnfunc_trigger_teleport()
493 InitializeEntity(self, teleport_findtarget, INITPRIO_FINDTARGET);
497 _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).
501 With default compile options (i.e. if the option _-flo_ is not passed to the compiler), boolean expressions are evaluated fully. This means that in
503 if(!flag && SomeComplexFunction(self))
506 _SomeCompexFunction_ is always evaluated, even if _flag_ is true. To avoid this, one can use:
509 if(SomeComplexFunction(self))
515 h1. Pitfalls and compiler bugs
517 h2. complex operators
519 Do not count on the modifying and reading operators like _+=_ or _++_ to always work. Using them in simple cases like:
522 for(i = 0; i < n; ++i)
525 is generally safe, but complex constructs like:
527 self.enemy.frags += self.value--;
529 are doomed. Instead, split up such expressions into simpler steps:
531 self.enemy.frags = self.enemy.frags + self.value;
534 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.
536 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.
538 h2. functions VS. arrays
540 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:
542 print(ftos(floatarray[i]), " --> ", stringarray[i], anotherstringarray[i], "\n");
544 as the array dereferencings and the _ftos_ return value are likely to overwrite each other. Instead, simplify it:
551 s2 = anotherstringarray[i];
552 print(ftos(f), " --> ", s, s2, "\n");
555 h2. vectoangles does not match makevectors
557 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.
559 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.
563 The server-side code calls the following entry points of the QuakeC code:
565 * *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!
566 * *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.
567 * *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.
568 * *void ClientKill()*: called when the player uses the "kill" console command to suicide.
569 * *void RestoreGame()*: called directly after loading a save game. Useful to, for example, load the databases from disk again.
570 * *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.
571 * *void PutClientInServer()*: called when the client requests to spawn. Typically puts the player somewhere on the map and lets him play.
572 * *.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.
573 * *void URI_Get_Callback(...)*:
574 * *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.
575 * *void SV_OnEntityNoSpawnFunction()*: called when there is no matching spawn function for an entity. Just ignore this...
576 * *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.
577 * *void SV_OnEntityPostSpawnFunction*: called ONLY after its spawn function or SV_OnEntityNoSpawnFunction was called, and skipped if the entity got removed by either.
578 * *void SetNewParms()*:
579 * *void SetChangeParms()*:
580 * *.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.
581 * *.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).
582 * *.void contentstransition()*:
583 * *.void think()*: described above, basically a timer function.
584 * *.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.
585 * *.void movetypesteplandevent()*: called when a player hits the floor.
586 * *.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.
587 * *.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.
588 * *void StartFrame()*: called at the beginning of each server frame, before anything else is done.
589 * *void EndFrame()*: called at the end of each server frame, just before waiting until the next frame is due.
590 * *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.
591 * *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.
projects / xonotic / xonotic.wiki.git / blob