QuakeC

QuakeC is a very simplified dialect of the well-known C programming language, as used by Quake. Nexuiz uses the FTEQCC dialect of QuakeC, so only this one will be described (as well as some common extensions among Quake engines).

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!

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.

As float has 23 bits of mantissa, it can also be used to safely represent integers in the range from -8388608 to 8388608. 8388609 is the first integer float can not represent.

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.

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.

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.

Common functions to be used on vectors are vlen (vector length), normalize (vector divided by its length, i.e. a unit vector).

Vector literals are written like '1 0 0'.

COMPILER BUG: always use vector = vector * float instead of vector *= float, as the latter creates incorrect code.

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:

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.

strcat concatenates 2 to 8 strings together, as in strcat(“a”, “b”, “c”) == “abc”

strstrofs(haystack, needle, offset) searches for an occurence of one string in another, as in strstrofs(“haystack”, “ac”, 0) == 5. The offset defines from which starting position to search, and the return value is -1 if no match is found.

substring(string, startpos, length) returns part of a string.

Note that there are different kinds of strings, regarding memory management:

• 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.
• 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:
  • To allocate a string, do for example myglobal = strzone(strcat(“hello ”, “world”));
  • To free the string when it is no longer needed, do: strunzone(myglobal);
• 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.
• Constant strings. A string literal like “foo” gets permanent storage assigned by the compiler. There is no need to strzone such strings.
• 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 the ! operator, the string ”” counts as FALSE too). As this is a useful property, Nexuiz code declares such a string variable of the name string_null. That means that the following patterns are commonly used for allocating strings:
  • Assigning to a global string variable: if(myglobal) strunzone(myglobal); myglobal = strzone(...);
  • Freeing the global string variable: if(myglobal) strunzone(myglobal); myglobal = string_null;
  • Checking if a global string value has been set: if(myglobal) { value has been set; } else { string has not yet been set; }

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:

.float myfield;

and then all objects e get a field that can be accessed like in e.myfield.

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.

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).

A reference to such a field can be stored too, in a field variable. It is declared and used like

var .float myfieldvar; myfieldvar = myfield; e.myfieldvar = 42;

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.

Functions and work just like in C:

float sum3(float a, float b, float c)
{
  return a + b + c;
}

However, the syntax to declare function pointers is simplified:

typedef float(float, float, float) op3func_t;
float(float a, float b, float c) f;
op3func_t g;
f = sum3;
g = f;
print(ftos(g(1, 2, 3)), "\n"); // prints 6

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 Nexuiz code in a few places):

float(float a, float b) sum2 = {
  return a + b;
}