-
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 that uses a new sprite to print a message
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.
Local vs Global. Variables vs Objects.
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...