Contents

Conventions

Throughout this document, for succinctness, I refer to the Torque Game Engine Scripting language simply as TorqueScript.


Language Features

TorqueScript is a typeless scripting language, with similarities in syntax to C/C++. In TorqueScript, you will find that most C/C++ operators work in the familiar way (with important exceptions, as noted here). Besides a subset of C/C++, TorqueScript provides:

  • Case-insensitive symbols; keywords false and FALSE are identical.
  • Auto creation and destruction of local/global variables and their storage.
  • String concatenation, comparison, and auto-string-constant creation (see Literals).
  • Function packaging.


Variable Names

TypeSyntaxExampleExplanation
Global
prefix $
$a
$a is a global variable
Local
prefix %
%b
%b is a local variable
Array
(Global
or Local)
postfix []
$MyArray[n]
Array
$MyMultiArray[n,m]
$MyMultiArrayn_m
Multi-dimensional array

Note: TorqueScript does not have support for arrays as such. Instead, the bracket notation is a shorthand for creating a variable name. $a[0] is synonymous with $a0, and $M[1,4] with $M1_4. You must not think of $a as the name of the array containing $a[5]. TorqueScript arrays provide the means for creating variable names dynamically: if $i is 5, then $a[$i] is synonymous with $a5.

Constants

TypeExampleExplanation
Boolean
TRUE
1
FALSE
0
Integer
123
decimal
0xabc
hexadecimal
Float
1.23
floating-point
1.00E-003
scientific notation
Note: If the float is less than 1, explicitly include the leading "0" before the ".", e.g., "0.2". Entering ".2" will not work in every circumstance.
Character
\n
newline
\r
carriage return
\t
tab
\c0 .. \c9
colorize subsequent console output
\cr
reset to default color
\cp
push color from color stack
\co
pop color from color stack
\xhh
two-digit hex value ASCII code
\\
backslash
\"
double-quotes
String
“Hello world”
Normal string
‘Torque Rocks’
A tagged string, as used in communication between client and server. The value of a tagged string is sent only once; subsequently, only the ‘tag’ is sent. Clients will store the string at an index identified by the ‘tag’ and can look up the value, avoiding the need for it to be sent repeatedly.
Vector
"1.0 2.0 1.0 2.0"
4-element vector

Note: TorqueScript does not have support for vectors as such. The vector exemplified here is simply a space-separated string. Space-, tab-, and newline-separated strings crop up in the calling sequence of certain functions, notably in the return value, which technically is a scalar, but may be a string that can be interpreted as a vector. See t2dSceneObject::getPosition(), resp. SimObject::getDynamicField().


Operators

Operator
Name
Example
Explanation
Arithmetic Operators
*
multiplication
$a * $b
Multiply $a and $b.
/
division
$a / $b
Divide $a by $b.
%
modulo
$a % $b
Remainder of $a divided by $b.
+
addition
$a + $b
Add $a and $b.
-
subtraction
$a - $b
Subtract $b from $a.
++
auto-increment
(post-fix only)
$a++
Increment $a. Note: ++$a is illegal.
Note: the value of $a++ is that of the incremented variable: auto-increment is post-fix in syntax, but pre-increment in sematics (the variable is incremented, before the return value is calculated). This behavior is unlike that of C and C++.
- -
auto-decrement
(post-fix only)
$b--
Decrement $b. Note: --$b is illegal.
Note: the value of $a-- is that of the decremented variable: auto-decrement is post-fix in syntax, but pre-decrement in sematics (the variable is decremented, before the return value is calculated). This behavior is unlike that of C and C++.
Relations (Arithmetic, Logical, and String)
<
Less than
$a < $b
1 if $a is less than % b (0 otherwise.)
>
More than
$a > $b
1 if $a is greater than % b (0 otherwise.)
<=
Less than or Equal to
$a <= $b
1 if $a is less than or equal to % b (0 otherwise.)
>=
More than or Equal to
$a >= $b
1 if $a is greater than or equal to % b (0 otherwise.)
==
Equal to
$a == $b
1 if $a is equal to % b (0 otherwise.)
!=
Not equal to
$a != $b
1 if $a is not equal to % b (0 otherwise.)
!
Logical NOT
!$a
1 if $a is 0 (0 otherwise.)
&&
Logical AND
$a && $b
1 if $a and $b are both non-zero (0 otherwise.)
||
Logical OR
$a || $b
1 if either $a or $b is non-zero (0 otherwise.)
$=
String equal to
$c $= $d
1 if $c equal to $d .
!$=
String not equal to
$c !$= $d
1 if $c not equal to $d.
Bitwise Operators
~
Bitwise complement
~$a
flip bits 1 to 0 and 0 to 1. (i.e. ~10b == 01b)
&
Bitwise AND
$a & $b
composite of elements where bits in same position are 1. (i.e. 1b & 1b == 1b)
|
Bitwise OR
$a | $b
composite of elements where bits 1 in either of the two elements. (i.e. 100b & 001b == 101b)
^
Bitwise XOR
$a ^ $b
composite of elements where bits in same position are opposite. (i.e. 100b & 101b == 001b)
<<
Left Shift
$a << 3
element shifted left by 3 and padded with zeros. (i.e. 11b << 3d == 11000b)
>>
Right Shift
$a >> 3
element shifted right by 3 and padded with zeros. (i.e. 11010b >> 3d == 00011b)
Assignment and Assignment Operators
=
Assignment
$a = $b;
Assign value of $b to $a.
Note: the value of an assignment is the value being assigned, so $a = $b = $c is legal.
op=
Assignment Operators
$a op= $b;
Equivalent to $a = $a op $b, where op can be any of:
* / % + - & | ^ << >>
String Operators
@
String concatenation
$c @ $d
Concatenates strings $c and $d into a single string. Numeric literals/variables convert to strings.
NL
New Line
$c NL $d
Concatenates strings $c and $d into a single string separated by new-line.
Note: such a string can be decomposed with getRecord()
TAB
Tab
$c TAB $d
Concatenates strings $c and $d into a single string separated by tab.
Note: such a string can be decomposed with getField()
SPC
Space
$c SPC $d
Concatenates strings $c and $d into a single string separated by space.
Note: such a string can be decomposed with getWord()
Miscellaneous
? :
Conditional
x ? y : z
Evaluates to y if x equal to 1, else evaluates to z.
[]
Array element
$a[5]
Synonymous with $a5.
( )
Delimiting,

Grouping
t2dGetMin(%a, %b)
if ( $a == $b )
($a+$b)*($c-$d)
Argument list for function call
Used with if, for, while, switch keywords
Control associativity in expressions
{}
Compound statement
(Block)
if (1) {$a = 1; $b = 2;}
function foo() {$a = 1;}
Delimit multiple statements
optional for if, else, for, while
Required for switch, datablock, new, function
,
Listing
t2dGetMin(%a, %b)
%M[1,2]
Delimiter for arguments
Note: there is no "comma operator", as defined in C/C++; $a = 1, $b = 2; is a parse error
::
Namespace
Item::onCollision()
This definition of the onCollision() function is in the Item namespace.
.
Field/Method selection
%obj.field
%obj.method()
Select a console method or field
//
Single-line comment
// This is a comment
Used to comment out a single line of code.
/* */
Multi-line comment
/*This is a a
multi-line
comment*/
Used to comment out multiple consecutive lines.
/* opens the comment, and */ closes it.