The Table Type

The table is an important and powerful structure within GameMonkey script. At its most basic, it allows you to specify arrays of data; at its most complex, you can begin to create organised structures of data and functions for use in your games.

Tables as Arrays

A table can be used as a simple array which contains any type of data.

Initialisation Example:

myArray = table( 1, 2, 3.14, 4, 5, "dog", "cat", 100 );

Much like C/C++ arrays, you need to use indices to access the data within the table. All indices are zero-based when a table is initialised in this manner. Lua programmers should note this difference as in Lua, initialised tables begin at an index of 1.

Accessing the data:

myArray[0] = 50;
print( myArray[1] );
myArray[100] = "dog_100";	// new item added
print( myArray[100] );

Example code: tables_1.gm

Tables as Associative Arrays

A table can also be used as an associative array, much like the map structure in the C++ standard library. An associative array can be indexed using a non-numeric key, allowing for named data lookups. Again, the data items in an associative array can be of any type.

Initialisation:

myData = table( Name = "Test", Weight = 60 );

Accessing the data is as simple as the first example:

print( myData[ "Name" ] );
print( myData[ "Weight" ] );
myData["Name"] = "Albert";
myData["Test"] = "Some Text Here";
print( myData[ "Name" ] );
print( myData[ "Test" ] );

Example code: tables_2.gm

You will have noticed that we can assign new keys and indexes at any time as the tables have no defined bounds.

Tables as Mixed Arrays

You can use the table as a mixed array, an array that contains both indexed data and keyed data (as in an associative array). This makes the table structure very flexible:

myTest = table( 1, 4, Test = "Text!", 7, 8 );
print( myTest[0] );
print( myTest[2] );
print( myTest["Test"] );

Example code: tables_3.gm

In the example above, the second print statement prints the number 7 and not as you may expect, the word 'Text!'. The reason for this is because GM Script keeps indexes and keys separate from each other within the table.

Because GMScript tables store their indexes as gmVariables, it is theoretically possible to index a table on any type other than null (as indexing on null will return null). However, indexing tables on anything other than numbers or strings can be counter-intuitive, so it is best practise to avoid it.

Iterating Table Data - 'foreach'

The foreach statement allows you to iterate over the contents of a table in a loop. The most basic form of the foreach statement is to examine just the values within the table:

foreach ( <value> in <table> ) 
{ 
// statements 
}

An example of this follows:

fruits = table ( "apple", "pear", "orange" );
foreach ( frt in fruits )
{
	print(frt);
}

Example code: tables_4.gm

The code above will print the contents of the table to the console in no particular order. However, you may have noticed that the table key is often as important as the value it references and may wish to capture that data too:

foreach ( <key> and <value> in <table> 
{ 
// statements 
}

An example:

fruits = table ( "apple", "pear", Juicy = "orange" );
foreach ( k and f in fruits )
{
	print( "The value at key '", k, "' is '", f, "'" );
}

Example code: tables_5.gm

Will print something similar to:-

	The value at key '0' is 'apple'
	The value at key 'Juicy' is 'orange'
	The value at key '1' is 'pear'

Simulation with Tables