-
Notifications
You must be signed in to change notification settings - Fork 1.5k
Scripting Tutorial
This guide will take you through the process of creating a basic script for Torque 2D.
The following guide(s) are recommended before you begin this tutorial:
The following guide(s) are useful to have available while completing this tutorial:
What you need
- A local checkout of of Torque 2D
- A text editor. Generally, any text editor will work fine as long as it does not introduce whitespace symbols. Avoid any advanced word processor, such as Microsoft Word. Recommended editors include, but are not limited to:
- Windows: Torsion, Notepad++, Visual Studio
- OS X: Xcode, TextWrangler, TextEdit (in "no formatting" mode)
When talking about creating or editing a script for Torque 2D, this always translates to a TorqueScript file. TorqueScript (TS) is a proprietary scripting language developed specifically for Torque technology. The language itself is derived from the scripting used for Tribes 2, which was the base tech Torque evolved from.
Scripts are written and stored in .cs files, which are compiled and executed by a binary compiled via the C++ engine (.exe for Windows or .app OS X). The CS extension stands for "C Script," meaning the language resembles C programming. Though there is a connection, TorqueScript is a much higher level language which is easier to learn than standard C or C++.
This file format should not be confused with Microsoft's C#, which also uses a .cs extension. The two languages are completely unrelated. If you have C# editing software installed, such as Visual Studio, there will be a conflict when opening a TorqueScript file. It's up to you to manage what programs should open a .cs file.
Using Windows file system to create a TorqueScript file.
Using Torsion to create a TorqueScript file.
Using OS X file system to create a TorqueScript file.
Now that we have a script, the first step you should always take is executing the file. Sometimes you will see this mentioned as "exec'ing".
Without executing, Torque will not use any code that will be written in the new script. All you need to know is the function call and path to the script. The example in this tutorial has created myScript.cs in the modules/SpriteToy/1 directory. The following code is called at the very top of the SpriteToy::create function:
function SpriteToy::create( %this )
{
// Execute the script. In this example, the file is in the same
// as the directory as this script.
exec("./myScript.cs");
// ...rest of function is unchanged
}Now, all the code you write in your script will be loaded in Torque. Let's add some code now.
Much of your TorqueScript experience will come down to calling existing functions and writing your own. Functions are a blocks of code that only execute when you call them by name.
There are essentially two types of functions: global and object method. The simplest function is a stand-alone global. Add the following to your script (myScript.cs in this example):
// Global function used to print the message "Hello World"
function helloWorld()
{
// Call the echo function with the phrase "Hello World"
echo("Hello World!");
}The above code demonstrates the following important concepts:
- Proper TorqueScript syntax
- A global
functionstructure - Commenting
- Calling a ConsoleFunction that was written in C++ previously
The function keyword, like other TorqueScript keywords, is case sensitive. If you were to use Function, your code would not work. Comments start with the // syntax. Any text on the same line as the comment will be ignored by the TorqueScript processor. These are useful for providing information about your code, so you should comment as often as possible.
A ConsoleFunction is a global function written in C++, then exposed to TorqueScript. You should never try to create a script version, such as function echo(). You will have bad results.
Your function is now ready to use. You can call it at any point after your script has been executed. For example, the following code in myScript.cs shows the call:
function SpriteToy::create( %this )
{
// Execute the script. In this example, the file is in the same
// as the directory as this script.
exec("./myScript.cs");
// Call the new function
helloWorld();
// ...rest of function is unchanged
}Your console should output "Hello World" after the function is called. Now, let's say you want to change the text that is printed to the console. You could change the line of code that has "Hello World", or you can pass in a parameter. Change helloWorld to the following:
// Global function used to print text to the console
/// %message - The text you wish to print
function helloWorld(%message)
{
// Call the echo function, passing %message as the argument
echo(%message);
}Now that the function signature has changed, you need to update your call back. Change that code to the following:
function SpriteToy::create( %this )
{
// Execute the script. In this example, the file is in the same
// as the directory as this script.
exec("./myScript.cs");
// Call the new function
helloWorld("Hello World");
// ...rest of function is unchanged
}The above is just an example of passing a parameter. You can pass whatever text you want, making your helloWorld function more flexible. Now that variables and arguments are being introduced, we should cover scope.
Next, let's make some changes to the helloWorld function. Change the code to the following:
// Global function used to print the message "Hello World"
function helloWorld()
{
// Store the text in a local variable
%myVariable = "Hello World";
// Call the echo function, passing %myVariable as the value
echo(%myVariable);
}The %myVariable = "Hello World"; demonstrates storing a value in a local variable. That variable is then used by the echo function to print a message. As soon as the function finishes executing, %myVariable and its value will be lost. It will no longer consume memory or be usable. If you want your variable to exist outside of the helloWorld function, use a global variable:
// Global function used to print the message "Hello World"
function helloWorld()
{
// Store the text in a global variable
$MyVariable = "Hello World";
// Call the echo function, passing $MyVariable as the value
echo($MyVariable);
}The above code stores the value in $MyVariable, which is a global variable. Even after the function finishes executing, you can access and manipulate $MyVariable. The a global variables impact on memory and performance is next to nothing.
Proper scoping is much more important when dealing with objects. For example, change the helloWorld function body to do the following:
// Global function that creates a single ScriptObject
function helloWorld()
{
// Store the text in a global variable
%myObject = new ScriptObject();
}The %myObject local variable will store the ID of the new ScriptObject. Once the function finishes, the local variable goes away. You can no longer access it by name. However, the ScriptObject will continue to exist outside of the function. If you know its ID or name, you can access it after the helloWorld function is called. This is extremely important to remember.
If you do not want an object to exist outside of a function, you will have to delete it before the function finishes or you will essentially have a "memory leak." You can always delete the object outside of the function, if you know the name or ID. However, unless you are tracking that some how, you will be hard pressed to do so.
In addition to the creation of stand-alone functions, TorqueScript allows you to create and call methods attached to objects. The first step is to create a namespace for your object. The two most common ways of doing achieving this is by giving an object a name or assigning a class.
Some of the more important ConsoleMethods are already written in C++, then exposed to script. When you want functionality not provided out of the box, you can add script based functions to objects.
Functions called from the engine source.
Isolating code to packages.
Finally...