Scripting

TrackMania actually has an internal, custom scripting language. It appears to be used mostly for GUI purposes. So far, only two scripts have been found, in Game.pak.

Scripts are stored in binary form in .gbx files of class CMwCmdBlockMain (0x01067000). They are quite easy to parse and decompile since they are not compiled to opcodes: instead, the AST (Abstract Syntax Tree) is serialized, preserving all the high-level programmatic structures like if, while... And not just that, even the original variable names are available in plain text.

If you haven't yet, read about the general .gbx file format first. Then you will have a much easier time understanding the rest of this article.

Features

Every CMwCmdBlockMain script operates in the context of a certain object instance (which we'll call the global instance), the type of which is stored in the script. It can use the fields and methods of this object to access and create other objects. However, there is no way to instantiate a class manually; creating objects has to happen through one of the provided methods.

The language itself is quite limited. It has basic programming constructs like if/while/for, variables and function calls. It supports working with integers, floating point numbers, vectors, matrices and strings. Math operators are however very limited (e.g. no modulo, let alone things like sin or exp), and string functions are almost nonexistent. Also, for loops can only work with steps of 1.

Terminology

TrackMania uses slightly weird naming conventions in its scripting system.

Instead of "setting" a variable, the variable is "affected".
Variables are in fact referred to as "idents", and a variable reference is known as an "ident interface".
A field or a method of an object is a "param". (So in other words, a "param" has nothing to do with function parameters.) A reference to one of these is a "param interface".
An access path starting at an object and going through a series of fields to reach a field or method is known as a "stack".
4x3 transform matrices are known as "iso4"'s.
For some class names, the developers couldn't decide between English or French, so you'll see "CMwCmdExpNum" (clearly English since "number" is "nombre" in French), but also "CMwCmdExpInf" where Inf stands for "inférieur", French for "less".

Member IDs

The scripting language often makes use of member IDs. These are quite similar to chunk IDs: they are a 32-bit unsigned integer that indicates an engine, a class, and a part of that class. The difference is that the last three digits do not refer to a chunk but to a class member, which can be a field or a method.

The entire tree of engines and their classes has been extracted and is available on this wiki. All of the class members have *also* been extracted, however this results in a huge file which is too large for a wiki article. Instead, you can download it here.

Enumerations

Some class fields store an enumeration value. There is no separate definition of these enumerations; the possible enumeration values are stored together with the field information. Enumeration values are 0-based and are all named; see the class members download above.

Common structures

The following file structures occur quite commonly in scripts, so we list them first.

CBlockVariable

Like the name says, declares a variable in a code block.

string name
int32 ignored = 0
int32 type
if type is 4 or 5:
- int32 classID

The type number is to be interpreted as follows:

0: bool
1: int32
2: float
3: string
4: object reference
5: weak object reference?
6: vec2D
7: vec3D
8: iso4
9: unknown

CMwCmdFunctionInterface

Not used in any known scripts, so the meaning of the fields is more of a guess.

int32 flag
if flag == 0:
- noderef function
- int32 numArgs
- noderef args[numArgs]

CMwCmdIdentInterface

References a variable for reading or writing.

string varName

CMwCmdStack

Specifies an access path: a sequential series of fields, numerical array indices, and textual array indices. An important detail to note is that the access path is stored backwards. So for obj.Field1[1].Field2["boo"], the stack would contain ("boo", <Field2 member ID>, 1, <Field1 member ID>).

int32 numElems
int32 types[numElems]
for (i = 0 .. numElems - 1)
- if types[i] == 0:
  - int32 memberID
- else if types[i] == 1:
  - int32 numericalIndex
- else if types[i] == 2:
  - int32 ignored = 0
  - string textualIndex

CMwCmdParamInterface

Specifies a base object, a number of CMwStacks for fixed access path parts, and a number of node references for dynamic path parts.

There are two versions available of this structure, 0 and 1. Which version is used is decided by the object that owns it.

Version 0:

int32 useGlobalInstance
if useGlobalInstance == 0:
- string varName
int32 numIndexExprs
noderef indexExprs[numIndexExprs]
int32 numFixedIndexStacks
CMwStack fixedIndexStacks[numFixedIndexStacks]

Version 1:

int32 ignored = 0
int32 useGlobalInstance
if useGlobalInstance == 0:
- string varName
noderef instance
int32 numIndexExprs
noderef indexExprs[numIndexExprs]
int32 numFixedIndexStacks
CMwStack fixedIndexStacks[numFixedIndexStacks]

The base object is determined as follows:

If useGlobalInstance is 1, the global instance is used
Otherwise, if the "instance" field is not null, it is used
Otherwise, the variable named "varName" is used.

The complete access path can be reconstructed with the following algorithm:

string result = baseObject.ToString();
for (int i = 0; i < numFixedIndexStacks; i++)
{
    for (int j = fixedIndexStacks[i].Items.Count - 1; j >= 0; j--)   // Stack items are stored backwards!
    {
        if (j == 0 && i < numIndexExprs && indexExprs[i] != null)
        {
            result += "[" + indexExprs[i].ToString() + "]";     // index expr can be a number or a string
        }
        else
        {
            result += fixedIndexStacks[i].Items[j].ToString();
        }
    }
}

Classes

CMwCmdBlockMain (01067000)

The main script block, derived from CMwCmdBlock.

Chunk005

lookbackstring name?
int32 globalInstClassID
int32 numNodes1
noderef nodes1[numNodes1]
int32 numNodes2
noderef nodes2[numNodes2]
int32 numNodes3
noderef nodes3[numNodes3]

CMwCmdBlock (01030000)

A block of code (e.g. { ... } in C++ or C#).

Chunk004

int32 numStatements
noderef statements[numStatements]
int32 numDummyVars
CBlockVariable dummyVars[numDummyVars]
int32 numVars
CBlockVariable vars[numVars]

CMwCmdAffectIdent (01032000)

Assigns a value to a variable.

Chunk000

CMwCmdIdentInterface variable
noderef value
int32 isConst (0 or 1)

CMwCmdAffectIdentBool (01071000)

Simply derives from CMwCmdAffectIdent.

CMwCmdAffectIdentClass (01072000)

Simply derives from CMwCmdAffectIdent.

CMwCmdAffectIdentEnum (010A5000)

Simply derives from CMwCmdAffectIdent.

CMwCmdAffectIdentIso4 (01073000)

Simply derives from CMwCmdAffectIdent.

CMwCmdAffectIdentNum (01074000)

Derives from CMwCmdAffectIdent, but in addition:

Chunk000

int32 index

When assigning to a scalar variable, index is -1. For a 2D or 3D vector, indices 0, 1 and 2 mean the x, y and z component of the vector. For an iso4 (4x3 matrix), the index is the row-major index of the matrix field.

CMwCmdAffectIdentString (01075000)

Simply derives from CMwCmdAffectIdent.

CMwCmdAffectIdentVec2 (01076000)

Simply derives from CMwCmdAffectIdent.

CMwCmdAffectIdentVec3 (01077000)

Simply derives from CMwCmdAffectIdent.

CMwCmdAffectParam (01033000)

Assigns a value to a field of an object.

Chunk001

CMwCmdParamInterface1 paramInterface
noderef value
int32
int32