Torque 3D Game Development Cookbook: Over 80 practical recipes and hidden gems for getting the most out of the Torque 3D game engine

We will be adding a new TorqueScript function to a project based on the Torque 3D Full template and try it out using the Empty Terrain level. If you haven't already, use the Torque Project Manager (Project Manager.exe) to create a new project from the Full template. It will be found under the My Projects directory. Then start up your favorite script editor, such as Torsion, and let's get going!

We are going to write a TorqueScript function that will parse a space-delimited string and output the results to the console. This is done as follows:

The previous code walks us through all of the functions used to access and manipulate the variables that contain space-delimited fields. We will now examine each of these functions and learn how to make use of them.

After obtaining the player's world position, our first action in the previous example is to get the number of fields within the space-delimited string (the %position variable). This is done using the getWordCount() function that has the following form:

amount = getWordCount( string );

In this form, string is the space-delimited string that contains the number of fields we want to eventually parse. The getWordCount() function returns the number of fields counted. The previous code stores this value into the %count variable. If there are no fields in the string, then 0 is returned.

With the number of fields now known, we can retrieve the individual x, y, and z values of the %position variable based on an index. To do this we use the getWord() function that has the following form:

field = getWord( string, index );

Here, the string parameter is the space-delimited string to parse, and the index parameter is the field number to retrieve. The getWord() function returns a string containing the single requested field. If the field index does not exist within the passed-in string, an empty string is returned.

The next action performed in the example code is to retrieve more than one field at a time. Specifically, the code extracts the x and y values from the player's position (the first and second field). We use the getWords() function to retrieve more than one field, which has the following form:

fields = getWords( string, startIndex, [endIndex] );

Here, the string parameter is the space-delimited string to parse, the startIndex parameter is the start of the range to retrieve, and the optional endIndex parameter is the end of the field range. If endIndex is not provided or has a value of -1, then all of the fields at the end of the string are returned.

The getWords() function returns a string containing all of the requested fields. If none of the requested fields exist within the passed-in string, an empty string is returned.

The example code then goes on to manipulate the %position variable by changing its z value (the third field). This is done with the setWord() function that has the following form:

result = setWord( string, index, replacement );

Here, the string parameter is the space-delimited string to modify, the index parameter is the field index in the string to modify, and the replacement parameter is the string used to replace the current value of the field. The setWord() function returns a new string with the modifications and doesn't change the passed-in string. If we wanted to modify the original variable, we would just use the same variable name for the return value as we did for the passed-in string. For example, consider the following code:

%position = setWord(%position, 2, "0");

The new string will essentially replace the previous string stored in %position.

If the index passed-in to setWord() is larger than the number of fields in the given string, the returned string is padded with empty fields to make up the difference, essentially appending the replacement string on to the end. For example, the following code would print a count of six to the console (the fifth index accesses the sixth field):

%val1 = "1 2 3";
%val2 = setWord( %val1, 5, "4");
echo( getWordCount( %val2 ) );

The final action in the example code removes a field from the string variable. This is done using the removeWord() function that has the following form:

result = removeWord( string, index );

Here, the string parameter is the space-delimited string to modify, and the index parameter is the field index in the string to remove. The removeWord() function returns a new string with the modifications and doesn't change the passed-in string. If the given field index does not exist within the string, the original string is returned unchanged.

As with the setWord() function, if we want to modify the original variable, we would need to pass it in as the string parameter as well as use it to store the result. This is done in the example code with the %position variable.

While space-delimited strings are the most common type of list we will come across in TorqueScript, spaces are not the only way to delimit a string. Tabs and new lines may also be used. We could use tab delimiters when we want the fields to contain spaces, and new line delimiters when we want the fields to contain spaces or tabs.

The whole Word family of functions we just explored (getWord() and so on) actually works with more than just spaces. They treat all the spaces, tabs, and new lines as valid delimiters. But what if we don't want to count spaces as a delimiter, such as with a list of peoples' combined first and last names ("John Smith")? There are two other families of functions that narrow the scope of what is a valid delimiter: Field and Record.

function operateOnFields2()
{
   // Build up a list of tab delimited name
   %list = "John Smith" TAB "Mary Contrary" TAB "Fido";
   
   // Get the number of tab delimited fields
   %count = getFieldCount(%list);
   
   // Print out a list of fields by index
   for (%i=0; %i<%count; %i++)
   {
      echo("Field " @ %i @ ": " @ getField(%list, %i));
   }
}

operateOnFields2();

==>operateOnFields2();
Field 0: John Smith
Field 1: Mary Contrary
Field 2: Fido

function operateOnFields3()
{
   // Build up a list of new line delimited items
   %list = "0" TAB "First item" NL
           "1" TAB "Second item" NL
           "2" TAB "Third item";
   
   // Get the number of tab delimited fields
   %count = getRecordCount(%list);
   
   // Print out a list of fields by index
   for (%i=0; %i<%count; %i++)
   {
      echo("Field " @ %i @ ": '" 
           @ getRecord(%list, %i) @ "'");
   }
}

operateOnFields3();

==>operateOnFields3();
Field 0: '0^First item'
Field 1: '1^Second item'
Field 2: '2^Third item'

We will be adding some new TorqueScript functions to a project based on the Torque 3D Full template and try it out using the Empty Terrain level. If you haven't already, use the Torque Project Manager (Project Manager.exe) to create a new project from the Full template. It will be found under the My Projects directory. Then start up your favorite script editor, such as Torsion, and let's get going!

We are going to write a TorqueScript function that will retrieve each item from a string list and do some work on it as follows:

The previous code uses the foreach$() function to retrieve each item in the string list and does some work on it. In this example, the item is passed on to another function.

The foreach$() function is different than most of the looping TorqueScript functions (such as for()) in that it takes two parameters that are separated by the in word rather than a semicolon. It is also unusual in that it creates a new variable to hold a string of the item. The foreach$() function has the following form:

foreach$( item in stringList)
{
   ... Do something with item ...
}

Here, the stringList parameter is the list of items to be processed, and the item parameter is a new variable that is created to hold a string of the item. It is the item variable that we work on. In our previous example this is the %id variable.

There is another way to step through the items in a string by using the getWordCount() and getWord() functions. For example, put the following function at the end of the game/scripts/server/game.cs script file after the code we entered in the foreach$() example:

function parseStringList2()
{
   // Populate a variable with some sample object ID's.
   %objects = "1121 1122 1438 1643 2025 1118 1564";
   
   // Get the number of items in the string list
   %count = getWordCount(%objects);
   
   // Step through each object in the string list.
   // This string list could contain any valid string
   // characters and doesn't need to be limited to
   // object ID's.
   echo("-- Starting string list processing");
   for (%i=0; %i<%count; %i++)
   {
      // Get the object ID from the string list
      %id = getWord(%objects, %i);
      
      // Perform some action on the object
      doSomething(%id);
   }
   echo("-- Finished string list processing");
}

Start up our game under the My Projects directory and load the Empty Terrain level. Open the console using the tilde (~) key and enter the following at the bottom of the screen:

parseStringList2();

In the console we will see the following output:

==>parseStringList2();
-- Starting string list processing
Processing object ID: 1121
Processing object ID: 1122
Processing object ID: 1438
Processing object ID: 1643
Processing object ID: 2025
Processing object ID: 1118
Processing object ID: 1564
-- Finished string list processing

The results end up being the same as when we used the foreach$() function. So why would we use this method over the foreach$() method? Well, for one thing, we will see this pattern in a number of stock Torque 3D scripts that were written prior to foreach$() being added to the TorqueScript language. We will also see this pattern in a lot of game developers' script code, just because they are not aware of the newer foreach$() function (now you are one of the special ones that do know!).

One advantage of foreach$() over using the getWordCount() and getWord() patterns to step through a list‑‑other than a lot less script code‑‑is that you don't have to perform two calls into the engine (getWordCount() and getWord()); every call we don't have to make back to the engine is a performance increase.

But then why would we actively use this alternative pattern at all? It is the only way to work with the other types of delimiters, such as tab and a new line. By replacing getWordCount() and getWord() with getFieldCount() and getField()respectively, not spaces but only tabs and new lines are treated as delimiters, and by replacing them with getRecordCount() and getRecord(), neither spaces nor tabs, but only new lines are treated as delimiters. This allows us to work with different types of data.

We will be adding a new TorqueScript function to a project based on the Torque 3D Full template and try it out using the Empty Terrain level. If you haven't already, use the Torque Project Manager (Project Manager.exe) to create a new project from the Full template. It will be found under the My Projects directory. Then start up your favorite script editor, such as Torsion, and let's get going!

We are going to write a TorqueScript function that will demonstrate how to retrieve components of a variable using the special accessors as follows:

TorqueScript provides two sets of convenience accessors to help work with components of a variable. The first set is x, y, z, and w. This set is most often used with the x, y, and z components of position and vector variables; and we will nearly always use the first three accessors, ignoring the w accessor. The second set is r, g, b, and a, which correspond to the red, green, blue, and alpha components of a variable containing color information.

Behind the scenes, whenever we use one of these special accessors, TorqueScript is retrieving the corresponding space-delimited field within the variable. So the x and r accessors refer to the first field, the y and g accessors refer to the second field, and so on.

This also means that the positional/vector accessors and color accessors can be freely mixed together. For example, the red component of a color variable may just as easily be retrieved using the x accessor, and the alpha component may be retrieved with the w accessor. This also works the other way round with the components of a vector retrieved using the color accessors. We can see this in action by copying the following function at the end of the game/scripts/server/game.cs script file:

function variableAccessors2()
{
   // Define a vector in the form of "x y z w"
   %vector = "1 0 0 1";
   
   // Print out each xyzw component to the console
   echo("Vector X: " @ %vector.x);
   echo("       Y: " @ %vector.y);
   echo("       Z: " @ %vector.z);
   echo("       W: " @ %vector.w);
   echo("\n");
   
   // Print out each rgba component to the console
   echo("Vector R: " @ %vector.r);
   echo("       G: " @ %vector.g);
   echo("       B: " @ %vector.b);
   echo("       A: " @ %vector.a);
}

Start up our game under the My Projects directory and load the Empty Terrain level. Open the console using the tilde (~) key and enter the following at the bottom of the screen:

variableAccessors2();

In the console we will see the following output:

==>variableAccessors2();
Vector X: 1
       Y: 0
       Z: 0
       W: 1


Vector R: 1
       G: 0
       B: 0
       A: 1

The results demonstrate that we can retrieve components of a variable using either set of accessors.

We will be adding a new TorqueScript function to a project based on the Torque 3D Full template and try it out using the Empty Terrain level. If you haven't already, use the Torque Project Manager (Project Manager.exe) to create a new project from the Full template. It will be found under the My Projects directory. Then start up your favorite script editor, such as Torsion, and let's get going!

We are going to write a TorqueScript function that will iterate through the objects of a SimSet or SimGroup collection as follows:

The foreach() function (which is different than the foreach$() function that is used to parse space-delimited strings) is used to iterate through a SimSet or SimGroup collection in order to retrieve one SimObject instance at a time and perform some operation on it. In this example, the ID and class name of object are output to the console.

The foreach() function is different than most of the looping TorqueScript functions (such as for()), in that it takes two parameters that are separated by the word in rather than a semicolon. It is also unusual in that it creates a new variable to hold the current SimObject instance (the %obj variable in our previous example). The foreach() function has the following form:

foreach( object in simgroup)
{
   ... Do something with object ...
}

Here, the simgroup parameter is the collection of objects to be processed (could also be a SimSet parameter), and the object parameter is a new variable that is created to hold the current SimObject instance. It is the object variable that we do work on.

An alternative method to access a object collection of a SimSet or SimGroup parameter is to use a standard for() loop and getObject() method of the collection. For example, put the following function at the end of the game/scripts/server/game.cs script file, following the code we entered in the foreach() example:

function iterateSimGroup2()
{
   // Get the number of objects in the SimGroup
   %count = MissionGroup.getCount();
   
   // Iterate through the MissionGroup
   for (%i=0; %i<%count; %i++)
   {
      // Retrieve the object
      %obj = MissionGroup.getObject(%i);
      
      // Print some information about the object in the group
      echo(%obj.getId() SPC %obj.getClassName());
   }
}

Start up our game under the My Projects directory and load the Empty Terrain level. Open the console using the tilde (~) key and enter the following at the bottom of the screen:

iterateSimGroup2();

In the console we will see the following output:

==>iterateSimGroup2();
4275 LevelInfo
4276 ScatterSky
4277 TerrainBlock
4278 SimGroup

The results end up being the same as when we used the foreach() function. There is no real advantage of using this method over the foreach() method. We do often see this pattern in a number of stock Torque 3D scripts that were written prior to foreach() being added to the TorqueScript language. We will also see this pattern in a lot of game developers' script code just because they are not aware of the newer foreach() function (now you are one of the special ones that do know!).

We will be adding a new TorqueScript function to a project based on the Torque 3D Full template and try it out using the Empty Terrain level. If you haven't already, use the Torque Project Manager (Project Manager.exe) to create a new project from the Full template. It will be found under the My Projects directory. Then start up your favorite script editor, such as Torsion, and let's get going!

We are going to write a TorqueScript function that will demonstrate how to retrieve a random SimObject instance from a SimSet or SimGroup collection as follows:

The getRandom() method of a SimSet and SimGroup collection returns a randomly selected SimObject ID from the collection. If the collection is empty, a value of -1 is returned.

We will be adding a new TorqueScript function to a project based on the Torque 3D Full template and try it out using the Empty Terrain level. If you haven't already, use the Torque Project Manager (Project Manager.exe) to create a new project from the Full template. It will be found under the My Projects directory. Then start up your favorite script editor, such as Torsion, and let's get going!

We are going to write a TorqueScript function that will demonstrate how to find a SimObject instance using its internal name as follows:

So that we may see the internal name search in action, we first create some SimObject instances and add them to a SimGroup collection. In our previous example we use the ScriptObject class for our SimObject instance. The ScriptObject class is the most basic SimObject derived class we can build from script, and can come in handy when we want an object that can hold arbitrary data. We give a unique value to the internalName property of each ScriptObject class.

With all of the objects and a group collection set up, we use the findObjectByInternalName() method of a SimGroup collection. This method is also available in a SimSet collection and has the following form:

foundObject = SimGroup.findObjectByInternalName( name, [searchChildren] );

Here, the name parameter is the internal name we wish to search for in the SimGroup collection, and the optional searchChildren parameter indicates the child collections should be searched when set to true (it is false by default). If a SimObject instance with its internalName property matches the requested name, it is returned. If no SimObject instance matches or there are none yet in the collection, 0 is returned.

Let's look at some additional ways to search for a SimObject class in a SimSet or SimGroup collection.

%object = MyGroup.findObjectByInternalName("name3", true);

%object = MyGroup->name2;

%object = MyGroup.findObjectByInternalName("name2");

MyGroup->name2.doSomething(true);

%object = MyGroup-->name2;

%object = MyGroup.findObjectByInternalName("name2", true);

MyGroup-->name2.doSomething(true);

We will be adding a new TorqueScript function to a project based on the Torque 3D Full template and try it out using the Empty Terrain level. If you haven't already, use the Torque Project Manager (Project Manager.exe) to create a new project from the Full template. It will be found under the My Projects directory. Then start up your favorite script editor, such as Torsion, and let's get going!

We are going to write a TorqueScript function that will demonstrate how to execute a method on all the SimObject instances in a SimGroup collection as follows:

The SimGroup and SimSet callOnChildren() methods automatically step through each child SimObject instance and if the requested method is valid on the object, it is called with the passed-in arguments. The callOnChildren() method has the following form:

SimGroup.callOnChildren( method, args… );

Here, the method parameter is the method to be called on each of the SimObject objects in the collection, and the args… parameter is actually a variable number of arguments that will be passed-in to the method. In our previous example we pass-in one argument, which is the name of the property we wish our method to process.

The callOnChildren() method doesn't just process the child SimObject instances that are part of a SimGroup or SimSet collection, it also traverses any child SimGroup or SimSet collection, and executes the method on their SimObject instances.

If we want to call a method only on all the SimObject objects that are the immediate children of a SimGroup or SimSet collection and not traverse through the hierarchy of the collection, we can use the callOnChildrenNoRecurse() method. It has the same form as callOnChildren() as follows:

SimGroup.callOnChildrenNoRecurse( method, args… );

We could modify the method call of the SimGroup collection from our previous example and replace it with callOnchildrenNoRecurse() as follows:

MyGroup.callOnChildrenNoRecurse(outputProperties, "myValue1"); 

With our particular example, we end up with the same output to the console, as there are no child SimGroup or SimSet objects that would be skipped by using callOnChildrenNoRecurse().

Creating a SimObject-based class is straightforward and there are a number of options available that we will look into later. Here we will create a ScriptObject instance, the simplest SimObject derived class, and assign it to a variable as follows:

%object = new ScriptObject();

We use the new keyword to create a new SimObject-based class, which returns the new object so it may be stored into a variable for future use.

There are a number of different options when it comes to creating a SimObject derived class. Let's take a look at them.

new Player(MyPlayer);

%pos = MyPlayer.getPosition();

new Player(MyPlayer)
    {
       datablock = SoldierDatablock;
       position = "0 0 10";
       size = "1 1 1";
       squad = "Bravo";
    };

new Player(MyPlayer2 : MyPlayer)
    {
       position = "2 0 10";
    };

Creating an internal name only SimObject instance is almost the same as creating an ordinary SimObject instance. The difference comes down to how we decorate the name we use. Here we will create a ScriptObject instance with an internal name, the simplest SimObject derived class, and assign it to a variable:

%object = new ScriptObject([MyScriptObject]);

By surrounding the name of the SimObject instance with square brackets, Torque 3D automatically sets the internalName property of object rather than its globally unique name. If we call the getName() method on our new ScriptObject instance, it will return an empty string. But if we call the getInternalName() method, MyScriptObject will be returned.

This shortcut to setting the internal name of a SimObject instance can be handy when working with GuiControl instances. The normal pattern works like the following:

new GuiWindowCtrl(MyDialog) {
   ... some properties here ...

   new GuiControl() {
      internalName = "control1";
      ... some properties here ...
   };
   new GuiControl() {
      internalName = "control2";
      ... some properties here ...
   };
};

With this pattern we have to set the internalName property of each GuiControl class manually. Using the special name decorators, the internalName property will be set automatically as follows:

new GuiWindowCtrl(MyDialog) {
   ... some properties here ...

   new GuiControl([control1]) {
      ... some properties here ...
   };
   new GuiControl([control2]) {
      ... some properties here ...
   };

Creating a Datablock instance is straight forward. Here we will create a StaticShapeData Datablock, one of many possible Datablock classes as follows:

datablock StaticShapeData(MyShapeData)
{
   category = "Scenic";
   shapeFile = "art/shapes/rocks/rock1.dts";
   computeCRC = true;
   isInvincible = true;
};

We use the datablock keyword when creating a new Datablock class object and always give it a unique global name. This name is used by other objects to reference this Datablock through the use of datablock property of the GameBase class.

If we happen to create two Datablock instances with the same global name but of different classes, then a Cannot Re-declare data block with a different class error is output to the console and nothing is done with the second Datablock instance. However, if the two global names and classes match, then all of the properties from the second Datablock instance are copied into the first.

There are a number of different things to keep in mind when it comes to creating a Datablock instance. Let's take a look at them.

Creating a singleton is straight forward. Here we will create a Material singleton, one of a number of SimObject classes that may be created as a singleton, as follows:

singleton Material(DECAL_scorch)
{
   baseTex[0] = "./scorch_decal.png";
   translucent = true;
   translucentBlendOp = None;
   translucentZWrite = true;
   alphaTest = true;
   alphaRef = 84;
};

We use the singleton keyword when creating a new SimObject class object that we want only one instance of, and always give a unique global name to it. Other than ensuring that only one instance of this object will exist, the creation process is exactly the same as when the new keyword was used.

We will be adding a new TorqueScript function to a project based on the Torque 3D Full template and try it out using the Empty Terrain level. If you haven't already, use the Torque Project Manager (Project Manager.exe) to create a new project from the Full template. It will be found under the My Projects directory. Then start up your favorite script editor, such as Torsion, and let's get going!

We are going to write a TorqueScript function that will demonstrate how to extend a SimObject instance using its class property as follows:

In the example code we create a ScriptObject instance and set its class property to MyExtensionClass1. This extends the namespace of the ScriptObject instances to include all the methods that are defined by this new class. We then create two methods for this new class: addValues() and newMethod(). The first method takes two parameters, adds them together, and returns the result. The second method takes no parameters and just outputs some information to the console.

Making use of these new methods is straight forward. We just call them on the object like any other method. The Torque 3D engine takes care of everything for us.

There is a lot more to know about working with the class property and extending the namespace of a SimObject instance. Let's take a look at these points.

SimObject.setClassNamespace( name );

result = SimObject.isInNamespaceHierarchy( name );

SimObject.setSuperClassNamespace( name );

function useClassProperty2()
{
   // Create a ScriptObject and define its class property.
   // The ScriptObject class is just a generic SimObject that
   // we can create in TorqueScript.
   new ScriptObject(MyScriptObj)
      {
         class = MyExtensionClass2;
      };
   
   // Get the name of our ScriptObject.  Normally this
   // would just return our globally unique name, but
   // our class namespace will change how this method
   // works.
   %result = MyScriptObj.getName();
   
   // Output the result the console
   echo("getName() returned: '" @ %result @ "'");
   
   // Clean up our object
   MyScriptObj.delete();
}

function MyExtensionClass2::getName(%this)
{
   // Call the parent method and obtain its result
   %result = Parent::getName(%this);
   
   // Return our modified result
   return "Our name is: " @ %result;
}

useClassProperty2();

==>useClassProperty2();
getName() returned: 'Our name is: MyScriptObj'

   // Call the parent method and obtain its result
   %result = Parent::getName(%this);

We will be adding a new TorqueScript function to a project based on the Torque 3D Full template and try it out using the Empty Terrain level. If you haven't already, use the Torque Project Manager (Project Manager.exe) to create a new project from the Full template. It will be found under the My Projects directory. Then start up your favorite script editor, such as Torsion, and let's get going!

We are going to write a TorqueScript function that will demonstrate how to retrieve the properties and methods of a SimObject instance using a variable as follows:

In the example code we first set up some ScriptObject objects to work with. We give each ScriptObject instance a global unique name and some data to hold. We then move on to step through each object and retrieve its data using a for() loop. We want to focus on this part as shown in the following code:

      // We will reference the object using its globally
      // unqiue name.  Build out that name here.
      %name = "MyScriptObj" @ (%i + 1);

Here we build up a string variable named %name using a constant string that is appended with a computed value. When put together, these give us a string that matches the global unique name of each ScriptObject instance. We then use this string variable to retrieve the data from the ScriptObject instance as follows:

      // Get a property's value from the ScriptObject.
      %value = %name.MyValue1;

Within the Torque 3D engine, any time we attempt to access a property or method using the dot (.) operator, the engine performs a search in the SimObject name dictionary based on the preceding variable. If the name is found in the dictionary, the property is retrieved or the method is executed. If the name is not found in the dictionary, an error is output to the console. Our previous example code performs the same lookup when executing the delete() method as follows:

      // Build the name of the object
      %object = "MyScriptObj" @ (%i + 1);
      
      // Delete the ScriptObject using its delete() method.
      %object.delete();

We will be adding a new TorqueScript function to a project based on the Torque 3D Full template and try it out using the Empty Terrain level. If you haven't already, use the Torque Project Manager (Project Manager.exe) to create a new project from the Full template. It will be found under the My Projects directory. Then start up your favorite script editor, such as Torsion, and let's get going!

We are going to write a TorqueScript function that will demonstrate how to programmatically call a SimObject method as follows:

Our example code first fills up an array with the methods we will call on the objects. It then loops though all the dynamically created objects in the scene and if an object derives from the SceneObject class, call our methods on it using the SimObejct call() method.

The SimObject call() method has the following form:

result = SimObject.call( method, args… );

Here, the method parameter is the method we want to call on the SimObject instance, and the args… parameter is actually an optional set of arguments to pass into method. The call() method returns the output as denoted by result of the method call, if any.

If the given method does not exist on the SimObject instance, an empty string is returned. No error will be output to the console.

If we are unsure whether a particular method exists on a SimObject instance, we can use the isMethod() method. It has the following form:

result = SimObject.isMethod( method );

Here the method parameter is the method name to search for, and result is either true or false depending on whether the method exists on the SimObject instance or not.

We will be adding a new TorqueScript function to a project based on the Torque 3D Full template and try it out using the Empty Terrain level. If you haven't already, use the Torque Project Manager (Project Manager.exe) to create a new project from the Full template. It will be found under the My Projects directory. Then start up your favorite script editor, such as Torsion, and let's get going!

We are going to write a TorqueScript function that will demonstrate how to programmatically call a function as follows:

Our example code chooses a particular function name to use based on a parameter passed into our function. It then uses the standard call() function to call the function by name, do something with the result, and return the result to the caller. The call() function has the following form:

result = call( function, args… );

Here the function parameter is the console function we want to call, and the args… parameter is actually an optional set of arguments to pass into function. The call() function returns the result denoted by the result parameter of the function call, if any.

If the given function does not exist, an empty string is returned. No error will be output to the console.

If we are unsure whether a particular function exists, we can use the isFunction() method. It has the following form:

result = isFunction( functionName );

Here the functionName parameter is the function name to search for, and result is either true or false, depending on whether the function exists or not.

We will be adding a new TorqueScript function to a project based on the Torque 3D Full template and try it out using the Empty Terrain level. If you haven't already, use the Torque Project Manager (Project Manager.exe) to create a new project from the Full template. It will be found under the My Projects directory. Then start up your favorite script editor, such as Torsion, and let's get going!

We are to write a TorqueScript function that will demonstrate how to use arrays as dictionaries as follows:

The code example first sets up a global array so we have some data to play with. Normally this sort of set up would be outside of the function we're using. Our global array is special in that each index is actually a string.

The getWeaponDamage() function then attempts to retrieve the given weapon from the array as follows:

   // Look up the damage amount
   %damage = $WeaponDamage[%weaponName];

If an empty string is returned, we know that the weapon name was not found in the array. We then provide some default damage value. If the weapon name was found in the array, we use its damage value.

Behind the scenes, TorqueScript is not actually creating any sort of traditional array to hold these values. When you use square brackets ([,]) to denote an array index, what actually happens is TorqueScript appends the index to the name of an array. So using our previous example, the definition for weapon damage of the rifle looks like the following:

$WeaponDamage["rifle"] = 6;

But what TorqueScript is doing behind the scenes looks like the following:

$WeaponDamagerifle = 6;

You can test this out yourself by typing the following line into the console after running our getWeaponDamage() function at least once:

echo($WeaponDamagerifle);

If you do this you will see 6 printed to the console as expected.

So in the end, accessing the index of an array is just a string lookup into the TorqueScript variable table.

We will be adding a new TorqueScript function to a project based on the Torque 3D Full template and try it out using the Empty Terrain level. If you haven't already, use the Torque Project Manager (Project Manager.exe) to create a new project from the Full template. It will be found under the My Projects directory. Then start up your favorite script editor, such as Torsion, and let's get going!

We are going to write a TorqueScript function that will demonstrate how to custom sort an ArrayObject as follows:

The example code begins by creating the ArrayObject instance that will be used to store some objects. It then steps through all the MissionGroup and MissionCleanup objects and stores any SceneObject instances it finds onto the array. The SimObject ID of the object is used as the key, and the class name of the object is used as the value.

With the array populated, we do an ascending sort using our custom sorting function, arraySortFunction1() as follows:

   // Sort the array's keys in ascending order using our
   // custom sort function.  This function will sort
   // all objects according to their world y position.
   %array.sortfk(arraySortFunction1);

The code then steps through the sorted array and prints the results to the console.

The critical component here is our custom sorting function, arraySortFunction1(). Each time the function is called, it passes two items to compare. As we're doing a key-based sort, the key of each item is passed to our sort function. When we created the array we placed SimObject ID of each SceneObject instance into the key, so we may now use the key to retrieve information about the SceneObject instance. In our case we get the world position of each object as follows:

   %posA = %a.getPosition();
   %posB = %b.getPosition();

The rule for the sorting function is that if item A is less than item B then return a value of -1. If item A is greater than B then return a value of 1. And if items A and B are equal, return a value of 0. It is up to our sorting function to determine what makes item A lesser than or greater than item B. In our example we're using world Y position of each object as follows:

   if (%posA.y < %posB.y)
      return -1;
   else if (%posA.y > %posB.y)
      return 1;
   else
      return 0;

We then end up with a nicely sorted list from the lowest Y position to highest Y position that we output to the console.

We will be adding a new TorqueScript function to a project based on the Torque 3D Full template and try it out using the Empty Terrain level. If you haven't already, use the Torque Project Manager (Project Manager.exe) to create a new project from the Full template. It will be found under the My Projects directory. Then start up your favorite script editor, such as Torsion, and let's get going!

We are going to write a TorqueScript function that will demonstrate how to schedule a method of a SimObject instance as follows:

The example code begins by creating a ScriptObject instance with a globally unique name of MyScheduleObject. This name is later used as the namespace for the method that will be scheduled. The example code then schedules the method using the SimObject schedule() method as follows:

   MyScheduleObject.eventId = 
      MyScheduleObject.schedule(250, myMethod, getRealTime());

The schedule() method has the following form:

eventID = SimObject.schedule( time, method, args… );

Here the time parameter is the delay in milliseconds before the method is executed, the method parameter is the name of the method on the SimObject instance to execute, and the args… parameter is actually a variable number of optional arguments that are passed to given method. The eventID value of the scheduled event is returned by schedule(), so that we may cancel the schedule before it is invoked.

The actual time it takes for the scheduled method to execute may be greater than the delay time requested. This can be due to a number of factors, such as current engine load. However, the delay will never be less than the requested time.

If the SimObject instance is deleted before the schedule has fired, the schedule will automatically be canceled. It is also possible to manually cancel a schedule by using the cancel() function. This function has the following form:

cancel( eventID ); 

Here the eventID parameter is the value returned by the schedule() method of the SimObject instance.

We will be adding a new TorqueScript function to a project based on the Torque 3D Full template and try it out using the Empty Terrain level. If you haven't already, use the Torque Project Manager (Project Manager.exe) to create a new project from the Full template. It will be found under the My Projects directory. Then start up your favorite script editor, such as Torsion, and let's get going!

We are going to write a TorqueScript function that will demonstrate how to schedule a function as follows:

The example code schedules our MyScheduleFunction using the schedule() function that has the following form:

eventID = schedule( time, SimObjectID, function args… );

Here, the time parameter is the delay in milliseconds before the function is executed. The SimObjectID parameter is an optional object to invoke this function on (or 0 if no object), the function parameter is the name of the function to execute, and the args… parameter is actually a variable number of optional arguments that are passed to the given function. The eventID parameter of the scheduled event is returned by schedule() so that we may cancel the schedule before it is invoked.

If a SimObject ID is provided to the schedule() function, the schedule essentially operates as if we used the SimObject schedule() method. If the SimObject ID is left as 0 then the function is invoked on its own.

The actual time taken for the scheduled method to execute may be greater than the delay time requested. This can be due to a number of factors, such as current engine load. However, the delay will never be less than the requested time.

It is possible to manually cancel a schedule by using the cancel() function. This function has the following form:

cancel( eventID ); 

Here the eventID parameter is the value returned by the schedule() function.

We will be adding a new TorqueScript function to a project based on the Torque 3D Full template and try it out using the Empty Terrain level. If you haven't already, use the Torque Project Manager (Project Manager.exe) to create a new project from the Full template. It will be found under the My Projects directory. Then start up your favorite script editor, such as Torsion, and let's get going!

We are going to write a TorqueScript function that will demonstrate how to work with packages as follows:

The example code first defines an ordinary function, printStuff1(). It just prints out four random numbers to the console. Then the code defines a package named ChangeItUP. A package is defined by using the package keyword followed by the name of the package. Any function or method that is defined within the curly braces of the package will override the same regular function or method when the package is activated. When a package is deactivated, the overridden functions and methods go back to their regular versions.

The unitTest1() function demonstrates this in action. It first invokes the regular printStuff1() function. Then the ChangeItUp package is activated. Now when printStuff1() is called, it is the one defined within the package that is used. Finally, the package is deactivated and the regular printStuff1() function is called.

The order in which the packages are activated and deactivated is important. When multiple packages are activated we have what is called the package stack. If the same function or method is defined across multiple packages and all of those packages are activated, the last package that was activated will be where the function or method is called.

If a package in the middle of the stack is deactivated, then all packages that were activated later in the stack (following the one we are about to deactivate) will also be deactivated.

To get a view of the current package stack use the getPackageList() function. This function returns a space-delimited list of all of the currently active packages, and in the order in which they were activated.