Skip to content

Introduction {documentation scripting overview}

Jump to bottom
Luis Anton Rebollo edited this page Dec 5, 2013 · 1 revision

 

IMPORTANT

You can download and view the Full TorqueScript Manual by clicking here: TorqueScript Reference Manual


Note for Windows Users

Due to security measures, the OS may block the CHM after you download it. To unblock it, perform the following steps:

1. Locate CHM on your hard drive.
2. Right click on the CHM, and then click Properties.
3. At the bottom, click the "Unblock" button.
4. Apply and close the properties.

Note for OSX Users: There is no default CHM viewer installed with Mac OSX. There are several free options available for download:

What is TorqueScript

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 should not be confused with C# files.


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++.


Basic Usage

Like most other scripting languages, such as Python or Java Script, TorqueScript is a high-level programming language interpreted by Torque 3D 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, and game flow. All of these can be written in TorqueScript. The language will allow you to rapidly prototype your game without having to be a programming expert or perform lengthy engine recompiling.


Scripting vs. Engine Programming

As mentioned above, TorqueScript 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 effect. Of course, for this example you could have used the in-game 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 Torque 3D. 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.
    • Go to 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 premier development environment for Mac OS X. If you plan on modifying Torque 3D'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 plug-in suite for the jEdit text editor and contains plug-ins 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 Torque 3D's editors, networking structure, input system, 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.
Clone this wiki locally