Torque script l.jpg
Sponsored Links
This presentation is the property of its rightful owner.
1 / 65

Torque Script PowerPoint PPT Presentation

  • Uploaded on
  • Presentation posted in: General

Torque Script. CIS 487/587 Bruce R. Maxim UM-Dearborn. Scripting Advantages. Useful for prototyping without recompilation Makes debugging easier Allows for game customization and tweaking Allows players to make their own total-mod based on an existing game structure

Download Presentation

Torque Script

An Image/Link below is provided (as is) to download presentation

Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author.While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server.

- - - - - - - - - - - - - - - - - - - - - - - - - - E N D - - - - - - - - - - - - - - - - - - - - - - - - - -

Presentation Transcript

Torque Script

CIS 487/587

Bruce R. Maxim


Scripting Advantages

  • Useful for prototyping without recompilation

  • Makes debugging easier

  • Allows for game customization and tweaking

  • Allows players to make their own total-mod based on an existing game structure

  • Any functional component that is not time critical can be written using scripting language rather than a compiled language

Necessary Features

  • Basic programming language features (variables, data types, control structures)

  • Access to engine-structures (rendering, audio, physics, AI, I/O, object management)

  • Familiar and consistent syntax

  • Object functionality (encapsulation, inheritance, polymorphism)

  • Dynamic scoping and memory management

  • Compilation of virtual machine “p-code”

Using the Console

  • Single script statements can typed in the console command line or an entire script can loaded from a file

  • The console window is opened by typing “~” once a Torque application is running

  • Ctrl-V allows pasting from clipboard into command line

  • The echo command can be used

    • echo(“Torque rocks”);

    • echo(1+1);


  • Torque is type insensitive

    • “1.2” == 1.2

  • Torque is case insensitive

    • $a == $A

  • The “;” is used as a statement terminator

    • $a = “a text string”;

Torque Features

  • Contains C++ arithmetic operators plus a few extra string operators

  • Control structures and function definition are similar to C++

  • Provides engine object inheritance and polymorphism

  • Supports use of Namespaces

  • On-demand loading and unloading of functions

  • Compiles and executes pcode


  • Variables do not need explicit declaration

  • Variable names begin with letter and contain any number of letters, digits, or “_”

  • Local and global variables

    • %local_var = value;

    • $global_var = value;

Basic Data Types

  • Numbers:

    • 123 (Integer)

    • 1.234 (floating point)

    • 1234e-3 (scientific notation)

    • 0xc001 (hexadecimal)

  • Strings

    • "abcd" (string)

    • 'abcd' (tagged string)

  • Booleans

    • true(1)

    • false(0)

Tagged Strings

  • Tagged strings have special numeric data associated with them

  • Tagged strings are used for sending strings across networks more efficiently

  • Tagged strings behave like normal strings

  • Tagged values can only be printed by detagging them after transmission

    • echo(“detagging example “ detag(‘$b’));

String Operations

  • Syntax

    • “string 1” op “string “

  • Operators

    • @ (concatenates two strings)

    • TAB (concatenation with tab)

    • SPC (concatenation with space)

    • NL (newline between strings)

String Escape Sequences

\n (newline)

\r (carriage return)

\t (tab)

\c0...\c9 (colorize subsequent text – predefined color)

\cr (reset to default color)

\cp (push current color on color stack)

\co (pop color from color stack)

\xhh (two digit hex value ASCII code)

\\ (backslash)


  • Example

    • $MyArray[n] (Single-dimension)

    • $MyMultiArray[m,n] (Multi-dimension)

    • $MyMultiArray[m_n] (Multi-dimension)

  • Refernces

    • $a != $a[0]

    • $a0 == $a[0]

    • $b[0,0]==$b0_0


  • Allow group of numeric values to be manipulated in sets of 3 or 4

  • Stored as strings, but interpreted as vectors

  • Torque provides a set of script operators for vectors

  • Example

    • “1.0 1.0 1.0 1.0” (4 element vector)


  • Boolean and arithmetic operators similar to those found in C++

  • The ++ and --operators are used only as postfix operators

  • The string comparison operators are

    • $= (test for string equality)

    • !$=(test for string inequality)


  • Brackets optional for single line statements

  • Nested if-then-else statements are allowed

  • Example


    { statements; }


    { alternate statements; }



case value0:



case value1: statements;





Switch only works for numeric expressions

Use switch$

The breaks are not really needed since Torque only executes one case



  • Examples

    for(expression0; expression1; expression2)

    { statement(s); }

    for(%count = 0; %count < 5; %count++)





  • Examples


    { statements; }

    %count = 0;

    while (%count < 5)





Functions - 1

  • Functions cannot have multiple prototypes (always keeps the most recently defined)

  • Torque does support the concept of packages to work around the duplicate name problem

  • Functions can be recursive

  • If functions are passed fewer actual parameters than the number the defined, the missing parameters will be assigned null string values

// function declaration

function echoRepeat (%echoString, %repeatCount)


for (%count = 0; %count < %repeatCount; %count++)

{ echo(%echoString); }


// function call from console or script

echoRepeat("hello!", 5);

Functions - 2

Functions - 3

// recursive function

function echoRepeat (%echoString, %repeatCount)


if (%repeatCount > 0)



echoRepeat(%echoString, %repeatCount--);



// calling recursive function

echoRepeat("hello!", 5);

Objects - 1

  • Every game item is considered an object

  • Even C++ objects are accessible via scripts

  • Every game object is assigned a numeric ID known as a handle

  • An objects may be assigned a name

  • Torque object data members are called as fields and functional methods are called commands

Objects - 2

%var = new ObjectType(Name : CopySource, arg0, ..., argn)


<datablock = DatablockIdentifier;>

[existing_field0 = InitialValue0;]


[existing_fieldM = InitialValueM;]

[dynamic_field0 = InitialValue0;]


[dynamic_fieldN = InitialValueN;]


Object - 3

  • %var- variable to hold object's handle

  • ObjectType- Is any class declared in the engine or in script that has been derived from SimObject or a subclass of SimObject.

  • Name (optional)- object's name.

  • CopySource (optional)- The name of an object which is previously defined somewhere in script.

    Note: If CopySource is of a different ObjectType than the object being created, only CopySource's dynamic fields will be copied.

Object - 4

  • arg0, ..., argn (optional)- comma separated list of arguments to the class constructor.

  • datablock- Many objects (those derived from GameBase, or children of GameBase) require datablocks to initialize specific attributes of the new object.

Object - 5

  • existing_fieldM- In addition to initializing values with a datablock, you may also initialize existing class members (fields) here.

    Note: In order to modify a member of a C++-defined class, the member must be exposed to the Console.

  • dynamic_fieldN- Lastly, you may create new fields (which will exist only in Script) for your new object. These will show up as dynamic fields in the World Editor Inspector.

Object - 6

// create a SimObject w/o modifying any fields

$example_object = new SimObject();

// create a SimObject w/ dynamic fields

$example_object = new SimObject()


a_new_field = "Hello world!";


Object - 7

// create a StaticShape using a datablock

datablock StaticShapeData(MyFirstDataBlock)


shapeFile = "~/data/shapes/player/player.dts";

junkvar = "helloworld";


new StaticShape()


dataBlock = "MyFirstDataBlock";

position = "0.0 0.0 0.0";

rotation = "1 0 0 0";

scale = "1 1 1";


Using Objects

// assuming the existence of a player called myGuy

// you could type the following in from the Console

$player_name = "myGuy";

$player_id = $player_name.getID();




Dynamic Fields - 1

  • Are associated with specific instances of an object type

  • There are allocated as referenced

  • Assigning a value to field that does not exist creates a new field

  • Trying to read a field that does not exist does not create a new field and a null string is returned

Dynamic Fields - 2

// new_var will not be created because we are only

// 'reading' it


// new_var2 will be created and initialized to "Hello”

$player_id.new_var2 = "Hello";


Console Functions - 1

function Classname::func_name(%this,[arg0],...,[argn])



return val; // optional


The syntax breaks down as follows:

  • function- Is a keyword telling TorqueScript we are defining a new function.

  • ClassName::- Is the class type this function is supposed to work with.

  • func_name- Is the name of the function we are creating.

Console Functions - 2

  • %this- Is a variable that will contain the handle of the 'calling object'.

  • ...- Is any number of additional arguments.

    function Player::hi(%this)


    echo("Player Hello ", %this);



    // assuming Player handle is 1000 we can call


Console Functions - 3

  • We can force Torque to call a specific instance using


  • New console function definitions override previous definitions with same name

  • Console functions (scripts and packages) can be loaded using the exec command


Packages - 1

  • Provide dynamic function polymorphism

  • Function definitions from active packages override current function definitions

  • Functions can appear in multiple packages

  • Functions can be packaged datablocks can not be packaged

Packages - 2

function demo()

{ echo("Demo definition 0"); }

package DemoPackage1


function demo()

{ echo("Demo definition 1"); }


package DemoPackage2


function demo()

{ echo("Demo definition 2"); }


Packages - 3

  • To make use of specific functions

    demo(); // original version


    demo(); // package 1 version


    demo(); // package 2 version


    demo(); // package 1 version


    demo(); // original version

Engine-Console Interface - 1

  • C++ Variable

    • variable not associated with any class.

  • C++ Function

    • function is not associated with any class.

  • Member

    • A variable defined in a C++ class.

  • Method

    • A routine defined and declared in a C++ class.

Engine-Console Interface - 2

  • Local or Global Variable

    • A variable in the Console.

    • Global variables may be defined in C++ and linked to a global engine variable.

    • Allowed C++ modifiers: const, static.

  • Function

    • A routine in the Console not associated with any particular namespace.

    • May be defined entirely in script or C++.

Engine-Console Interface - 3

  • Field

    • A variable associated with an object in the Console.

    • Linked with a Member.

  • Dynamic Field

    • A variable associated with an object in the Console.

    • Exists only in the Console.

Engine-Console Interface - 4

  • Command (deprecated)

    • A routine associated with a particular namespace in the Console.

    • Linked with an existing Method.

    • Console Commands are deprecated-- that is, they should no longer be used. Information on them is provided for reference only.

  • Console Method

    • A routine associated with a particular namespace in the Console.

    • Exists only the Console.

addField( )

  • This function allows you to link C++ class Members to console object Fields.

  • The rules for using this function are

  • Member to be exposed must be non-dynamic (i.e. not a pointer).

  • Member to be exposed must be non-static.

  • addField() statements must be included in the class initPersistFields( ) method.

addField( )

void ConsoleObject::addField

(const char*in_pFieldname, // console var name

const U32 in_fieldType, // from consoleTypes.h

const dsize_t in_fieldOffset, // calc by Offset()

const char* in_pFieldDocs) // text field description

void ConsoleObject::addField

(const char* in_pFieldname,

const U32 in_fieldType,

const dsize_t in_fieldOffset,

const U32 in_elementCount, // # elements at offset

EnumTable *in_table, // table of enum values

// and strings

const char* in_pFieldDocs)

addFieldV( )

  • Specialized version does not handle enums

  • Supports use of validator functions

    void ConsoleObject::addFieldV

    (const char* in_pFieldname,

    const U32 in_fieldType,

    const dsize_t in_fieldOffset,

    TypeValidator *v) // pointer to TypeValidator

    // class

Macros -1

  • addField() variants used to give a console field the same name as class member

    #define addNamedField


    \ addField(#fieldName, type,


    #define addNamedFieldV

    (fieldName,type,className, validator)

    \ addFieldV(#fieldName, type,

    Offset(fieldName,className), validator)

Macros - 2

  • Offset macro calculate position of variable in bytes from beginning of class in memory

    Offset(VariableName, // C++ class member name to

    // expose to console

    ClassName) // name of C++ class

removeField( )

  • Lets you unlink a member-field pairing

  • Can be used to hide information form player (e.g. not allow position calls for Terrain data)

    bool ConsoleObject::removeField

    (const char* in_pFieldname)

    // in_pFieldname is string specifying string to

    // be removed


  • This function allows you to expose a global C++ variable or a static Member as a global variable in the console. (See


    (const char *name, // string specifying global

    // console variable

    S32 t, // variable type from

    // consoleTypes.h

    void *dp); // point to C++ global

    // variable or static

    // member

ConsoleMethod - 1

  • This is a macro that allows you to create a new Console Method from C++.

  • Used to replace clumsy addCommand() calls.

  • The static variant of ConsoleMethod is for methods that you want to call statically. For example, 'GameConnection::getServerConnection()'.




ConsoleMethod - 2


(className, // class owning C++ method

scriptname, // method name inside console

returnType, // method return type

minArgs, // mini # method arguments

// method name is 1st and handle

// is 2nd

maxArgs, // max # arguments, 0 means any

// number of args can be passed

usage) // help statement used is wrong

// number of args are passed

// in call

ConsoleMethod - 3

// From

// Calls a methos getID() which returns a

// 32 bit value


(SimObject, getId, S32, 2, 2, "obj.getId()")




return object->getId();


ConsoleFunction - 1

  • This is a macro that allows you to create a new Console Function from C++.

  • Ex:


    (name, // console name for function

    returnType, // function return type

    minArgs, // function name passed as 1st

    maxArgs, // 0 means any number

    usage) // help statement for error

ConsoleFunction - 2

// From

// Creates a console function that can be used

// to call the C++ function Sim::getCurrentTime


( getSimTime, S32, 1, 1,

"getSimTime() - Time since game started.")


return Sim::getCurrentTime();


Con::getLocalVariable( )

  • This function allows you to get the contents of a local variable in the console from within the engine.

  • Note: The value is returned as a char string.

    const char *Con::getLocalVariable

    (const char* name);


  • This function allows you to set the contents of a local variable in the console from within the engine.

  • Note: all values passed as char strings to the console. The console automatically converts this information as necessary.


    (const char *name, const char *value);

Console Printing Functions

  • These functions provide the ability to print various levels of information into the console (or log if logging is enabled).

  • *_format is a standard C format string

    Con::printf(const char *_format, ...);


    (ConsoleLogEntry::Type type, const char *_format, ...);


    (ConsoleLogEntry::Type type, const char *_format, ...);

Datablocks - 1

  • Objects placed in the game world will fall into three broad categories:

    • The object does not have much associated data and/or has few parameters.

    • The object does have a lot of parameters, but these parameters are likely to be unique, or must be allowed to be unique, between instances of the object.

    • The object has a lot of data or parameters, but it is OK for these datum/parameters to be shared between instances.

Datablocks - 2

  • The first two categories fit the class of objects that do not need and are therefore not created from datablocks.

  • The third category fits the class of objects that could benefit from using datablocks. Why?

    • Unlike normal objects, you are only allowed to have a single instance of any datablock.

    • Furthermore, objects that are created from datablocks all share the same instance of that datablock.

Creating Datablock Objects - 1

  • The following creates a StaticShape object named TestTarget that uses SimpleTarget0 to initialize the object’s datablock

    new StaticShape(TestTarget)


    position = "0 0 0";

    rotation = "1 0 0 0";

    scale = "1 1 1";

    dataBlock = "SimpleTarget0";


Creating Datablock Objects - 2

  • The following uses inheritance to create a StaticShape object named TestTarget2

    new StaticShape(TestTarget2: TestTarget)


    position = "0 10 0";


Declaring Datablocks - 1

  • Similar to declaring console objects

    datablock DataBlockType(Name [: CopySource])


    category = "CategoryName";

    [datablock_field0 = Value0;]


    [datablock_fieldM = ValueM;]

    [dynamic_field0 = Value0;]


    [dynamic_fieldN = ValueN;]


Declaring Datablocks - 2

// Creates MyTargets and specifies that it should be

// located in the Targets folder in the World Editor tree

datablock StaticShapeData(MyTargets)


category = "Targets";

shapeFile = "~/data/shapes/targets/simpletarget0.dts";


// Inherits all data from MyTargets and adds new variable

// StartHidden with initial value 1

datablock StaticShapeData(SimpleTarget0 : MyTargets)


StartHidden = 1;



  • There is a Namespace for every Torque object

  • Namespaces are chained

  • Search to resolve names begins with the current object namespace and then works recursively upwards through the parent’s namespace

Object Namespace - 1

function GameBase::doIt(%this)


echo("Calling StaticShape::doIt() ==> on object“

SPC %this);


// since doIt is declared in GameBase namespace or

// its children

%myTarget = new StaticShape(CoolTarget)


position = "0 0 0";

dataBlock = "SimpleTarget1";



Object Namespace - 2

  • When doIt( ) is called, you do not need to pass an argument explicitly, the console uses the argument object tag if we do not

  • The one argument doIt( ) uses is named %this.

    Please note:

  • in the cases where we use the name of the object, the name will be passed as the ID. Torque automatically does lookups for names

  • thus in most cases, names can be used interchangeably with IDs, as long as the names are unique.

  • Login