Retrieving components of a variable using accessors

Under TorqueScript position, vector, matrix, and color variables are all very similar. They are made up of a string with space-delimited components (or fields). For example, a position variable may be defined as follows:

// A position is of the form "x y z"
%position = "1.2 0.34 13.22";

TorqueScript provides a set of special accessors to work with these common types of variables. This allows us to access each individual component and manipulate it.

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 components of a variable using the special accessors as follows:

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

   function variableAccessors1()
   {
      // A position is of the form "x y z"
      %position = "23.0 2.35 9.78";
      
      // Print out each component to the console
      echo("Position X: " @ %position.x);
      echo("         Y: " @ %position.y);
      echo("         Z: " @ %position.z);
      echo("\n");
      
      // Add one to the position's y component
      %position.y += 1;
      
      // Print out each component to the console
      echo("New Position X: " @ %position.x);
      echo("             Y: " @ %position.y);
      echo("             Z: " @ %position.z);
      echo("\n");
      
      // Define a vector in the form of "x y z w"
      %vector = "1 0 0 1";
      
      // Print out each component to the console
      echo("Vector X: " @ %vector.x);
      echo("       Y: " @ %vector.y);
      echo("       Z: " @ %vector.z);
      echo("       W: " @ %vector.w);
      echo("\n");
      
      // A color is of the form "r g b a"
      %color = "128 0 128 255";
      
      // Print out each color component to the console
      echo("Color R: " @ %color.r);
      echo("      G: " @ %color.g);
      echo("      B: " @ %color.b);
      echo("      A: " @ %color.a);
      echo("\n");
      
      // Modify the color components
      %color.r += 64;
      %color.g += 64;
      %color.b = 0;
      
      // Print out each color component to the console
      echo("New Color R: " @ %color.r);
      echo("          G: " @ %color.g);
      echo("          B: " @ %color.b);
      echo("          A: " @ %color.a);
   }

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:

   variableAccessors1();
   

   In the console we will see the following output:

   ==>variableAccessors1();
   Position X: 23.0
            Y: 2.35
            Z: 9.78
   
   New Position X: 23.0
                Y: 3.35
                Z: 9.78
   
   Vector X: 1
          Y: 0
          Z: 0
          W: 1
   
   Color R: 128
         G: 0
         B: 128
         A: 255
   
   New Color R: 192
             G: 64
             B: 0
             A: 255
   

How it works...

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.

There's more...

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.

See also

• Accessing delimited fields within a string