Torque script
1 / 65

Torque Script - PowerPoint PPT Presentation

  • Updated On :

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

I am the owner, or an agent authorized to act on behalf of the owner, of the copyrighted work described.
Download Presentation

PowerPoint Slideshow about 'Torque Script' - stillman

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 l.jpg

Torque Script

CIS 487/587

Bruce R. Maxim


Scripting advantages l.jpg
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 l.jpg
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 l.jpg
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);

Syntax l.jpg

  • 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 l.jpg
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 l.jpg

  • 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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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)

Arrays l.jpg

  • 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

Vectors l.jpg

  • 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)

Operators l.jpg

  • 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)

If then else l.jpg

  • Brackets optional for single line statements

  • Nested if-then-else statements are allowed

  • Example


    { statements; }


    { alternate statements; }

Switch l.jpg



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


Slide17 l.jpg

  • Examples

    for(expression0; expression1; expression2)

    { statement(s); }

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




While l.jpg

  • Examples


    { statements; }

    %count = 0;

    while (%count < 5)





Functions 1 l.jpg
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

Functions 2 l.jpg

// 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 l.jpg
Functions - 3

// recursive function

function echoRepeat (%echoString, %repeatCount)


if (%repeatCount > 0)



echoRepeat(%echoString, %repeatCount--);



// calling recursive function

echoRepeat("hello!", 5);

Objects 1 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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.

Addfield43 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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

Con addvariable l.jpg

  • 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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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);

Con setlocalvariable l.jpg

  • 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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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 l.jpg
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;


Namespaces l.jpg

  • 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 l.jpg
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 l.jpg
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.