iTorque 2D - Torque Script Introduction

What is TorqueScript

TorqueScript (TS) is a proprietary scripting language developed specifically for Torque technology. The language itself is derived from the scripting language used for Tribes 2, which was the base technology that Torque evolved from. Scripts are written and stored in .cs files, which are compiled to a byte-code format and executed by the game binary. The game binary is a compiled executable program (.exe for Windows or .app OS X) written in C++.

The CS extension stands for "C Script," meaning the language is 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++.

Basic Usage

Like most other scripting languages, such as Python or Java Script, TorqueScript is a high-level programming language interpreted by iTorque 2D at run time. Unlike C++, you can write your code in script and run it without recompiling your game.

All of your interfaces can be built using the GUI Editor, which saves the data out to TorqueScript. The same goes for data saved by the World Editor or Material Editor. Most of the editors themselves are C++ components exposed and constructed via TorqueScript.

More importantly, nearly all of your game play programming will be written in TorqueScript: inventory systems, win/lose scenarios, AI, weapon functionality, collision response, game flow. All of these can be written in TorqueScript. The language will allow you to rapidly prototype your game without having to be programming expert or perform lengthy engine recompiling.

Scripting vs Engine Programming

TorqueScript is comprised of the core C++ objects needed to make your game. For example, you will use the PlayerData structure to create player objects for your game. This structure was written in C++:

C++ PlayerData Code

struct PlayerData: public ShapeBaseData {
   typedef ShapeBaseData Parent;
   bool renderFirstPerson;    ///< Render the player shape in first person


   mass = 9.0f;         // from ShapeBase
   drag = 0.3f;         // from ShapeBase
   density = 1.1f;      // from ShapeBase

Instead of having to go into C++ and create new PlayerData objects or edit certain fields (such as mass), PlayerData was exposed to TorqueScript:

Example TorqueScript PlayerData Code

datablock PlayerData(DefaultPlayerData)
{
   renderFirstPerson = true;

   className = Armor;
   shapeFile = "art/shapes/actors/gideon/base.dts";

   mass = 100;
   drag = 1.3;
   maxdrag = 0.4;

   // Allowable Inventory Items
   maxInv[Pistol] = 1;
   maxInv[PistolAmmo] = 50;
};

If you want to change the name of the object, the mass, the inventory, or anything else, just open the script, make the change, and save the file. When you run your game, the changes will immediately take affect. Of course, for this example you could have used the Datablock Editor, but you should get the point. TorqueScript is the first place you should go to write your game play code.

TorqueScript Editors

TorqueScript files are essentially text files. This means you have several editors to choose from. Some users prefer to use the stock OS text editors: Notepad on Windows or Text Edit on OS X. Others will use their programming IDEs (Interactive Development Environments), such as Visual Studio for Windows or Xcode on OS X. Third party applications are the most popular choice:

On Windows

Recommended:

Torsion - Torsion is undeniably the best TorqueScript IDE was developed by Torque veterans Sickhead Games. If you are developing on Windows, this is the first thing you should purchase after iTorque 2D. No other editor offers this level of quality and functionality:
- Integrated "One Click" script debugging.
- Full control over script execution via step and break commands.
- Advanced editor features like code folding, line wrapping, auto-indent, column marker, automatic bracket matching, and visible display of tabs and spaces.
- Goto line and text searching.
- ScriptSense updated dynamically as you type.
- Customizable syntax highlighting for TorqueScript.
- Unlimited undo/redo buffer.
- Code browser window for exploring both engine exports and script symbols in your project.

Alternatives:

Notepad++ - This is a free (as in "free speech" and also as in "free beer") source code editor and Notepad replacement that supports several languages.

UltraEdit - UltraEdit is a powerful disk-based text editor, programmer's editor, and hex editor that is used to edit TorqueScript, HTML, PHP, javascript, Perl, C/C++, and a multitude of other coding/programming languages.

On OS X

Recommended:

Xcode - Xcode is Apple's premiere development environment for Mac OS X. If you plan on modifying iTorque 2D's source code, you will need this anyway. Most developers at GarageGames use Xcode to modify their scripts on a Mac.

Text Edit - This is the OS X default text editor. With no bells or whistles, this is not the best editor you can use on OS X, but it is free and ships with the OS.

Alternatives:

TIDE - Torque Integrated Development Environment (TIDE) is a free, cross-platform IDE for Torque Game Engine scripting by Paul Dana and Stefan Moises. It is implemented in Java as a "plugin suite" for the jEdit text editor and contains plugins for syntax highlighting, function browsing, script debugging, etc.

Smultron - Smultron is a text editor written in Cocoa for Mac OS X Leopard 10.5 which is designed to be both easy to use and powerful.

Getting Started

Like the rest of the documentation, the TorqueScript guides should be read in order (from top to bottom in the table of contents). This means you should start by reading the Syntax Guide. If you have never written TorqueScript before, DO NOT SKIP the Syntax Guide.

The docs in the Simple Tutorials will provide you with working code meant to show off syntax and basic TorqueScript structures. This is where you will create, edit, debug, and execute your first scripts.

Finally, the Advanced Tutorials section will walk you through complex functionality and algorithms. These tutorials make full use of iTorque 2D's editors, input system, behaviors and TorqueScript. These examples will even get into game play mechanics.

If you simply need a quick reference while writing scripts, you can read through the TorqueScript Reference Guide.

Contents