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