Using a variable to access methods or properties of a SimObject instance

Sometimes we don't know the global unique name of a SimObject instance or its ID when writing our script code. We may need to look up the name or ID, or even compute it. In these cases, we need to be able to reference a SimObject instance using a variable and in this recipe, we will learn how to do just that.

Getting ready

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!

How to do it...

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:

1. Open the game/scripts/server/game.cs script file and add the following code to the bottom:

   function variableObjectAccess1()
   {
      // Build some ScriptObjects to work with.
      // The ScriptObject class is just a generic SimObject that
      // we can create in TorqueScript.
      new ScriptObject(MyScriptObj1)
         {
            MyValue1 = "obj1";
         };
   
      new ScriptObject(MyScriptObj2)
         {
            MyValue1 = "obj2";
         };
   
      new ScriptObject(MyScriptObj3)
         {
            MyValue1 = "obj3";
         };
      
      // Access each ScriptObject using a computed variable
      for (%i=0; %i<3; %i++)
      {
         // We will reference the object using its globally
         // unqiue name.  Build out that name here.
         %name = "MyScriptObj" @ (%i + 1);
         
         // Get a property's value from the ScriptObject.
         %value = %name.MyValue1;
         
         // Print out to the console
         echo("ScriptObject " @ %name 
              @ " has a value of: " @ %value);
      }
      
      // Clean up our ScriptObejcts also using a computed
      // variable
      for (%i=0; %i<3; %i++)
      {
         // Build the name of the object
         %object = "MyScriptObj" @ (%i + 1);
         
         // Delete the ScriptObject using its delete() method.
         %object.delete();
      }
   }

2. 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:

   variableObjectAccess1();
   

   In the console we will see the following output:

   ==>variableObjectAccess1();
   ScriptObject MyScriptObj1 has a value of: obj1
   ScriptObject MyScriptObj2 has a value of: obj2
   ScriptObject MyScriptObj3 has a value of: obj3
   

How it works...

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();

See also

• Using call() to call a variable method on a SimObject instance with arguments