torque script
Skip this Video
Download Presentation
Torque Script

Loading in 2 Seconds...

play fullscreen
1 / 65

Torque Script - PowerPoint PPT Presentation

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

Torque Script

CIS 487/587

Bruce R. Maxim


scripting advantages
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
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
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
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
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
  • 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
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
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)
if then else
  • 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 - 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
// 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
Functions - 3

// recursive function

function echoRepeat (%echoString, %repeatCount)


if (%repeatCount > 0)



echoRepeat(%echoString, %repeatCount--);



// calling recursive function

echoRepeat("hello!", 5);

objects 1
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
Objects - 2

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


[existing_field0 = InitialValue0;]


[existing_fieldM = InitialValueM;]

[dynamic_field0 = InitialValue0;]


[dynamic_fieldN = InitialValueN;]


object 3
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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

con addvariable
  • 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
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
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
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
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
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
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
  • 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
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
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
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
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
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
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
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
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
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.