Torquescript overview

What is TorqueScript?

TorqueScript (TS) is a scripting language developed specifically for Torque technology, and is MIT licensed along with the rest of the engine. 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 JavaScript, 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 effect. TorqueScript is the first place you should go to write your game play code.

Editors

TorqueScript files are plain text, so any text editor will do. What you want from one is syntax highlighting, since a .cs file with no coloring is hard going.

Visual Studio Code is the usual choice, and there are TorqueScript extensions for it: TorqueScript on the VS Code Marketplace and zfbx/TorqueScript, which adds snippets as well as highlighting. Both were written for Torque3D but the language is the same, so they work here.

One gotcha worth knowing: TorqueScript uses the .cs extension, which is also C#'s. Installing a TorqueScript extension will override C# highlighting for every .cs file you open. If you write C# on the same machine, that's the trade — most people either accept it or turn the extension on per workspace.

Anything else works too. Notepad++ and Sublime Text are both fine, and if you are already building the engine you will have Visual Studio or Xcode open anyway, either of which can edit script perfectly well.

The tool you will actually lean on is the in-engine console, opened with Ctrl + Tilde (~), where you can inspect objects, call methods and echo values while the game runs. See the Console Guide. A remote script debugger is built in too, but it needs a client at the other end and the IDE that provided one is gone, so the console is what most people use.

Where to go next

• TorqueScript Syntax — the language itself: variables, control flow, functions, objects.
• Callbacks — every hook the engine will call on your objects.
• TORQUE_SCRIPT.md in the engine repository — how to organize a project's script so it stays navigable as it grows. Recommendations rather than rules, but the shipped modules follow them.