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.
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 demonstrate how to work with packages as follows:
Open the
game/scripts/server/game.csscript 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(); }Start up our game under the
My Projectsdirectory and load theEmpty Terrainlevel. 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
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.
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.