Note: Although keywords are not reserved, it is considered bad practice to use variables that have the same spelling as a keyword.

Purpose Use break to exit the innermost for or while loop. Unlike C and C++, break has no effect in a switch or switch$ statement.

%count = 0; 
while( 1 ) 
{  
   echo(%count++); 
   if (%count > 2) 
   break; 
}

See Also
for, while

Purpose Used to label cases in a switch or switch$ statement.
Syntax
case expression :(colon character)
The argument of the enclosing switch or switch$ statement is evaluated and compared to the value of expression using operator == or $=, respectively.
If true, execute the statements up to the next case statement and exit the switch.
If false, skip to the next case statement.
See Also
switch, switch$

Purpose Causes the script to skip to the next iteration of the for or while loop in which it appears;

%count = 0; 
while(%count++ < 8) 
{ 
   if ( %count > 2 )
      continue; // echo will not be executed
   echo(%count); 
}

See Also:
for, while

Purpose The datablock keyword is used to declare a new datablock. A datablock object is used in the declaration and initialization of a special set of classes that take a datablock(s). Datablocks are created on the server and ghosted to clients.

Syntax

datablock DatablockClass ( NewDatablockName : InheritDatablock ) 
{
   className = "SomeName";

   DataBlockBody
};

• DatablockClass - A predefined engine class which inherits from SimDataBlock or one of it's children.

• NewDatablockName - The name for this datablock. Must be unique.

• InheritDatablock - Previously defined datablock to inherit (copy) DataBlockBody values from. Optional.

• className - This is a special field which can be initialized with the name of a previously defined [in Torque Script] datablock. In effect, this inserts the "SomeName" name into the namespace calling sequence between NewDatablockName and DatablockClass. For some datablock classes, className can be a non-datablock name, but it isn't guaranteed to work for all calling sequences or classes.

• DataBlockBody - Fields and the values they will be assigned for this datablock.

datablock SimDataBlock( myDataBlock ) 
{
   newField = "Hello";
   newField2 = 10;
}; 

Here we have declared a new SimDataBlock datablock named myDataBlock. Additionally, we have given it a new field named newField, initialized to "Hello" and a new field named newField2 initialized to 10. The namespace calling sequence for this datablock is: myDataBlock -> SimDataBlock

datablock SimDataBlock( mySecondDataBlock : myDataBlock) 
{
   className = "myDataBlock";
   newField2 = 15;
}; 

Here we have declared a new SimDataBlock datablock named mySecondDataBlock that derives from myDataBlock. Because it is deriving from a prior datablock, it will copy any fields that were declared and/or initialized in the parent datablock. However, because we are re-declaring the field newField2. The new initialization value is taken in preference to the copied value, meaning that newField has the value "Hello" and newField2 has the value 15. Finally, we have defined className as myDataBlock, making the namespace calling sequence for mySecondDataBlock:

mySecondDataBlock -> myDataBlock -> SimDataBlock

See Also
new, Parent

Purpose The default case in a switch or switch$ statement, i.e., the case that is executed if no other cases are chosen.
Syntax
default :(colon character)
Note: The default keyword must be listed after all case keywords. It is a syntax error to place it before subsequent case keywords.

See Also
switch, switch$

Purpose The else keyword is used with the if keyword to control the flow of a script. The general form of the well known if-then-else construct is as follows:

if (expression) 
{ 
   statement(s); 
} 
else 
{ 
   alternate statement(s); 
}

Where the alternate statement(s) are executed if the expression evaluates to 0.

See if example.

See Also
if

Purpose The false keyword is used for boolean comparison and evalulates to 0.

if( false == 0 ) 
{ 
   echo( "false evaulates to" SPC 0 ); 
}

See Also
if, true

Purpose A looping construct, whose general form is:
for ( statement0 ; expression1 ; statement2 )
{
statements(s)
}
where,

• statement0 - Usually an assignment.
• expression1 - An expression, usually of the form: variable compare op value
• statement2 - Usually an assignment.

Execution

1. To begin, statement0 is executed.
   
2. Then, expression1 is tested. If false, end the for loop.
3. Execute statement(s), then execute statement2.
4. Continue with Step 2 and 3.

• All three of statement0, expression1, and statement2 are required. If you need statement0 or statement2 to be empty, just insert a 0.
• Composite expressions of the form ( sub_expression0 , sub_expression1 , sub_expressionN ) are illegal.

Example 1

for( %val = 0 ; %val <  3 ; %val++ ) 
{ 
   echo( %val );
}

Example 2 Empty statement0 and statement2

%value = 0; 
for( 0 ; %val < 3 ; 0 ) 
{ 
   echo( %val ); 
   %val ++;
}

Example 3 Illegal sub-expressions (would produce an error while compiling):

%val = 0; 
for( %val0 = 0 , %val1 = 3 ; %val0 <  3 ; %val0++, %val1-- )  
{ 
   echo( %val0 );
   echo( %val1 );
}

See Also
break, continue, while

Purpose The function keyword is used to define a new console function or method. Unlike a language like C or C++, functions are not declared in one place and defined in another, but defined only. Redeclaring a named function later in script over-rides the previous definition. The format of a function takes one of two forms:

Function definition

function func_name( [arg0] , ... , [argn] ) 
{
   statements;
   [return val;]
}

• func_name - Name by which this function will be subsequently called.
  
• [arg0] , ... , [argn] - Optional arguments.
  
• statements - Any number of statements may be contained within the body of the function.
  
• val - Functions may optionally return a value;

Console method definition

function namespace::func_name( %this, [arg0] , ... , [argn] ) 
{
   statements;
   [return val;]
}

• namespace - The name of a datablock or object classname.
  
• :: - Namespace resolution operator.
  
• %this - The first argument of a console method is always the handle to the object which is calling the method.

Defining a function

function test( %val ) 
{
  echo( "test(" SPC %val SPC ")" );

  if( 10 == %val ) return true;

  return false;
}

Defining a console method

function Item::test( %this , %val ) 
{
  echo( "Item::test(" SPC %this SPC "," SPC %val SPC ")" );

  if( 10 = %val ) return true;

  return false;
}

Instantiating a console object

%obj = new Item(MyItem)
{
  // ..
};

Invoking a console method

Item::test( %obj, 10 ) ; 	
%obj.test( 10 ) ;   		
MyItem.test( 10 ) ; 
%obj.getName().test( 10 ) ; 

• In the first example of invoking, it should be clear that we have simply defined a function in the Item namespace and are now invoking it in the normal way.
• In the second example, which is equivalent to the first, the syntax used automatically passes the object's handle as the first argument to the function.
• In the third example, we take advantage of the ability of the .(dot) operator to use the name of an object in lieu of its handle.
• The fourth example illustrates a different way of doing the same thing, this time using the SimObject::getName() function, defined for every console class.

Purpose The if keyword is used with or without the else keyword to control the flow of a script. The general form of the well known if-then-else construct is as follows,

if (expression) 
{ 
   statement(s); 
}
else 
{ 
   alternate statement(s); 
}

Where the statement(s) are executed if the expression evaluates to a non-zero value.

if(0) 
{ 
   echo( "hello" ); 
} 
else 
{ 
   echo( "goodbye" ); 
}

if(5) 
{ 
   echo( "hello" ); 
} 
else 
{ 
   echo( “goodbye” ); 
}

See Also
else

Purpose The new keyword is used to instantiate (create) a new copy of a conobject. A conobject is:

• an engine class available in the console (Item(), Player(), etc.), or
  
• a datablock (derived or otherwise).

// New non-datablock (using) object
%obj = new ScriptObject();

//New datablock (using) object
datablock ItemData( GoldCoin ) 
{
...
};

%coin = new Item( myGoldCoin ) 
{
  // ...
  datablock = GoldCoin;
};

See Also
datablock

Purpose The package keyword tells the console that the subsequent block of code is to be declared but not loaded. Packages provide dynamic function-polymorphism in TorqueScript. In short, a function defined in a package will over-ride the prior definition of a same named function when the is activated. When the package is subsequently de-activated, the previous definition of any overridden functions will be re-asserted.

A package will have the following syntax:

package package_name 
{
	function function_definition0() 
	{
		[statements;]
	}
	...
	function function_definitionN() 
	{
		[statements;]
	}
};

Things to know:

• The same function can be defined in multiple packages.
• Only functions can be packaged.
• Datablocks cannot be packaged.
• Packages 'stack' meaning that deactivating packages activated prior to the currently active (s) will deactivate all packages activated prior to the being deactivated (see example below).
• Functions in a may activate and deactivate packages.

Activating
In order to use the functions in a package, the package must be activated:

ActivatePackage(_name);

Deactivating
Subsequently a package can be deativated:

DeactivatePackage(_name);

Usage
First, define a function and two packages, each of which provides an alternative definition by the same name.

function testFunction() 
{
   echo( "testFunction() - unpackaged." );
}

package MyPackage0
{
  function testFunction() 
  {
      echo( "testFunction() - MyPackage0." );
  }
};

MyPackage1
{
  function testFunction() 
  {
      echo( "testFunction() - MyPackage1." );
  }
};

Next, invoke that function under three different conditions. The following is as if run in the console, with our input set off by '==>'

==> testFunction(); 
testFunction() - unpackaged.

==> ActivatePackage( MyPackage0 );

==> testFunction(); 
testFunction() - MyPackage0.

==> ActivatePackage( MyPackage1 );

==> testFunction(); 
testFunction() - MyPackage1.

==> DeactivatePackage( MyPackage0 );  // MyPackage1 is automatically deactivated.

==> testFunction(); 
testFunction() - unpackaged.

See Also
function, Parent

Purpose The Parent keyword is used with the namespace operator (::) to reference the previous definition of a function what has been over-ridden either through inheritance or packaging. The Parent keyword can only be used within specific contexts:

• From within a consoleMethod, or
  
• from within a packaged function.

// Calling an inherited parent
datablock ItemData( GoldCoin ) 
{
...
};

function ItemData::onAdd( %db, %obj ) 
{
   echo( "ItemData::onAdd()" );
}

function GoldCoin::onAdd( %db, %obj ) 
{
   Parent::onAdd( %db, %obj );

   echo( "GoldCoin::onAdd()" );
}

// Calling a  parent
function testFunction() 
{
   echo( "testFunction() - unpackaged." );
}

MyPackage0
{
  function testFunction() 
  {
     Parent::testFunction();
     echo( "testFunction() - MyPackage0." );
  }
};

...

testFunction(); 
// prints => testFunction() - unpackaged.

ActivatePackage( MyPackage0 );

testFunction(); 
// prints => testFunction() - unpackaged.
// prints => testFunction() - MyPackage0.

See Also
datablock, function

Purpose The return keyword is used to return a value from a function

function equal_to( %arg0 , %arg1 ) 
{ 
   return ( %arg0 == %arg1 ); 
}

echo( equal_to(10,11) ); // prints 0

echo( equal_to(11,11) ); // prints 1

See Also
function

Purpose The switch keyword is used to control the flow of a script. It is like the switch$ statement, but intended for numeric comparisons instead of string comparisons.

The general form of a switch statement is as follows:

switch ( numeric expression ) 
{
case value0:
   statement(s);
case value1:
   statement(s);
. . .
case valueN:
   statement(s);
default:
   statement(s);
}

Execution

1. First, numeric expression is evaluated and compared with value0.
2. If the result is true, the statement(s) associated with that case are executed, and the switch statement is exited.
3. If not, control passes to the next case statement, where numeric expression is again evaluated, this time being compared to value1.
4. If control falls through to the default case, its statements will be executed.

%tmp = 1;

switch( %tmp  ) 
{ 
case 0: 
   echo( 0 ); 
case 1: 
   echo( 1 ); 
default: 
   echo( "proof" ); 
}

See Also
case, default, switch$

Purpose The switch$ keyword is used to control the flow of a script. It is like the switch statement, but intended for string comparisons instead of numeric comparisons.

The general form of the switch$ statement is:

switch$ ( string expression ) 
{
case string_value0:
   statement(s);

case string_value1:
   statement(s);
. . .
case string_valueN:
   statement(s);

default:
   statement(s);
}

Execution

1. First, string expression is evaluated and compared with value0.
2. If the result is true, the statement(s) associated with that case are executed, and the switch$ statement is exited.
3. If not, control passes to the next case statement, where string expression is again evaluated, this time being compared to value1.
4. If control falls through to the default case, its statements will be executed.

Purpose The true keyword is used for boolean comparison and evalulates to 1.

if(true == 1) 
{ 
   echo( "true evaulates to" SPC 1 ); 
}

See Also
if, false

Purpose The while keyword is a looping construct whose general form is:

while (expression)
{
   statements(s); 
}

Where expression is usually of the form: variable compare op value, and the loop continues to execute statement(s) until expression evaluates to false (i.e. 0).

%val=5; 

while( %val ) 
{ 
   echo( %val-- ); 
}

See Also
break, continue, for