Using script arrays as dictionaries

Arrays are a common form of data structure found in nearly all programming languages. When working with an array, you start at a zero-based index and keep incrementing the index until the array is full. TorqueScript arrays are a little different, in that their index need not be consecutive, nor do they even need to be a number. In this recipe, we will learn how to use TorqueScript arrays to store and retrieve arbitrarily indexed data, sometimes referred to as dictionaries.

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 to write a TorqueScript function that will demonstrate how to use arrays as dictionaries as follows:

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

   function getWeaponDamage(%weaponName)
   {
      // Begin by defining some damage amounts for
      // various weapons.  Normally we would set this
      // up at the beginning of the game rather than
      // every time this function is called.
      $WeaponDamage["pistol"] = 2;
      $WeaponDamage["rifle"] = 6;
      $WeaponDamage["rocket"] = 12;
      
      // Look up the damage amount
      %damage = $WeaponDamage[%weaponName];
      
      // Check if the damage amount was found.  If not
      // then set it to some default value.
      if (%damage $= "")
      {
         // The damage was an empty string and was
         // therefore not found in our array.  Set it
         // to a default value.
         %damage = 1;
      }
      
      return %damage;
   }

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:

   getWeaponDamage("pistol");
   

   In the console we will see the following output:

   ==>getWeaponDamage("pistol");
   2
   

3. We can try another run with a different weapon by entering the following new command at the bottom of the screen:

   getWeaponDamage("rocket");
   

   In the console we will see the following output:

   ==>getWeaponDamage("rocket");
   12
   

4. We will also try a weapon that is not in the array as follows:

   getWeaponDamage("knife");
   

   In the console we will see the following output:

   ==>getWeaponDamage("knife");
   1
   

How it works...

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.

See also

• Using ArrayObject and custom script sorting callbacks