Activating and deactivating a package

TorqueScript packages allow us to encapsulate functions and SimObject methods into chunks that may be turned on and off. Packages are often used to modify the behavior of standard code, such as for a particular game play type. In this recipe, we will learn how to create a package and then how to activate and deactivate 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 work with packages as follows:

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

   function printStuff1()
   {
      echo("Non-packaged printStuff1()");
      
      // Print out four random numbers to the console
      for (%i=0; %i<4; %i++)
      {
         echo("Number " @ %i @ ": " @ getRandom());
      }
   }
   
   //Start the definition of our package
   package ChangeItUp
   {
      function printStuff1()
      {
         echo("Packaged printStuff1()");
         
         // This version of the function just counts to 10
         %counter = "";
         for (%i=1; %i<=10; %i++)
         {
            %counter = %counter SPC %i;
         }
         
         echo(%counter);
      }
   };
   
   // This function will test everything out
   function unitTest1()
   {
      // Invoke the non-packaged function
      printStuff1();
      
      // Activate the package
      activatePackage(ChangeItUp);
      
      // Invoke what should be the packaged function
      printStuff1();
      
      // Deactivate the package
      deactivatePackage(ChangeItUp);
      
      // Now we should be back to the non-packaged
      // function
      printStuff1();
   }

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:

   unitTest1();
   

   In the console we will see the following output:

   ==>unitTest1();
   Non-packaged printStuff1()
   Number 0: 0.265364
   Number 1: 0.96804
   Number 2: 0.855327
   Number 3: 0.473076
   Packaged printStuff1()
    1 2 3 4 5 6 7 8 9 10
   Non-packaged printStuff1()
   Number 0: 0.982307
   Number 1: 0.639691
   Number 2: 0.278508
   Number 3: 0.888561
   

How it works...

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.

There's more...

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.