Torquescript overview

Michael Perry edited this page Feb 13, 2013 · 1 revision

Torque Logo

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 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 2D at run time. Unlike C++, you can write your code in script and run it without recompiling your game.

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 a programming expert or perform lengthy engine recompiling.

Scripting vs Engine Programming

The core C++ objects needed to make your game are exposed to TorqueScript through the script interpreter. For example, you will use the Sprite class to create image objects for your game. This class was written in C++:

class Sprite : public SpriteBase
{
    typedef SpriteBase Parent;

private:
    /// Render flipping.
    bool mFlipX;
    bool mFlipY;

public:
    Sprite();
    virtual ~Sprite();

    static void initPersistFields();
    virtual void copyTo(SimObject* object);

    /// Render flipping.
    void setFlip( const bool flipX, const bool flipY )  { mFlipX = flipX; mFlipY = flipY; }
    void setFlipX( const bool flipX )                   { setFlip( flipX, mFlipY ); }
    void setFlipY( const bool flipY )                   { setFlip( mFlipX, flipY ); }
    inline bool getFlipX( void ) const                  { return mFlipX; }
    inline bool getFlipY( void ) const                  { return mFlipY; }

    virtual void sceneRender( const SceneRenderState* pSceneRenderState, const SceneRenderRequest* pSceneRenderRequest, BatchRender* pBatchRenderer );

    /// Declare Console Object.
    DECLARE_CONOBJECT( Sprite );

protected:
    static bool writeFlipX( void* obj, StringTableEntry pFieldName )        { return static_cast<Sprite*>(obj)->getFlipX() == true; }
    static bool writeFlipY( void* obj, StringTableEntry pFieldName )        { return static_cast<Sprite*>(obj)->getFlipY() == true; }
};

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

%fish = new Sprite()
{
    Animation = "AquariumToy:Angelfish";
    class = "FishClass";
    position = "0 0";
    size = "5 5";
    SceneLayer = "2";
    SceneGroup = "14";
    CollisionCallback = true;
};

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. 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 and was developed by Torque veterans Sickhead Games. If you are developing on Windows, this is the first thing you should purchase. 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 Torque 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.

To continue your TorqueScript education, see our TorqueScript Syntax Guide