fteqcc_manual.txt

                            ====================
                            FTEQCC DOCUMENTATION
                            ====================

Contents by David Walton and Marco Hladik.
Edited and compiled by Marco Hladik.

Last updated: 10th August 2018, 9:21 PM GMT

========
0. INDEX
========

1)  Overview
        1.1) Server-Side QuakeC (SSQC)
        1.2) Client-Side QuakeC (CSQC)
        1.3) Menu QuakeC (MenuQC)
2)  Getting Started
3)  Command-Line
4)  Project Mangement
5)  Other Pre-Processor
6)  Control Statements
7)  Basic Types
        7.1) entity
        7.2) float
        7.3) string
        7.4) int
        7.5) vector
        7.6) __variant
8)  Complex Types
        8.1)  arrays
        8.2)  fields
        8.3)  functions
        8.4)  typedef
        8.5)  enum / enumflags / strongly typed enums
        8.6)  struct
        8.7)  union
        8.8)  class
        8.9)  pointer
        8.10) Accessors
9)  Type Modifiers
        9.1) const / var
        9.2) __unused / noref
        9.3) __used
        9.4) local
        9.5) static / nonstatic
        9.6) nosave
        9.7) inline
        9.8) strip / __ignore
        9.9) shared
        9.10) optional
        9.11) __inout / __in / __out
        9.12) __weak
        9.13) __wrap
        9.14) __accumulate
10) Operators
11) Intrinsics
12) Modelgen Commands
13) Compiler Flags
14) Engine Support

===========
1. Overview
===========

    QuakeC is a language originally created by iD software for use in in the
video game Quake. Vanilla QuakeC is quite a limited language, however with qcc
improvements and engine extensions, its less annoying to write and also much
more capable as a programming language.

Today we're dealing with different types of modules. The original QuakeC only
supported the modification of game-code run on the server. It was not capable
of altering any client-side behaviour. Just send a selection of commands and
hope that the client interprets the stuff properly.


1.1) Server-Side QuakeC (SSQC)
==============================

    This is the classic form of QuakeC, and is the module executed by the server
component. SSQC's reason to exist is so that it can deal with networking. 
It is normally considered authoritive, which is a fancy way of saying that CSQC
isn't to be trusted (if only due to packetloss). 
As such, the SSQC is normally expected to track the state of any entity that has
any impact on the outcome of a game.

In mods designed to run without CSQC, the SSQC generally does a lot more than
just that, however it is also potentially running on a computer on the other
side of the planet, so while you can write your entire game in just the SSQC
module, doing so means that you have no control over the user's actual screen,
and anything that is displayed can be quite laggy which may limit what you can
expect to achieve with SSQC alone.

There are two major variations of SSQC:

[1] NetQuake (NQ):
The original and more common type.

[2] QuakeWorld (QW):
Which was originally meant for deathmatch only. 
It streamlines some things but in the process has a number of omissions that
break singleplayer quake (most qw mods lack any singleplayer/coop logic, with
no support for any monsters).

Thus most engines focus on NQ, even FTEQW!
SSQC tends to be very object orientated. There are comparatively few
non-constant globals as multiple pontential players/etc hinder the use of such
individual globals.


1.2) Client-Side QuakeC (CSQC)
==============================

    This module runs clientside. Each client potentially has its own instance of
CSQC, and thus they'll all end up disagreeing about some part of the game
without the SSQC to provide authoritive information - remember this: 
The SSQC knows best.

CSQC normally has full control over the client's screen (via builtins). It is
normally the CSQC that decides when and where to draw the various hud elements.
The CSQC also has control over the 3d view, and can not only decide where to
draw the 3d view, but it can also change the camera as well as directly control
the entities that are inserted into that view.
However, not every engine supports CSQC, and those that do might have it
disabled for whatever reason.

There are three variations of CSQC:

[1] FTE:
This was the first version of CSQC (if you ignore that CSQC was predated by
menuqc). It is also the one that supports the most extensions since.

[2] DP:
DP's CSQC implementation was an attempt to follow a poorly understood and
incomplete description of FTE's CSQC implementation. As a result, it does
many things in a sub-par way and refuses to improve upon any of it because
doing so might break one of the mods that use it.
Even so, you can still achieve some awesome stuff with it, it just tends to
be more limited than in FTE.

[3] Simple CSQC:
This variation of CSQC is a cut down version of CSQC. It is restricted from
various actions and is unable to query anything about the game beyond the
stats. Its sole purpose is to allow it to draw 2d elements including hud,
scoreboard, and menus. The crc of the csprogs.dat explcitly matches that
of the nq progs.dat, which allows client+server to reuse various builtins
etc, simplifying the implementation further, this also permits the entry
points to be provided by the progs.dat itself although this is more of a
convienience than anything else (it should still run in a seperate VM and
thus have no access to ssqc state).
As an improper subset, it is trivial to create a DP-compatible csprogs that
wraps the Simple CSQC entrypoints, allowing one csprogs to run seamlessly in
FTE+QSS+DP, and hopefully also other engines in the future.

CSQC tends to be more procedural than SSQC.
Generally there is only one player so that info can all be stored in globals
instead of entities (splitscreen may require arrays).


1.3) Menu QuakeC (MenuQC)
=========================

    The mythical MenuQC module is responsible for drawing 2d menus.
It serves many of the CSQC's roles, except that it does not get purged on map
changes and is explicitly designed to remain running even when not connected
to a server.
Becase MenuQC was implemented in DP first combined with FTE's actual attempts
at compatibility, there is only a single standard for MenuQC. However, while
MenuQC is standard, both major supporters have their own extensions, but even
worse is that no two engines have the same names for the same cvar.
Indeed, cvar-hell is why it is generally not recommended for a mod to even try
to support more than one engine. Its much easier to just use the engine's menus
instead.
As such, MenuQC is generally used only for standalone total conversions.

==================
2. Getting Started
==================

    The best way to get started is to find an existing qc-only mod (like
id1qc.zip), extract the qc source files somewhere like c:\quake\mymod\src\*.qc,
shift-right-click the extracted .src file and select open-with and find
fteqccgui.exe.

Then in fteqccgui press F7 to compile, then press F5 to run (you'll be prompted
to locate the exe you want to run as well as you quake directory.
In the engine you can then just load a map.

One common suggestion is to open weapons.qc, find the W_FireRocket function, and
to then change the velocity multiplier for really slow moving rockets, just to
see that you've made a change. There are many many other things you could do
instead, of course. 

Your mod, your choice.

===============
3. Command-Line
===============

    Many commandline arguments are best migrated to pragmas, or set via
fteqccgui's options menu.

[*] -src path
Specifies the directory to start looking in for source files. Mostly redundant.

[*] -srcfile foo.src
Specifies the .src file to start with.

[*] -o output.dat
Explicit output file name.

[*] -O3
Sets optimisations to max. Do not use in addons.

[*] -O2
Sets optimisations to high.

[*] -O0
Turns all optimisations off. You do NOT want this. Optimisations are required in
order to avoid wasting defs.

[*] -std=foo
Reconfigures compiler keywords+flags in order to attempt better compatibility
with the syntax of other QC compilers. There are absolutely no guarentees, nor
should there be much expectations...

[*] -Kfoo / -Kno-foo
Enables the named keyword.
Keywords that are not enabled are still usable with a double-underscore prefix,
so enabling/disabling them is more for compatibility.

[*] -Ffoo / -Fno-foo
Enables disables various compiler flags. There's a number of them, they're not
all useful either, and changing them mid-way through development will generally
result in new bugs in code that was working before. Consult fteqccgui's options
menu for a list.

[*] -Tfoo
Instructs fteqcc to target a specific instruction set and output format.
Common options are: standard, fte, h2, dp, qtest.
You may prefer to use '#pragma target foo' instead.
Using -Th2 also enables some additional keywords in order to act like hcc.
Other targets do not.

[*] -Dvariable[=value]
Defines the named preprocessor macro with the given value.

[*] -Isomepath
Registers an alternative include path, for included files that might otherwise
be considered missing.

[*] -Wall
Enables nearly all warnings.

[*] -Wextra
Enables more warnings than are useful. Many might be unfixable.

[*] -Werror
All warnings will be treated as errors.

[*] -Wno-mundane
Disables a number of warnings that you probably don't care too much about.

[*] -v
Verbose. Can be used multiple times to increase verbosity. Twice will include
autocvar output, which should simplify creation of your mod's default.cfg

[*] --version
Prints out the version of fteqcc and then quits.

[*] -stdout
Runs fteqccgui as if it were fteqcc (ie: compiles and quits without creating any
gui windows). Note that if you want to see the output on windows then you'll
need to pipe the output through some other program.

====================
4. Project Mangement
====================

    All QuakeC starts with a single file - aka the .src. 
This file comes in two forms.

1) Old style:
    First token: treated as equivelent to #output "thetokenhere"
    Other tokens: treated as equivelent to #include "thetokenhere"
    Preprocessor may be used in this file only after the first token.
2) New style:
    First token MUST have a leading #, and is typically #output "filename".
    The rest of the code is treated as a .qc file in its own right, including
    function defs etc.
    Usually the code will be include a series of #includes in order to pull in
    any .qc files you wish to compile.

[*] #merge
#merge "existing.dat" Attempts to imports an existing .dat into the compiler's
state. The imported state will lack any and all type information, so you will
need to re-prototype any variables that you use.
With the use of the __wrap keyword, you can rewrite the imported functions,
otherwise you can add additional symbols into the output.
Do NOT use the same filename for both #merge and #output.

[*] #copyright
Allows you to specify a copyright message. This will be embedded at the start of
the file, and will be displayed in a prompt if anyone tries to use fteqccgui's
decompiler on your mod.
You may wish to include the url of your source repo here.

[*] #include
Pulls in another source file, as if its contents had been embedded in the file
instead of the #include line.

[*] #includelist #endlist
Acts as an #include for each line between the #includelist and #endlist lines.

[*] #pragma includedir "path"
Specifies an alternative path from which to include other files. The path is
relative to the file containing the pragma (if not absolute).

[*] #datafile
Certain modes of operation cause FTEQCC to consider the output .dat files to be
zips (eg with the -Fembedsrc argument).
This argument explicitly includes the specified file within the resulting
.dat/zip.

[*] #pragma sourcefile
This pragma names an additional sourcefile to be compiled at the same time.
Thus if you have a progs.src that contains eg:
    #pragma sourcefile "ssqc.src"
    #pragma sourcefile "CSQC.src"
And then you compile that progs.src, fteqcc[gui] will attempt to compile all
three src files. This is strongly recommended for mods that involve a lot of
debugging of more than one module, and is the only way to get fteqccgui to track
the defs from multiple modules.

[*] #output / #pragma PROGS_DAT
Changes the .dat file that will be written from the current .src file.

[*] #message
Spits out a message to the compilers text output.
Does not otherwise affect anything.

[*] #pragma once
This file will be treated as 0-length if it is included again elsewhere.

[*] #error
Acts as a syntax error with user-defined text.
Useful to verify preprocessor state.

[*] #pragma noref STATE
If STATE is 1, then all following definitions will implicitly use the 'noref'
type modifier, which allows the qcc to silently strip them if they are not
actually referenced nor initialised.
This can be used to silence warnings from *extensions.qc files.

[*] #pragma defaultstatic STATE
Enables/disables the assumption that variables should be static. This can be
override on a per-variable basis with the static or nonstatic modifier.
In programming, it can often pay to 'box' things together, allowing you to
guarentee that only a specific part of your code can interact with something
and thereby reduce the number of outside things that will need to change when
refactoring code later on.
Note that static variables are considered to be invisible to the engine also,
which includes spawn functions and entry points, so use with caution.

[*] #pragma autoproto
If used, this must be used before any variables are defined. This causes fteqcc
to compile your code twice. The first time it will look only at definitions
while skipping over any function bodies allowing them to act as prototypes.
The second time it will compile the functions themselves.
Thus this ensures that any global that is declared later can freely be used in
any expressions or functions. Unfortunately this does not also apply to locals,
but this is usually much less of a concern.

[*] #pragma optimise [no-]foo
Enables or disables various specific optimisations without needing to deal with
commandlines etc, which can ensure other users alwways use the same
optimisation.
Note that if the argument is 'addon' then fteqcc will disable any optimisations
that might break addons/mutators. Otherwise accepts 0-3 as does the commandline.

[*] #pragam keyword enable|disable KEYWORD
Enables or disables parsing of a keyword. This can be used as a lazy wat to
avoid conflicts between eg fteqcc's break keyword and quake's break builtin.
Note that all keywords are still available using a double-underscore prefix,
eg '__break;' will always work. Many keywords default to disabled in order to
avoid common conflicts.

[*] #pragam flag enable|disable NAMEOFFLAG
Enables or disables some compiler flag (aka feature). These can affect how
various expressions are interpreted.
The exact list ought to be documented elsewhere.

[*] #pragam warning enable|disable|error|toggle WARNINGCODE
This controls the behaviour of the specified warning. If the warning is enabled
then it'll print as normal. If it is disabled, then the compiler will merely
mute the warning, everything else will still work the same. If the warning is
set to error, then any time that warning is encountered, the compiler will
consider it to be a soft error (aborting after 10 soft errors) and no output
will be generated.
The vanilla qcc silently accepted certain statements that are fundamentally
unsafe, and which many mods of the era used.
It is strongly recommended to make these into werrors instead, if you can.
Not all errors have a warning code to disable them, but those that do will
print their code every time one is encountered. Don't disable them simply
because you're lazy, as this solves nothing (if nothing else at least use
#warning to remind you to fix any spam later).

======================
5. Other Pre-Processor
======================

[*] #define foo bar
Defines a preprocessor constant/macro. Any time the compiler sees 'foo', it will
replace it with 'bar'.
If you have more than one token, it is strongly recommended to include brackets,
otherwise operator precedence can be confused between the code where the macro
is used and its contents (although this may even be desirable in rare
situations).
Multiple-line macros can be specified by a trailing backslash on the previous
line (there must be no whitespace between the backslash and the linebreak).
It is possible to embed preprocessor directives inside macros by using a
trailing backslash with the preprocessor starting on the next line.
However, this sort of vileness is STRONGLY DISCOURAGED, and will generate
warnings.

[*] #define foo(args) bar
Defines a preprocessor macro. This causes foo to act much like a function, with
any tokens matching an argument being replaced with the contents of that
argument, and otherwise acts as a constant.
Note that side effects (like pre/post increments or assignments) as arguments
can trigger multiple times if the argument is evaluated more than one in the
macro, or not at all if its not used.
Thus such side effects are not recommended.
Additionally, the macro should normally enclose each argument inside a
parenthasis in order to avoid operator precendence issues between caller
and macro.
Macros can contain braces or brackets, including unmatched ones, but this is
generally not recommended except possibly in BEGIN_* and END_* macros.
A single hash inside a macro body will 'stringify' the following token.
A double-hash will 'paste' the preceeding and trailing token together, removing
any whitespace, concatenating the two into a single token (which can be used to
generate names of variables/macros according to a base token.

[*] #append foo bar
Appends bar onto the end of the preprocessor macro.
This can be useful for list-like macros.

[*] #undef foo
Forgets the macro specified.

[*] #if EXPRESSION
The expression only supports numbers.
No variables are allowed, not even if they're defined with const.
The expession may contain && and || operators, and may include a special
'defined(x)' intrinsic that returns true if the name is in fact defined as a
macro (not a variable).

[*] #ifdef MACRONAME
Equivelent to #if defined(MACRONAME)

[*] #ifndef MACRONAME
Equivelent to #if !defined(MACRONAME)

[*] #elif EXPRESSION
Acts like #else #if expression but on a single line and without needing an
additional #endif

[*] #else
Parses the following text only if none of the expression in the preceeding #ifs
were false.

[*] #endif
Terminates a conditional preprocessor block.

=====================
6. Control Statements
=====================

[*] break;
Jumps outside of the current for/while/until/do loop, or switch statement.

[*] continue;
Jumps back to the start of the current loop.

[*] return
    return; // for functions defined as returning void
    return foo; // for functions with an actual return type.
    return = foo; // for __accumulate functions that wish to execute accumulated
                    code instead of skipping it all.
    __exit; // exit as if reaching the end of the function.
This is fantastic for confusing decompilers but otherwise should not be used.
The accumulate version above sets an implicit variable which is automatically
returned once control reaches the end of the function.
The other forms will leave the function there and then.
For compatibility reasons, fteqcc does not strictly enforce return types,
however this is bad practise and you really should fix any related warning
if you want to avoid unintended type punning.

[*] goto foo;
Jumps to another location of the current function. The location must be marked.
    goto foo;
    unreachablecode();
    foo:

[*] { }
Blocks are a convienient way to group multiple statements.
Note that any control statement documented as taking either a block or a
statement does so interchangably (and many programming guides recommend that
blocks ALWAYS be used).
Note that blocks can be used outside of control statements too.
This allows for weird grouping or preprocessor workarounds.

[*] if (condition) statement;
The most simple conditional branch.
If the condition is considered true, then the code will be executed, otherwise
it will be skipped. If the expression is followed by an else satement then that
will be executed if the primary block was not.
Large 'else if' chains can be constructed, but you may find switch statements to
be more readable. 
At this point, we have to ask ourselves what the nature of truth really is.
Not in a philosophical sense, but in a programmery sense.

QuakeC looks for truth in multiple ways, and all control statements use the same
basic form of truth, which depends upon types, but unitialised variables are
always FALSE (except field references, which are typically auto-initialised):

    [*] int
    False when 0, true when anything else.

    [*] float
    False when +0, true when anything else. Note that -0 is normally TRUE, but
    some engines might treat this as false regardless, so don't expect things
    to make sense. There's a compile-flag to treat if(-0) as FALSE, for a small
    performance hit.

    [*] strings
    False when NULL, true when not NULL. Note that empty strings are not the
    same as NULL.

    [*] functions
    Only the null function is false (assignments from __NULL__ or other null
    functions can be used to reset a function reference to null).
    Other functions (including SUB_Null) are considered true.

    [*] vectors
    By default, fteqcc compares all three components against +/-0.
    Other QC compilers will typically test the _x component only.

    [*] fields
    Tests for null... Note that (typically) the modelindex field aliases the
    null field, so would be considered false.

    [*] entities
    The world entity is equivelent to null, and thus false. All other entities
    are considered true.

    [*] pointers
    __NULL__ is false, otherwise true.

    [*] __variant
    Danger... don't do this at home.

    [*] arrays, structs, unions
    These complex types cannot be evaluated for truth. You will need to evaluate
    a specific index or member instead.

HexenC adds an inverted form of if statements:

    if not(condition)
        break;
        
Which is especially useful to test the return value of eg fgets, allowing you to
detect end-of-file conditions without breaking when encountering empty lines -
note that `if(!condition)` tests for empty instead of null, and is thus not
suitable in all cases.

[*] for (initial; condition; increment) statement;
Like in C. The initial terms are executed, then the loop will restart for as
long as the condition evaluates to true. The increment term is executed each
time the loop is restarted (including via continues) but not the initial time.
Multiple initial terms or increments can be achieved via use of the comma
operator, while the condition term must use the && or || operators.
Declarations are permitted inside the initial term, but have scope only within
the loop.

[*] while (condition) statement;

[*] do while

    do {
        statements();
    } while( condition );

[*] __state
This is an alternative way to set .frame, .think, and .nextthink in a single
opcode.
    __state [framenumber, functiontothink];	// quake style, accepts expressions,
                                            however do not use pre-increment
                                            nor post-increment as this is
                                            potentially ambiguous - use
                                            brackets if you need this.
    __state [++ firstframe .. lastframe];	// hexen2 style, MUST use immediates
                                            / frame macros.
For the hexen2-style version, the animation automatically repeats
selecting(wrapping) the frame. The cycle_wrapped global will be set according to
whether the animation wrapped or not (starting from a frame outside of the range
does not count as a wrap).

[*] switch / case / default
    switch (expression) {
    case 0:
        statements;
        break;
    case 1..5: // ranges are inclusive, so this includes 5 but not 5.001
        statements;
        break;
    case 6:	// falls through
    case 7:
        statements;
        break;
    default:	// if none of the above cases matched (like 8 or .3)
        statements;
        break;
    }
Switches allow a slightly cleaner alternative to massive if-else-if-else chains.
The case statements define various possible values, with the following code
being executed.
The 'default' statement defines a fallback location to execute from if none of
the cases matched the expression's value. Note that execution will continue
through any later cases, so be sure to use break statements to prevent undesired
fall-throughts.
Cases may be either a single value, or in the case of a numeric expression they
may be a range of values seperated by a double-dot (eg: case 0..1:foo;break;).
Cases are not required to be constants, but they must not be expressions (which
means fixed array indexes are acceptable, but not dynamic indexes).

[*] __thinktime
    __thinktime ent : delay;
is equivelent to 
    ent.nextthink = time + delay;
When using -Th2 on the commandline, the double-underscores are not required.

[*] __until
    __until(condition) {statements;}
A flipped version of while loops - the loop will repeat until the condition
becomes true. When using -Th2 on the commandline, the double-underscores are not
required.

[*] __loop
    __loop { statements; }
Generally its better to use while(1){} or for(;;){} instead
When using -Th2 on the commandline, the double-underscores are not required.

==============
7. Basic Types
==============

7.1) entity
===========

Quake's objects. Each one has its own copy of each and every field.
Except for the world and players, the only difference between each entity is the
contents of its fields.
Note that collision and pvs state is tracked invisibly, and can be updated by
calling setorigin.

7.2) float
==========

These are standard IEEE single precision floats.
If you are attempting to store bit-values in a float then go no higher than 24
bits, failure to adhere to this can result in the lower bits getting forgotten
due to precision issues.

Float immediates can be specified as decimal (eg: 5.3), or as hex (eg: 0x554336
- note the bit limitation means you should stay with 6 hex digits).
Numbers with no decimal point are normally assumed to be floats, but if you wish
to be explicit then you can simply add a trailing point.

Additionally, character codes can be inserted as immediates using eg 'x' for the
ascii value of the x glyph.

A denormalised float is a very small float with its exponent part set to 0,
which is a special case of floats where the mantissa component has no implied
leading bit set to 1.
These thus have the same representation as an integer with up to 23 bits and can
thus be used to manipulate pointers/ents/strings in various hacky ways (as 
popularised by qccx). 
Not only are such hacks not recommended due to engine incompatibilties, but many
CPUs/binaries are explicitly configured to treat all denormalised floats as 0
for performance reasons and so their use isn't recommended even when not
exploiting an engine's QCVM, and any operation that implicitly requires
denormalised floats will generate warnings (which can be disabled).

7.3) string
===========

String immediates take the form of eg: "Hello World". Implicit concatenation
exists and can be used by simply placing two adjacent immediates.
To avoid issues with codepages and unicode conversions, strings should be kept
as ascii where possible, this can be achieved with string escapes instead of
pasting non-ascii values from an external tool.

    [*] \\
    Represents a single backslash character.

    [*] \"
    Represents a single double-quote character without closing the string.

    [*] \'
    Represents a single apostrophe character.

    [*] \n
    Represents a new-line character.

    [*] \r
    Represents a carrage-return character. This should only be used at the end
    of console prints where you wish for the next line to replace the one you
    just printed, and can be used for progress sprints without flooding the
    console too much.

    [*] \s
    Denotes 'special' text. This is an easy way to write red text without
    needing to resort to non-ascii source.

    [*] \0 through \9
    These represent 'golden' numbers.

    [*] \x##
    Represents a single byte with an explicit 8-bit hex value. If your engine is
    configured to interpret text as utf-8 then this will often result in invalid
    character encoding, if above 127.

    [*] \u#
    Represents a utf-8 encoded character. The # represents multiple hex nibbles.
    In order to avoid confusion with trailing text, you may need to terminate
    the string early and resume it again using string concatenation, but another
    string escape works well too. This should only be used for mods that require
    engines to interpret text as utf-8.

    [*] \(      \=      \)
    These three represent the open/center/close characters that are typically
    used for quake's slider glyphs.

    [*] \<      \-      \>
    These three represent the start/middle/end characters of quake's line
    seperator glyhs.

There are a few other escapes, but I cba to document them as I'd rather people
just used \x instead.

Additionally, FTEQCC supports raw strings.
These are specified as eg: 
	R"delim(Your String Here)delim". 
Any and all text within the two brackets is your string - including any new line
characters exactly as they are in the file.
Any escapes are ignored, and will appear in the resulting string as-is
(you'll see the backslashes in-game).

The two 'delim' words in the example must match each other (but can be 0-length)
and are used as a way to allow close-bracket+double-quote pairs to exist inside
the raw string itself, including nested raw strings (so long as the delimiters
differ).
Note that file paths in quake should normally always use the more portable
forward-slash for path seperators, instead of the microsoft-only backslash
seperator.

Some engines support internationalisation. This is achieved by replacing all
strings defined as e.g. _("foo") according to the contents of a progs.LANG.po
file. 
Mods that use this mechanism will likely also need to enable utf-8 support in
the engine, as well as use a unicode font.

Strings in the QCVM are nominally considered to be indexes from the start of
some string table defined by the progs.dat, however there are many special types
of string that are special or flawed.

    [*] null string
    The null string is the only string considered null. It is always empty.

    [*] immediate string
    This is any string immediate that came from inside the qc.

    [*] permanent string
    These are any string that came from parsing map entities.

    [*] engine string
    These strings point into engine memory, and their contents may change at any
    time even when the string reference doesn't. This is why it can be so hard
    to detect when the player's netname field changes - because the field itself
    doesn't actually change.
    
    [*] zoned/allocated strings
    These strings are ones that were returned by the strzone builtin (part of
    the FRIK_FILE extension). These are the ONLY strings that can be safely
    strunzoned in all engines (some engines may silently ignore the null string
    for convienience).
    If your mod mixes permanent strings (or even immediate strings) with
    allocated strings then you may find yourself with no way to decide whether
    you need to call strunzone or not. It is recommended to just strzone in your
    spawn functions etc, despite how ugly that is.
    Note that allocated strings CANNOT safely be stored in globals in certain
    engines, at least not if saved games are to load correctly without strunzone
    crashing on the non-zoned strings loaded from the saved game.
    
    [*] temporary string
    Temp strings are messy and temporary by their very nature.
    Their behaviour is highly engine-specific. Many engines rotate between 16
    engine strings (or 1, in the case of vanilla quake), so after the 16th call
    that returns a tempstring the older tempstrings get overwritten (you can
    renew the string with strcat, but this is somewhat messy). Do not store them
    inside globals or fields. Even temporarily storing a tempstring into a
    global/field can result in warning messages when saving a game.

    QS behaviour: Cycles between 16 tempstrings.
    DP behaviour: Allocates more memory for tempstrings as needed. 
                Fails if strunzone is called on loaded saved games, spams if
                tempstrings are still referenced when saving.
    FTEQW behaviour: Does not distinguish between permanent strings, allocated
                    strings, nor temporary strings. All three have the exact
                    same behaviour - strzone is an alias for strcat (and
                    strunzone is a no-op), and tempstrings are collected only
                    once they are no longer referenced.
                    This avoids most savedgame issues.
    
    
    
    
7.4) int / integer
==================

Generally requires opcode extensions.
Note that unlike C, QC assumes numeric immediates to be floats.
Normally you should use a postfix of i to explicitly make it an int immediate,
but you can also enable a specific compiler flag to assume immediates as ints.

7.5) vector
===========

Vector immediates traditionally take the form of 'x y z', but using [x, y, z] 
allows formulas and thus simpler argument passing.
Note that vector*vector yields a dot-product, while all other operations are
per-channel.
Normally vectors act a bit like unions and define both 'vec' and 'vec_[x|y|z]'
variables allowing for direct channel access, however the _x etc versions are
not always available (eg in arrays). The modern way to access individual
channels is with eg vec.x instead. Note that array indexing also works, so
vec[0] returns the _x component.
Dynamic indexes work also, but with the same performance hit as arrays so it is
generally best to avoid that if you can.

7.6) __variant
===============

This type represents an undefined type no larger than a vector, and should
normally be used only for function arguments or return value, but can also be
used for type punning.

================
8. Complex Types
================

8.1) arrays
===========

FTEQCC supports single-dimension arrays.
float foo[] = {1,2,3,4};
will thus define a float array and will infer its length as 4.
If you need to use an explicit length, or you do not wish to initialise the
array, then you must put the needed length inside the square brackets.
Note that arrays are 0-based, so an array defined as float foo[2]; can be
accessed as foo[0] or foo[1], but any other value (including foo[2]) is out of
bounds. Indexes will be rounded down.
foo.length can be read if you wish to know how long an array is (especially if
the length was inferred for some reason)
Dynamic indexes ARE supported in all cases, however they may come at a
significant performance loss if you do not have extended opcodes enabled, so it
is generally preferable to unroll small loops such that constant indexes can be
used.
Dynamic lengths are not supported at this time.
Arrays are also supported within structs, allowing for (clumsy)
multi-dimensional arrays.

8.2) fields
===========

Fields are defined by prefixing the field's type with a dot.
Every single entity will then have its own instance of the data, accessed via
    eg: self.myfield
Fields are assumed to be constants, with any uninitialsed fields reserving space
in every single entity in order to hold the data. Fields defined as var or
initialised to the value of another field will NOT consume any space within
each entity.

    .float foo; // const, allocates storage.
    var .float bar = foo;
    void() fnar =
    {
        self.foo = 42;
        if (self.bar != 42)
            dprintf("the impossible happened\n");
    };

Note that field references are variables in their own right.
They can be defined as arrays, they can be passed to functions etc (eg the find
builtin depends upon it).
A word of warning though - field references will not appear in most saved game
formats. That's probably fine for deathmatch, but if you're using them for
singleplayer then be sure to initialise them (even if to the value of another).

8.3) functions
==============

In QuakeC, functions are both a function reference/variable, and typically a
function immediate/body, much like a string is both a string reference, and the
string data itself.
So function definitions are initialised in basically the same way as any other
variable, where the function-type syntax is basically just returntype(arglist),
eg:
    returntype(arglist) name = functionbody;
functionbody can then be either some other function, or a function immediate.
As a special exception for C compatibility, the arglist parenthasis can follow
the function's name instead, and when the initialiser is an immediate, the
equals and trailing semi-colon tokens are optional.
Note that function immediates are what contain the bulk of code, and can only be
present within the context of a function type - meaning either in a function
initialisation or via a cast (creating an annonymous function - note that these
are not safe for saved games, so try to avoid their use in ssqc).
Because functions are really function references, you can define them as var, 
and by doing so you can remap/wrap them at any point you wish. function types
can also be used freely within function arguments or anywhere else.
    
    void() somename = {}; // QC-style function
    
    void somename(void) {} // C-style
    
    void() foo = [$newframe, nextfunc] {}; // QC state function ( function
                                        // contains: self.frame = $newframe; 
                                        // self.think = nextfunc; 
                                        // self.nextthink = time+0.1; )
    
    var void() dynreference; // uninitialised function reference, for
                            // dynamically switching functions.
    
    var void() dynreference = somename; // initialised function references work
    
    void(vector foo, float bar) func = {}; // function with two arguments.
    
    void(float foo = 4) func = {}; // function that will be passed 4 for the
                                // first argument if it is omitted.
    void(... foo) func = {
        for(float f = 0; f < foo; f++) 
            bprint(va_arg(f, string));
        }; // variable-args function that passes each arg to another.
        
    void(optional float foo, ...) func = #0; // name-linked builtin where the
                                            // first arg may be ommitted but
                                            // must otherwise be a float, with
                                            // up to 7 other args.
                                            
    void(void) func = #0:foo; // unnumbered-but-named builtin.
    
    void(float foo) func : 0; // hexenc builtin syntax
    
Note that QC can only tell how many arguments were passed using the
variable-argument argcount form. Any optional arguments that were omitted will
have undefined values. Any argumentsspecified after an optional argument must be
omitted if the prior arg is omitted but otherwise must be specified unless they
are optional themselves, or preinitialised.
Preinitialised non-optional arguments can be omitted, their preinitialised value
will be passed in this case. If the argument list is empty (ie: two adjacent
commas in the call), then the argument's default value will be passed
automatically regardless of whether the argument is considered optional.
Builtins can only accept up to 8 args. Non-builtins have a much higher limit.
Vectors count as 1 argument (and thus allow you to pack additional information).

Structs can be passed but will be counted as
ceil(sizeof(thestruct)/sizeof(vector)) arguments.
Named builtins can be used by some (but not all) engines to avoid numbering
conflicts. Typically these builtins must also be numbered as 0.

8.4) typedef
============

    typedef type newname;
    
Typedefs allow the creation of an alias for types.

8.5) enum / enumflags / strongly typed enums
============================================

    enum int
    {
        FIRST,
        SECOND,
        THIRD,
        NINTH=8
    };
    
Provides an easy way to define a set of constants.
enum: Each name will default to one higher than the previous name, with the
first defaulting to 0. enumflags: Each name will default to twice the previous
name, with the first defaulting to 1, ideal for bit flags.

Strongly typed enums are also supported:

    enum class foo { cake, pie, sauce };
    enum class bar { banana, sauce, pie };
    
Standard enums do not have their own scope. So you could not reuse the names of
inside constants.

8.6) struct
===========

Allows you to define a struct, which is useful for boxing multiple related
variables.

    typedef struct
    {
        vector rgb;
        float a;
    } rgba_t;
    rgba_t opaque_red = {'1 0 0', 1};

    void(rgba_t c) fillscreen =
    {
        drawfill([0,0], screensize, c.rgb, c.a, 0};
    };
    void() drawstuff = 
    {
        fillscreen(opaque_red);
    };
These are especially useful when combined with pointers, but can also simplify
copies.

8.7) union
==========

Equivelent to structs, except all struct members start at the same offset.
This can be used for either type punning or compressing mutually-exclusive
fields inside complex struct layouts. By nesting structs, unions and arrays,
you can get some quite complex data structures.
Note that unions and structs define within unions or structs do not need to be
named. Members from child structs will automatically be accessed as if they were
part of the containing stuct.
    struct
    {
        float type;
        union
        {
            struct
            {
                float f;
                vector bar;
            };
            struct
            {
                string s[2];
            };
        };
    } foo[8];
    float() foobar =
    {
        if (foo[4].type)
            return stof(foo[4].s[1]);
        else
            return foo[4].f;
    };

8.8) class
==========

    class foo : entity
    {
        float interval;
        virtual void() think =
        {
            centerprint(enemy, this.message);
            nextthink = time+interval;
        };
        nonvirtual void(enemy e) setEnemy =
        {
            enemy = e;
        };
        void() foo =
        {
        nextthink = time+interval;
        };
    };
    void() someiplayerfunction =
    {
        foo myfoo = spawn(foo, message:"Hello World", interval:5);
        myfoo.setEnemy(self);
    };
    
The above is a terrible example, sorry.
If the parent class is omitted, entity will be assumed.
Class constructors double up as spawn functions, and the spawn intrisic works
in the same way - the named members will be set before the constructor is
called, instead of passing arguments to the constructor (which avoids the need
for overloads etc). The 'interval' field above is defined as a class field.
Such class fields are valid ONLY on entities of that class, which allows for
more efficient memory usage.
Member functions can be defined as virtual (such functions are technically
pre-initialised fields, and thus compatible with things like think or touch),
non-virtual (read: non-inherited), or static (where 'this' cannot be used).

Public, private, protected are parsed like in C++, but ignored.
Only a single parent type can be inherited, and it must be a class or the
general entity type.

8.9) pointer
============

(Note: not a keyword)
As in C, pointers are defined using an asterisk prefix on the type's name.
    float *ptr;			// define a pointer-to-float
    ptr = &self.frame;	// obtain the address of a variable
    *ptr = *ptr + 1;	// access through the pointer (aka: dereference)
In order to define a field that contains a pointer (instead of a pointer to
a fieldref), use '.*float ptr;', or you can define the field using a typedefed
pointer.
Pointers can be used without qcc extensions, however you can only get the
address of an entity's field, and you can only write. This is still sufficient
to rewrite world's fields, but not particuarly useful otherwise.
It is not possible to pass the address of a local into a child function, due to
QCVM limitations. As a work around, you can define the local as static or use
the alloca intrinsic. Generally you should use __[in]out arguments instead.
Classes can be prototyped with just 'class foo;', but any class-specific fields
will not be usable until the actual class definition, which can mean that
methods must have their code defined outside of the class itself.
A method can include only its prototype within the class, and with the eventual
method being defined as eg: 'void() classname::methodname = {};'.

8.10) Accessors
===============

accessors are a weird and whacky way to invoke functions in a more friendly way.
They allow a reference/handle to provide a number of properties that invoke get
or set functions when used. Many of these functions are excelent candidates for
inlining...
A good example is that of setting up a string-buffer type that invokes an
engine's bufstr_get/set builtins, allowing you to write stringbuffer code as if
it were simply accessing an array.
index types can be any type of variable, so eg hash tables can be accessed as:
    hashaccessor["foo"]

Here's an example using the string buffers extension:

    accessor strbuf : float
    {
        inline get float asfloat[float idx] = {
                return stof(bufstr_get(this, idx));
            };
        inline set float asfloat[float idx] = {
                bufstr_set(this, idx, ftos(value));
            };
        
        // we can get away with directly referencing existing functions/builtins
        get string[float] = bufstr_get;
        set string[float] = bufstr_set;
        get float length = buf_getsize;
    };
    void() accessorexample =
    {
        // buf_create normally returns a handle in a float
        strbuf b = (strbuf)buf_create(); 
        
        // We can now use b as if it were defined as string b[];
        // There isn't even a limit to the indexes!
        b[0] = "This is";
        b[1] = "a test";
        b[2] = "of stringbuffer access";
        // gap!
        b.asfloat[4] = 4;
        
        // loop through them all. Note how the length property invokes
        // buf_getsize which tells us the maximum valid index.
        for (float i = 0; i < b.length; i++)
            print(sprintf("%d: %s\n", i, b[i]));
        
        // still needs to be freed though
        buf_destroy((float)b);
    };

An accessor property defined with an & after the access type specifies that the
'this' inside the code can actually be written to. Otherwise it should be
considered const, which is fine in the above case where it is just a handle.
In set properties, the value to assign is simply called 'value'. If there is
just a type with no name inside the array, then the used key will be named
'index'.
The index type can be anything, so long as it is typedefed.
Note that eg 'b.foo' is equivelent to 'b["foo"]' when b is a variable of type
accessor and 'foo' is not a property of b, b has an unnamed property with an
index type of string, and 'foo' isn't an immediate.
This is useful with accessors built around hashtables.
The unnamed property can be a non-array too - such properties can be accessed
only via eg '*b'.

=================
9. Type Modifiers
=================

9.1) const / var
================

Definitions are either constants or variables.
Initialised globals are normally considered constants, while locals are always
assumed to be variables (this part differs from vanilla qcc).
Uninitialised field and function globals are considered const also (const fields
will be auto-initialised, while functions will generate an error if they are not
explicitly initialised).

9.2) __unused / noref
=====================

This variable is probably unused. Don't warn about it.
These variables may also be stripped completely if they are not referenced
anywhere.

9.3) __used
===========

This variable is actually used somewhere, even if the qcc cannot tell that
(eg: by the engine). There will be no warnings about it being unused, and it
will NOT be auto-stripped.

9.4) local
==========

Obsolete prefix that means nothing on its own.
Vanilla QC used this to tell the compiler to expect a variable definition inside
a function (instead of actual code). However, in FTEQCC this should not normally
be needed except with certain rare type modifiers.

9.5) static / nonstatic
=======================

Static globals are visible only within the .qc file in which they are defined.
Static locals are visible only within the function in which they are defined
(but also become persistent and do not lose their values between calls - like
globals).
Note that static variables use name mangling that might get renamed between
releases, which can break saved games if you're not careful.

9.6) nosave
===========

Globals marked as nosave will not appear in saved games.
They will thus lose their values in saved games, which might either be
undesirable, or a clumsy way to detect reloads.
When the game is reloaded, they will typically revert to the values that were
set at time=0.2 on account of the weird way that saved games work.
nosave is recommended for variables that track objects which cannot be reloaded,
like file handles.

9.7) inline
===========

Functions marked as inline will be eligable for inlining for a small performance
boost.
FTEQCC's inlining is limited, and should generally only be used for small
functions (eg ones that exist to just call other functions with a different
argument order etc).

9.8) strip / __ignore
=====================

This variable / function / field is NOT used. Function bodies will be ignored,
and any definitions will be stripped. If the qcc detects that it is still
required somewhere, you will get a compile error. This can be used inside
#defines to create CSQC-only or ssqc-only functions without needing #ifdefs
inside every single function.

9.9) shared
===========

Globals marked as shared will have the same value regardless of which dat it
was defined in within a single QCVM (read: for mutators, not CSQC).

9.10) optional
==============

optional function arguments may be omitted without warnings/errors. Note that
only the engine can tell how many args were actually passed, so this should
normally only be used on builtins.
QC functions should normally use initialised arguments instead. These have
well-defined values if the argument is ommitted (slightly slower, but avoids the
need for extra signalling).

9.11) __inout / __in / __out
============================

Valid only for function arguments.
By default, all function arguments are __in arguments. However, if they're
defined as __inout or __out then any changes the callee made to the argument
will be written back to the passed value in the caller.
__out arguments cannot accept constants, nor any other expression that cannot be
assigned to (like additions etc).
This mechanism allows a function to return multiple values without needing to
resort to vectors nor structs nor pointers.

9.12) __weak
============

Weak symbols will not conflict with other definitions of the same variable.
Weak symbols will be ignored if they are already defined, and replaced if
followed by a non-weak definition with the same name.

9.13) __wrap
============

Defines a function that is a wrapper for a prior instance of the function with
the same name.
There MUST be a function already defined with the same name, you can define one
as __weak if there is not. If you combine __weak and _wrap on the same function,
then the function will be silently ignored if there was no prior define.
Wrappers MUST reference their 'prior' function, but they can do so by discarding
it, eg: (void)prior;

9.14) __accumulate
==================

Accumultate is a more efficient but limited way of combining functions.
Additional definitions of the function will be concatenated onto the end of the
prior function. A followed return statement in any of the prior functions will
prevent any later accumulations from executing - thus an alternative way to
specify return values is recommended, eg: return = 5;

=============
10. Operators
=============

Operator precedence follows somewhat complex rules that do NOT match C's
operator precedence.
As a general rule, QC is more forgiving, at least if you don't expect C
precedence, particuarly around the & and | operators.

Operators are listed in rough order of priority.
Unary operators are normally written with the operator before their argument,
the exception being post-increment/decrement.

[*] . field
The field operator is context sensitive.
If the lhs is an entity then the rhs MUST be a field reference.
If the lhs is a class or struct then the rhs is expected to be a member of that
class or struct (or from a parent class).

If the lhs is a pointer then it will be dereferenced first.
(For compatiblity with C, this operator can be written as -> instead.)

[*] unary ++ and --
These operators come in two forms - pre and post.
For instance, '++foo' preincrements foo, while 'foo--' postdecrements it.
These change the value by 1, either up or down.
The pre form changes the value before reading its value as part of the
expression.
The post form changes the value AFTER it has been used in the containing
expression, and may have additional costs in certain situations.

[*] unary (TYPE) cast
Casts can be used to convert a variable or expression to a different basic type.
Most casts are performed implicitly on assignments (like int->float or vice
versa), but it can often help to be able to cast directly so that you don't
need to assign it to something first.
Some of the explicit-only casts are potentially unsafe. For instance, all
reference or pointer types can be cast to integers and back.
This is fundamentally unreliable, but it is available if you think you know what
you're doing. So as a general rule, if you need casts then you're writing code
that needs to be tested properly.
One likely use of casts is for converting classes from a parent type to a child.
The reverse is safe and performed explicitly, but parent to child has no
guanrentee that the class actually is the child type, without explicit checks in
your code. The need for an explicit cast helps remind you that you need to
verify the classname or equivelent.

    childtype foo = (childtype)parentref;

Note that casting floats to ints provides a convienient way to truncate a float
towards 0, eg:

    float f = (int)5.3;

[*] unary ~ bitwise not
Sets any bit that was clear, and clears any bit that was set.
Note that this exploits Two's complement numbers, and thus will usually result
in negative numbers. This does not mean that you should try using more than 23
bits in float-based bitfields, but should be safe so long as the upper 9 bits
are sign-extended.

[*] unary * dereference
Dereferencing a pointer means to follow the pointer back to the piece of memory
that the pointer refers to, either to read or write that memory.
It is possible to write to pointers without opcode extensions, but not read from
them.

[*] unary & reference
Obtains the address (aka: a reference) to the specified value.
This cannot be used on intermediate values, but can be used on array lookups,
fields, or globals.
This operator normally REQUIRES opcode extensions, however &self.skin is valid
even without, but the resulting pointer should be considered write-only.

[*] * multiply
Vector * vector is actually a dotproduct.
That is: (lhs_x*rhs_x)+(lhs_y*rhs_y)+(lhs_z+rhs_z)] and thus results in a single
float instead of a vector type.
Otherwise vectors and floats can be mixed, with the vector scaled by the float.

[*] / divide
Divides the left hand side by the right.
Vectors are only supported as the lhs. The rhs must always be a float or int.
If both arguments are ints then the result will round towards 0.

[*] % modulo
Performs a division, but returns the remainder (which might be 0).
This is true even for floats where none of the lhs, rhs, nor the result are
required to be a whole number.

[*] & bitwise and
The return value is the set of bits that are set in both the lhs and rhs.
Vectors can be used (but not mixed).

[*] | bitwise or
The return value is the set of bits that are set in either the lhs and rhs.
Vectors can be used (but not mixed). Note that due to floating point precision,
floats (or vector components) are limited to about 23 bits. Trying to set more
bits will result in a loss of precision which will typically result in the
lowest bits being forgotten.

[*] ^ - bitwise xor
The return value is the set of bits that are set in one one of the lhs and rhs,
with any bits set in both or neither being clear.
This is useful for toggling individual bits.

[*] << left shift
Shifts the number to the left. This is better understood in binary.
The lhs is multiplied by 2 several times (as described by the rhs).
If the rhs is 0 then the result is simply the lhs. Behaviour is undefined if rhs
is not a whole number, or is negative.
Cannot be performed on vectors.

[*] >> right shift
Shifts the number to the right. This is better understood in binary.
The lhs is divided by 2 several times (as described by the rhs).
If the rhs is 0 then the result is simply the lhs. Behaviour is undefined if rhs
is not a whole number, or is negative.
Cannot be performed on vectors.

[*] >< crossproduct
Only works on vectors. Returns the crossproduct of the two vectors, which is an
vector that is tangenital to both input vectors. The length of the result is
scaled by the length of the two inputs. The direction of the resulting vector
can be flipped by swapping the lhs and rhs values (or just negating the result).

[*] + add
Adds the two arguments together.
Mixing vectors and floats is not supported.

[*] - subtract
Subtracts the rhs from the lhs.
Mixing vectors and floats is not supported.

[*] == and !=
This compares two variables looking for equality. This is not a simple compare,
and thus null strings will be considered equal to merely empty strings. +0.0 and
-0.0 will compare as equal, etc.
== results in 1 when they are equal. != results in 1 when they are not equal.
Otherwise both result in 0.

[*] >= <= < >
Numeric comparisons. Valid for floats, ints and pointers, but not vectors, ents,
fields, functions, etc

[*] unary ! logical not
Evaluates the truth of its argument, and flips it, resulting in either 1.0 or
+0.0. Empty strings are considered false, vectors are considered in their
entirety, floats consider -0.0 to be false, otherwise tests for null.

[*] = assignment
This is the standard assignment operator. This operator accepts any type
(including structs/unions) except arrays, but the rhs MUST be compatible with
the lhs type. Assignments and initialisers work a little differently, with
initialisers having implicit types and thus allowing function bodies or structs
to be defined without casts.

[*] += -= |= &= &~= ^= *= <<= >>= /=
These are special assignment operators that perform an operation on the target.
For example, 'lhs += rhs' is equivelent to 'lhs = lhs + rhs;'.
This applies to each operator listed.
Thus foo *= 4; will multiply foo by 4, and store the result into foo, basically
'lhs OP= rhs;' is equivelent to 'lhs=lhs OP rhs;'
(note that &~= is equivelent to TWO operators, specifically
'lhs = (lhs) & ~(rhs);', but otherwise follows the same form)

[*] (+) bitset
Equivelent to 'lhs |= rhs;' or 'lhs = lhs | rhs;', changing lhs to a value which
includes all bits that were set in the rhs.
This operator is implemented for hexenc compatibility.

[*] (-) bitclear
Equivelent to 'lhs = lhs & ~rhs;', changing lhs to a value which has no bits
set that were in the rhs.
This operator is implemented for hexenc compatibility.

[*] ternary ?: conditional
Given the line 'result = A?B:C;', the result will be be equal to B ONLY if A is
true, otherwise equal to C. B may be ommitted, and if so will be equivelent to
A. Side effects will not be executed in the side that was not taken.

[*] && logical and
Asesses the truth of the lhs and rhs sides, and results in 1.0f if BOTH sides
are considered true, and 0.0f if neither or only one is considered true.
Does NOT early-out - both sides WILL be executed in full. (There is a
compiler-flag to enable early-out, in which case the lhs will always be
executed, but the rhs will be skipped if the lhs is true.)
Truth is a matter of who asks, and this comparison always considers -0.0 to be
false.

[*] || logical or
Asesses the truth of the lhs and rhs sides, and results in 1.0f if EITHER side
is considered true, and 0.0f if neither is considered true.
Does NOT early-out - both sides WILL be executed in full. (There is a
compiler-flag to enable early-out, in which case the lhs will always be
executed, but the rhs will be skipped if the lhs is false.)
Truth is a matter of who asks, and this comparison always considers -0.0 to be
false.

[*] , list
Seperates a list of expressions.
The following does not apply to argument lists - function call parsing uses
EVERY argument.
The return value of 'a,b' is actually just the rhs, but any side effects in the
lhs will be executed first. This inclues assignments or pre/post-increment
operators.
Thus lists are useful only where you want hidden sideeffects.

    vector tmp; vec = ( tmp_x = 5, tmp_y = 4,tmp_z = 7, tmp );

Is equivelent to 'vec = [5,4,7];' and thus has limited use in macros or to
express multiple statements without the use of a block and any extra indentation
required by coding style guides.

==============
11. Intrinsics
==============

[*] _(string strimmediate)
Defines a translation string. This auto-generates a symbol prefixed with 
'dotranslate_'. Certain engines can then use this to automatically replace your
strings with strings containing text from other natural languages, via the use
of a .po file (eg: progs.en_gb.po). You can use some part of the gnu gettext
library to extract these.
This intrinsic can be used even at global scope for initialisers.

[*] sizeof(variableortype)
This function accepts either variables or types, and reports the size-in-bytes
of the variable (or a variable of that type). When used on arrays, it returns
the size of the entire array (dereference it to read the size of a single
element of the array), but usually you should just read thearray.length instead.

[*] alloca(bytes)
Attempts to allocate stack memory, and returns a pointer.
This memory will be released when your current function returns.

[*] va_arg(index, type)
When in a QC function defined as accepting variable arguments, this reads the
nth argument, and interprets it as the specified type.
I would generally recommend to avoid variable arguments on qc functions on
account of there being no type checking, as well as performance issues with
emulated arrays.
Ideally, use optional or even __variant args instead.

[*] random([min,] max)
Returns a random number between min and max. If there's only one argument, then
the min argument will be interpretted as 0.
Note that this works by invoking the engine's arg-less random() builtin, and
said builtin MAY return 1 in various engines (but NOT fte+qss+dp) which can and
WILL result in bounds check issues.

[*] randomv([min,] max)
Returns a random vector within the specified box.
Note that different engines handle random() differently, and this can and
eventually WILL result in bounds check issues when combined with arrays.

[*] spawn(classtype, field1:value1, field2:value2, ...)
This uses the regular spawn builtin and then assigns to the fields for that
specified class, then calls the class's constructor before returning the new
object to the caller.
It is worth noting that this is consistent with map entities.

[*] used_sound(soundname) / used_model(modelname)
Arguments MUST be string constants/immediates.
These serve to silence warnings about sounds or models being precached but not
use. This can legitimately happen if there is a setmodel call that accepts
(as fteqcc can only flag constant modelnames, not variables.
They return their arguments, so eg:

    self.mdl = used_model("progs/foo.mdl"); 

..is fine.

[*] autocvar(name, value[, description])
Creates an autocvar with the specified name (not quoted). The autocvar's type
will be inferred from the value's type (which must be an intrinsic).
The description is useful only in combination with the '-v -v -v' argument
tupple, which dumps a list of all autocvars for easy copying into some
default.cfg file (as well as other output).

[*] entnum(ent)
Probably unsafe. Attempts to guess the entity's index.
Ideally use the num_for_edict builtin instead, if you can.

[*] precache_sound 
[*] precache_model
[*] precache_texture
[*] precache_file
[*] setmodel
[*] localsound
[*] sound
These intrinsics affect warnings about redundant/missing precaches.
precache_file lines might get stripped (along with their arguments).
Otherwise they are simply their normal builtins.
If using the outdated write-paks feature, the named files will be included into
paks numbered according to the numeric postfixes used on the precache intrinsic.

[*] floor
[*] ceil
[*] sin
[*] cos
[*] log
[*] sqrt
[*] pow
[*] mod
[*] bitshift
These intrinsics mirror their builtins, falling back to the builtin where the
arguments are not constants.

=====================
12. Modelgen Commands
=====================

    iD software's modelgen and spritegen tools were designed to read special
commands directly from qc files, ensuring that data was kept in sync.

Those tools are basically irrelevant now, but the qc syntax remains regardless,
and has been extended Model generation commands always start on a new line with
a leading $ char.

[*] $cd
[*] $origin
[*] $base
[*] $flags
[*] $scale
[*] $skin
Does nothing.

[*] $frame foo bar etc
Defines a series of frame macros. One per token.
Duplicate names will generate a gap (and a warning).
The compiler will then expand any $foo tokens to a 0-based float that is one
higher than the previous macro.

[*] $modelname
Allows for switching between models easily.
Models are expected to use different frame names.

[*] $framesave NAME
Saves the number of frame macros. Use $framerestore to return to it as needed.

[*] $framerestore NAME
Sets up the next $frame to return to a previous value.

[*] $framevalue IDX
Sets up the next $frame to use the specified value

[*] $flush
Wipes the list of valid frame macros.

==================
13. Compiler Flags
==================

    These are enabled with -Ffoo or disabled with -Fno-foo.
Many (but not all) can also be reconfigured mid-compile, using:
    #pragma flag [en|dis]able foo

[*] -acc
Reacc support.
Reacc is a pascall like compiler. It was released before the Quake source was
released.
This flag has a few effects. It sorts all qc files in the current directory
into alphabetical order to compile them. It also allows Reacc global/field
distinctions, as well as interprets | chars as new-line in strings.
Whilst case insensitivity and lax type checking are supported by reacc, they
are seperate compiler flags in fteqcc.

[*] -qccx
QCCX syntax
WARNING: This syntax makes mods inherantly engine specific.
Do NOT use unless you know what you're doing.
This is provided for compatibility only.
Any entity hacks will be unsupported in FTEQW, DP, and others, resulting in
engine crashes if the code in question is executed.

[*] -kce
Keywords Coexist
If you want keywords to NOT be disabled when they a variable by the same name
is defined, check here.

[*] -parms
Define offset parms
When set, defines explicit PARM0 PARM1 etc symbols (instead of leaving the
unnamed). These are useful if you make use of the asm keyword for function
calls, or you wish to create your own variable arguments. This is an easy way to
break decompilers.

[*] -autoproto
Automatic Prototyping
Causes compilation to take two passes instead of one. The first pass, only the
definitions are read. The second pass actually compiles your code. This means
you never have to remember to prototype functions again.
Note that while you cannot change this flag mid-compile, you can use:
    #pragma autoproto 
..before any symbol declarations, which can help avoid special compilation
instructions for third-parties etc.
This does not work for type declarations - typedefs must still be in logical
order.

[*] -wasm
Dump Assembler
Writes out a qc.asm which contains all your functions but in assembler.
This is a great way to look for bugs in fteqcc, but can also be used to see
exactly what your functions turn into, and thus how to optimise statements
better.
It is generally favourable to use the annotate option instead.

[*] -annotate
Annotate Sourcecode
Annotate source code with assembler statements on compile (requires gui).

[*] -nullemptystr
Null String Immediates
Empty string immediates will have the raw value 0 instead of 1.

[*] -ifstring
if(string) fix
Causes if(string) to behave identically to if(string!="") This is most useful
with addons of course, but also has adverse effects with FRIK_FILE's fgets,
where it becomes impossible to determin the end of the file. In such a case, you
can still use asm {IF string 2;RETURN} to detect eof and leave the function.

[*] -iffloat
if(-0.0) fix
Fixes certain floating point logic. Without this, (-0.0) will be considered true
inside conditionals, while (!-0.0) will ALSO be considered true.

[*] -ifvector
if('0 1 0') fix
Fixes conditional vector logic. Without this, conditionals will consider only
the first component, using the same rules for single floats.

[*] -vectorlogic
v&&v||v fix
Fixes conditional vector logic. Otherwise these operators would check only the
first component.

[*] -brokenarray
array[0] omission
Treat references to arrays as references to the first index of said array, to
replicate an old fteqcc bug instead of returning a pointer to the first element
of the array.

[*] -rootconstructor
root constructor first
When enabled, the root constructor of classes should be called first, just like
in C++.

[*] -caseinsens
Case insensitivity
Causes fteqcc to become case insensitive whilst compiling names. It's generally
not advised to use this as it compiles a little more slowly and provides little
benefit. However, it is required for full reacc support.

[*] -lax
Lax type checks
Disables many errors (generating warnings instead) when function calls or
operations refer to two normally incompatible types. This is required for
reacc support, and can also allow certain (evil) mods to compile that were
originally written for frikqcc.

[*] -hashonly
Hash-only constants
Allows only the use of #constant for precompiler constants, allows certain
preqcc using mods to compile. Specifically, preprocessor macros will NOT be
expanded unless they explicitly have a leading #.

[*] -lo
Logic ops
This changes the behaviour of your code. It generates additional operations to
skip the rhs of && and || expressions where the lhs prevents the rhs from being
significant (like in C). With this flag, the line if (0 && somefunction()) will
never call the function. It can thus be considered an optimisation.
However, due to the change of behaviour, it is not considered so by fteqcc.
Note that due to inprecisions with floats, this flag can cause runaway loop
errors within the player walk and run functions (without iffloat also enabled).
This code is advised:
    In player_stand1:
        if (self.velocity_x || self.velocity_y)
    In player_run: 
        if (!(self.velocity_x || self.velocity_y))

[*] -msvcstyle
MSVC-style errors
Generates warning and error messages in a format that MSVC understands, to
facilitate IDE integration.

[*] -debugmacros
Verbose Macro Expansion
Print out the contents of macros that are expanded.
This can help look inside macros that are expanded and is especially handy if
people are using preprocessor hacks.

[*] -filetimes
Check Filetimes
Recompiles the progs only if the input file modification times are more recent
than that of the output file. Requires old-style .src files and will ignore
modification times of #included files. If nothing changed then the compiler
quits early without writing any output.

[*] -fastarrays
fast arrays where possible
Generates extra instructions inside array handling functions to detect engine
and use extension opcodes only in supporting engines.
Adds a global which is set by the engine if the engine supports the extra
opcodes. Note that this applies to all arrays or none.

[*] -assumeint
Assume Integers
Numerical constants are assumed to be integers, instead of floats.

[*] -subscope
Subscoped Locals
Restrict the scope of locals to the block they are actually defined within, as
in C.

[*] -typeexplicit
Explicit types
All type conversions must be explicit or directly supported by instruction set.

[*] -boundchecks
Disable Bound Checks
Disable array index checks, speeding up array access but can result in your code
misbehaving.

[*] -nofileline
Ignore #pragma file
Ignores #pragma file(foo) and #pragma line(foo), so that errors and symbols
reflect the actual lines, instead of the original source.

[*] -embedsrc
Embed Sources
Write the sourcecode into the output file. The resulting .dat can be opened as a
standard zip archive (or by fteqccgui).
Good for GPL compliance!

==================
14. Engine Support
==================

    Different engines support different extensions.
These take the form of added builtins, new fields with special side effects (or
even existing fields with new values meaning new stuff), or globals that report
additional results or change the behaviour of existing builtins.
Engine extensions can be useful but they can also restrict which engines your
mod can run on. You'll need to find the right compromise for your mod yourself.

Most of the common important extensions can be queried at run time.
This is done eg as following:

    if (cvar("pr_checkextension"))
        if (checkextension("FRIK_FILE"))
            canopenfiles = TRUE;

Note that QuakeC does not normally early-out, so the two if statements must be
nested and not replaced with an && operator.
FTEQW (and QSS) have a few builtins that have no formal named extension.
These can be queried with eg the following:

    if (cvar("pr_checkextension"))
        if (checkextension("FTE_QC_CHECKCOMMAND"))
        {
            if (checkbuiltin(search_getfilemtime))
                cancheckmodificationtimes = TRUE;
            if (checkcommand("cef"))
                canusewebbrowserplugin = TRUE;
        }

Upcoming is a list of the engines with extensive extensions.
These files typically contain comments that describe the new stuff either on a
per-feature basis or per-extension basis.
If you don't understand the description of a feature for one engine then you may
find another engine describes it with greater clarity.

[*] FTE
    http://fte.triptohell.info/moodles/fteqcc/fteextensions.qc
[*] QSS
    http://fte.triptohell.info/moodles/qss/QSS_DevKit.zip
[*] DP
    http://svn.icculus.org/twilight/trunk/darkplaces/dpdefs/