This quick reference guide was taken directly out of The Game Programmer's Guide to Torque by Edward Maurina. It's an outstanding resource - a must for anyone wanting to get serious about programming in Torque.

Torque includes a bad word filtering feature that can be used process strings and to replace any words matching words on the list of known bad works. This list is built manually. Bad words are replaced with a user-defined set of random characters. Please note, a small but common list of bad words is already included in the engine. Please refer to the engine source code for this list as a would-be tasteless the list of words here.

Purpose
Use the addBadWord function to add new 'bad words' to the current 'bad word' list. Once a word is added to the list, it may not be removed. Also, adding a word more than once has no additional effect.

Syntax
aBadWord – A word to be considered as foul language and to be looked for when the containsBadWords and/or filterString functions are called.

Returns
No return value.

Notes
Several bad words are already added by the engine. Please refer to the source code for a full listing.

See Also
containsBadWords, filterString

Purpose
Use the containsBadWords function to check string for any previosly specified 'bad words'.

Syntax
string – Any string to be checked for bad words.

Returns
Returns true if any words on the bad word list are found in the string. Returns false otherwise.

Notes
This function will catch whole words and variants as long as the variant contains the full spelling of the bad word. For example, if 'whack' were defined as a bad word, this function would return true if the word 'whacko' were included in a sentence.

See Also
addBadWord, filterString

Returns true if string contains any known bad words.

Purpose
Use the filterString function to parse baseString for words on the 'bad word' list and to then replace those words with random characters.

Syntax
baseString – The original string, possibly containing bad words.
replacementChars – This optional argument can be used to supply a single character or a list of chracters to use for the replacement of characters the bad words. If no replacement chracters are specified, the engine will choose randomly from lower-case alpha-characters (a..z).

Returns
Returns a 'cleaned' string. This string will contain all the original words, except that any words which were deemed 'bad' will have had each character in the word replaced with a random replacement character.

Notes
This function will catch whole words and variants as long as the variant contains the full spelling of the bad word. For example, if 'whack' where defined as a bad word, this function would return true if the word 'whacko' were included in a sentence.

See Also
addBadWord, containsBadWords

function badWordTest()
{
  addBadWord( "poop" );
  
  %testPhrase = "This is the poop!";
  
  %filteredPhrase = filterString( %testPhrase , "@#$*" );
  
  echo("Contains bad words? ==> " , containsBadWords( %testPhrase ) );
  
  echo("Before filtering: ", %testPhrase );
  
  echo("After  filtering: ", %filteredPhrase );

}


badWordTest();

Contains bad words? ==> 1
Before filtering: This is the poop!
After  filtering: This is the $@@*!

Purpose
Use the strcmp function to do a lexicographic case sensitive string comparison between string1 and string2.

Syntax
string1 – String to be compared to string2.
string2 – String to be compared to string1.

Returns
Returns a numeric value:
-1 – string1 is less than string2, including case.
0 – string1 is equal to string2, including case.
1 – string1 is greater than string2, including case.

See Also
see stricmp, strstr

Purpose
Use the stricmp function to do a lexicographic case in-sensitive string comparison between string1 and string2.

Syntax
string1 – String to be compared to string2.
string2 – String to be compared to string1.

Returns
Returns a numeric value:
-1 – string1 is less than string2, ignoring case.
0 – string1 is equal to string2, ignoring case.
1 – string1 is greater than string2, ignoring case.

See Also
see strcmp, strstr

function strcmptest() 
{
  echo("Lexicographic comparisons are not the same as arithmetic comparisons...");
  
  echo("100 - 10 == 90, but strcmp( \"100\" , \"10\" ) == " , 
       strcmp( "100" , "10" ) );
        
  echo("\n", "Don't forget about case-senstivity...");
 
  echo("strcmp( \"ABC\" , \"abc\" )  == " , 
       strcmp( "ABC" , "abc" ) , "\n\n, but \n" );
  
  echo("stricmp( \"ABC\" , \"abc\" ) == " , 
       stricmp( "ABC" , "abc" ) );
}


strcmptest();

Lexicographic comparisons are not the same as arithmetic comparisons...
100 - 10 == 90, but strcmp( "100" , "10" ) == 1

Don't forget about case-senstivity...
strcmp( "ABC" , "abc" )  == -1

, but 

stricmp( "ABC" , "abc" ) == 0

Purpose
Use the strlwr function to convert all alpha characters in sourceString to lower-case equivalents.

Syntax
sourceString – The string to be modified.

Returns
Returns a copy of souriceString in which all upper-case characters have been coverted to lower-case letters.

See Also
strupr

echo( strlwr( "ABCD123" ) ); // Prints abcd123

Purpose
Use the strupr function to convert all alpha characters in sourceString to upper-case equivalents.

Syntax
sourceString – The string to be modified.

Returns
Returns a copy of souriceString in which all lower-case characters have been coverted to upper-case letters.

See Also
strlwr

echo( strupr( "abcd123" ) ); // Prints ABCD123

A field is a sub-string withing a larger string, where each field is delimted by a NEWLINE character or a TAB character. A newline can be represented as either "\n" or the keyword NL, and a tab can be represented by hitting the TAB key, or by the keyword TAB.

Purpose
Use the getField function to get the field at index in sourceString.

Syntax
sourceString – A string containing one or more fields.

Returns
Returns field at index in sourceString, or null string if no field exists at that index.

See Also
getFields, setField

// Prints Torque
echo( getField( "GPGTGE + " NL "AND" TAB "Torque" TAB "Rocks" , 2 ) );

Purpose
Use the getFieldCount function to get the number of fields in sourceString.

Syntax
sourceString – A string containing one or more fields.

Returns
Returns number of fields in sourceString or 0 if no fields are present.

%fields = "You" TAB "must" TAB "buy" TAB "GPGTGE";

echo( getFieldCount( %fields ) ); // Prints 4

Purpose
Use the getFields function to retrieve a set of fields from a sourceString.

Syntax
sourceString – A string containing one or more fields.
index – The index of the first field to retrieve.
endindex – The index of the final field to retrieve.

Returns
Returns all fields (separated by current delimiter) from sourceString, starting at index and ending at endIndex or end of string, whichever comes first. If no endIndex is specified, all remaining fields are returned.

See Also
getField, setField

// Prints Torque^Rocks (^ is printed TAB in console)
echo( getFields( "GPGTGE + " NL "AND" TAB "Torque" TAB "Rocks" , 2 , 3 ) );

// Also prints Torque^Rocks
echo( getFields( "GPGTGE + " NL "AND" TAB "Torque" TAB "Rocks" , 2 ) );

Purpose
Use the removeField function to remove a single indexed field from a sourceString.

Syntax
sourceString – A string containing one or more fields.
index – The index of the field to remove.


Returns
Returns sourceString minus the removed field. If the index is greater than the number of fields in sourceString, the original string is returned.

See Also
setField

%fields = "Torque" TAB "So" TAB "Totally" TAB "Rocks!";

// %fields will contain three fields: "Torque", "Totally", and "Rocks!".
%fields = removeField( %fields, 1 );

Purpose
Use the setField function to replace an existing field with a new field(s), or to add field(s) to a string..

Syntax
sourceString – A string containing one or more fields.
index – The index of the field to remove.
replace – The new field(s) to replace the field at index with.


Returns
There are multiple return cases:
- In the first case, a simple one-to-one replacement, the field at index in sourceString will be replaced with the value in replace, and the new string will be returned.

- In the second case, a multi-to-one replacement, the field at index in sourceString will be replaced with the value in replace, which can be two or more fields, and the new string will be returned.

- In the thrid and final case, new records, empty or filled, can be appended to the end of sourceString. If index is beyond the end of the sourceString, that is, the index is greater than the total count of fields in sourceString, the requisite number of empty (null-string) fields will be appended to the end of sourceString and the value in replace will be appended to the end of this new string. This entire resultant string will be returned.

See Also
getField, getFields, removeField

// %fields will contain two fields, "Torque" and "Rocks!",
%fields =  setField( "Torque" TAB "Rock" , 1 , "Rocks!" );

Purpose
Use the strlen function to determine how many characters there are in string.

Syntax
string – The string to count characters for.

Returns
Returns the number of characters in string, or 0 if string is invalid or a NULL string.

// Prints 10
echo( strlen( "0123456789" ) );

A record is a sub-string withing a larger string, where each record is delimted by a NEWLINE character. A newline can be represented as either "\n" or the keyword NL.

Purpose
Use the getRecord function to get the record at index in sourceString.
A record is defined by a NL.
Syntax
sourceString – A string containing one or more records.

Returns
Returns record at index in sourceString, or NULL string if no record exists at that index.

See Also
getRecords, setRecord

// Prints Torque
echo( getRecord( "GPGTGE + " NL "AND" NL "Torque" NL "Rocks" , 2 ) );

Purpose
Use the getRecordCount function to get the number of records in sourceString.

Syntax
sourceString – A string containing one or more records.

Returns
Returns number of records in sourceString or 0 if no records are present.

%records = "You" NL "must" NL "buy" NL "GPGTGE";

echo( getRecordCount( %records ) ); // Prints 4

Purpose
Use the getRecords function to retrieve a set of records from a sourceString.

Syntax
sourceString – A string containing one or more records.
index – The index of the first record to retrieve.
endindex – The index of the final record to retrieve.

Returns
Returns all records (separated by current delimiter) from sourceString, starting at index and ending at endIndex or end of string, whichever comes first. If no endIndex is specified, all remaining records are returned.

See Also
getRecord, setRecord

// Prints 
// Torque
// Rocks
echo( getRecords( "GPGTGE + " NL "AND" NL "Torque" NL "Rocks" , 2 , 3 ) ); 

// Also prints
// Torque
// Rocks
echo( getRecords( "GPGTGE + " NL "AND" NL "Torque" NL "Rocks" , 2 ) );

Purpose
Use the removeRecord function to remove a single indexed record from a sourceString.

Syntax
sourceString – A string containing one or more records.
index – The index of the record to remove.

Returns
Returns sourceString minus the removed record. If the index is greater than the number of records in sourceString, the original string is returned.

See Also
setRecord

%records = "Torque" NL "So" NL "Totally" NL "Rocks!";

// %records will contain three records: "Torque", "Totally", and "Rocks!".
%records = removeRecord( %records, 1 );

Purpose
Use the setRecord function to replace an existing record with a new record(s), or to add record(s) to a string..

Syntax
sourceString – A string containing one or more records.
index – The index of the record to remove.
replace – The new record(s) to replace the record at index with.

Returns
There are multiple return cases:
- In the first case, a simple one-to-one replacement, the record at index in sourceString will be replaced with the value in replace, and the new string will be returned.

- In the first case, a multi-to-one replacement, the record at index in sourceString will be replaced with the value in replace, which can be two or more records, and the new string will be returned.

- In the thrid and final case, new records, empty or filled, can be appended to the end of sourceString. If index is beyond the end of the sourceString, that is, the index is greater than the total count of records in sourceString, the requisite number of empty (null-string) records will be appended to the end of sourceString and the value in replace will be appended to the end of this new string. This entire resultant string will be returned.

See Also
getRecord, getRecords, removeRecord

// %records will contain two records, "Torque" and "Rocks!",
%Records =  setRecord( "Torque" NL "Rock" , 1 , "Rocks!" );

Purpose
Use the strreplace function to replace every instance of from in sourceString with to.

Syntax
sourceString – The string to do replacement operations on.
from – The old value to be replaced.
to – The new value to replace old values with.

Returns
Returns a new version of sourceString in which every instance of the value in from was replaced with the value in to.

Notes
This function is case-sensitive and only does exact matching.

// Prints Torque rocks!
echo( strreplace("Torque is cool!" , "is cool" , "rocks" ) );

Purpose
Use the getSubStr function to get a sub-string of sourceString, starting at character index start and ending at character index start + count, or the end-of-string, which ever comes first.

Syntax
sourceString – The string from which to extract a sub-string.
start – The character index at which the extraction starts.
count – The length of the sub-string to extract.

Returns
Returns a string made up of the character at start in sourceString and ending at the end of the original sourceString, or start + count, whichever comes first.

Notes
If start + count is greater than the length of sourceString, the extraction will return a string shorter than count.

See Also
strchr

// Prints 2345
echo( getSubStr( "0123456789" , 2 , 4 ) );

Purpose
Use the strchr function to extract a sub-string of sourceString, where the sub-string is equal to the first occurence of char in sourceString followed by the remainder of sourceString.

Syntax
sourceString – The string from which to extract a sub-string.
char – The character to search for in sourceString.

Returns
Returns a string composed of first instance of char in sourceString, and all of the characters after it. If char is not found, a NULL string is returned.

See Also
getSubStr

// Prints 3456789
echo( strchr( "0123456789" , "3" ) );

Purpose
Use the strPos function to locate the first instance of searchString in sourceString, starting at character 0, or at an optional offset.

Syntax
sourceString – The string in which to search for searchString.
searchString – The string for which to search for in sourceString.
offset – An optional non-negative integer value representing the character offset within sourceString at which to begin the search.

Returns
Returns a numeric character index representing the postion in sourceString at which searchString was found, or -1 to indicate that no instance of searchString was found.

See Also
strstr

// Prints 2
echo( strpos( "This is a test" , "is" ) );

// Prints 5
echo( strpos( "This is a test" , "is" , 3 ) );

Purpose
Use the strstr function to locate the first instance of searchString in sourceString.

Syntax
sourceString – The string in which to search for searchString.
searchString – The string for which to search for in sourceString.

Returns
Returns a numeric character index representing the postion in sourceString at which searchString was found, or -1 to indicate that no instance of searchString was found.

See Also
strpos

// Prints -1
echo( strstr( "This is a test" , "IS" ) );

// Prints 2
echo( strstr( "This is a test" , "is" ) );

Purpose
Use the stripChars function to remove chars from sourceString.

Syntax

sourceString–The string to be modified.
chars–The character or characters to search for and remove.

Returns
Returns a copy of sourceString, from which all instances of chars have been removed. This may be the original sourceString, if chars was not found.

See Also
stripMLControlChars, stripTrailingSpaces

// Prints WowThisIsCool
echo( stripChars("WowxThisy*IsCoolz!" , "*xyz" ) );

Purpose

Removes TorqueML color codes from the given string.

Syntax

stringtoStrip—The input string.

Returns

Returns a copy of stringtoStrip, from which all instances of TorqueML markup color codes have been removed.

Purpose
Use the stripMLControlChars function to remove all Torque Markup-Language (ML) symbols from sourceString.

Syntax
sourceString – The string to be modified.

Returns
Returns a copy of sourceString with all the ML symbols removed, or the original string if no ML symbols were present.

Caution
This may not remove
correctly, so check before you trust this function.

See Also
stripChars, stripTrailingSpaces

Purpose
Use the stripTrailingSpaces function to remove all spaces and underscores from sourceString.

Syntax
sourceString – The string to be modified.

Returns
Returns modified string, or original string if no trailing spaces found found.

Notes
This function DOES NOT remove TAB characters, only a space " ", or underline "_" are considered spaces.

See Also
stripChars, stripMLControlChars, ltrim, rtrim, trim

// Prints This is a test.
echo( stripTrailingSpaces( "This is a    " ) SPC "test." );

Purpose
Use the ltrim function to strip the leading white space from sourceString.

Syntax
sourceString – The string to be trimmed.

Returns
Returns sourceString with all the leading white spaces removed.

Notes
White space is any character in this set: spaces, TABs, and NULL strings.

See Also
stripChars, stripMLControlChars, stripTrailingSpaces, rtrim, trim

// Prints This is a test.
echo( ltrim( " " TAB " " SPC "This is a test." ) );

Purpose
Use the rtrim function to strip the trailing white space from sourceString.

Syntax
sourceString – The string to be trimmed.

Returns
Returns sourceString with all the trailing white spaces removed.

Notes
White space is any character in this set: spaces, TABs, and NULL strings.

See Also
stripChars, stripMLControlChars, stripTrailingSpaces, ltrim, trim

// Prints This is a test.
echo( rtrim( "This is a    " ) SPC "test." );

Purpose
Use the trim function to strip the leading and trailing white space from sourceString.

Syntax
sourceString – The string to be trimmed.

Returns
Returns sourceString with all the leading and trailing white spaces removed.

Notes
White space is any character in this set: spaces, TABs, and NULL strings.

See Also
stripChars, stripMLControlChars, stripTrailingSpaces, ltrim, rtrim

// Prints This is a test.
echo( trim( " " TAB " " SPC "This is a     " ) SPC "test." );

Purpose
Use the nextToken function to get the first token found in tokenList, where tokens are separated by the character(s) specified in delimeter. The token itself is stored in a variable whose name is specified in tokenVar. This function provides complex power in a simple package. Please read the notes below, they are very important.

Syntax
tokenList – The string containing token(s).
tokenVar – The 'name' of the variable to store the token in.
delimeter – The character(s) to use as a delimeter. A delimeter may be a single character, or a sequence of characters.

Returns
Returns a copy of tokenList, less the first token and the first delimeter. If there are no more tokens, a NULL string is returned.

Notes
This function is scope-smart. That is, when we specify the name of the variable to store a token in by passing a value in tokenVar, we do not include either a local symbol (%), or a global symbol ($). We just pass in an un-adorned name, let's say "George". Then, depending on where this function is called, "George" will become a local (%George), or a global ($George) variable. If this function is called within a function or method definition, "George" will be local (%George). If this function is called from the file-scope (execucted as part of a file and not within the scope of a function or method), "George" will become a global ($George). There is one additional special case. If you attempt to use this from the console command line, the token will vaporize and no variable will be created.

function testTokens( )
{
  %myTokens = "A,E,I,O,U";

  while( "" !$= %myTokens )
  {
     %myTokens = nextToken( %myTokens , "theToken" , "," ); 
   
     echo( %theToken );
   }
}

testTokens(); 
A
E
I
O
U

A word is a sub-string withing a larger string, where each word is delimted by a SPACE character. A space can be represented as either " " or the keyword SPC.

Purpose
Use the firstWord function to retrieve the first word found in sourceString.

Syntax
sourceString – A string containing one or more words.

Returns
Returns the first word found in sourceString, or a NULL string, if no words are found.

See Also
restWords

// a target in range was found so select it
if (%scanTarg) 
{
   %targetObject = firstWord(%scanTarg);
   %client.setSelectedObj(%targetObject);
}

Purpose
Use the getWord function to get the word at index in sourceString.

Syntax
sourceString – A string containing one or more words.

Returns
Returns word at index in sourceString, or null string if no word exists at that index.

See Also
getWords, setWord

function TerrainEditor::offsetBrush(%this, %x, %y) 
{
   %curPos = %this.getBrushPos();
   %this.setBrushPos(getWord(%curPos, 0) + %x, getWord(%curPos, 1) + %y);
}

Purpose
Use the getWordCount function to get the number of words in sourceString.

Syntax
sourceString – A string containing one or more words.

Returns
Returns number of words in sourceString or 0 if no words are present.

if ( %pos != -1 ) 
{
   %wordCount = getWordCount( %action );
   %mods = %wordCount > 1 ? getWords( %action, 0, %wordCount - 2 ) @ " " : "";
   %object = getWord( %action, %wordCount - 1 );
   switch$ ( %object ) 
   {
      case "upov":   %object = "POV1 up";
      case "dpov":   %object = "POV1 down";
      case "lpov":   %object = "POV1 left";
      case "rpov":   %object = "POV1 right";
      case "upov2":  %object = "POV2 up";
      case "dpov2":  %object = "POV2 down";
      case "lpov2":  %object = "POV2 left";
      case "rpov2":  %object = "POV2 right";
      default:       %object = "??";
   }
   return( %mods @ %object );
}
 else 
{
   error( "Unsupported Joystick input object passed to getDisplayMapName!" );
}

Purpose
Use the getWords function to retrieve a set of words from a sourceString.

Syntax
sourceString – A string containing one or more words.
index – The index of the first word to retrieve.
endindex – The index of the final word to retrieve.

Returns
Returns all words (separated by current delimiter) from sourceString, starting at index and ending at endIndex or end of string, whichever comes first. If no endIndex is specified, all remaining words are returned.

See Also
getWord, setWord

%pos    = getWords(%obj.getTransform(), 0, 2);

Purpose
Use the removeWord function to remove a single indexed word from a sourceString.

Syntax
sourceString – A string containing one or more words.
index – The index of the word to remove.


Returns
Returns sourceString minus the removed word. If the index is greater than the number of words in sourceString, the original string is returned.

See Also
setWord

%cam = removeWord(%cam, 0, getWord(%pos, 0));

Purpose
Use the restWords function to retrieve all words after the first word in sourceString.

Syntax
sourceString – A string containing one or more words.

Returns
Returns a string containing all the words after the first word found in sourceString, or a NULL string if no words remain after the first word (or if no words at all remain).

See Also
firstWord

function Heightfield::showTab(%id) 
{
   Heightfield::hideTab();
   %data = restWords(Heightfield_operation.getRowTextById(%id));
   %tab  = getField(%data,1);
   echo("Tab data: " @ %data @ " tab: " @ %tab);
   %tab.setVisible(true);
}

Purpose
Use the setWord function to replace an existing word with a new word(s), or to add word(s) to a string..

Syntax
sourceString – A string containing one or more words.
index – The index of the word to remove.
replace – The new word(s) to replace the word at index with.


Returns
There are multiple return cases:
- In the first case, a simple one-to-one replacement, the word at index in sourceString will be replaced with the value in replace, and the new string will be returned.

- In the second case, a multi-to-one replacement, the word at index in sourceString will be replaced with the value in replace, which can be two or more words, and the new string will be returned.

- In the third and final case, new records, empty or filled, can be appended to the end of sourceString. If index is beyond the end of the sourceString, that is, the index is greater than the total count of words in sourceString, the requisite number of empty (null-string) words will be appended to the end of sourceString and the value in replace will be appended to the end of this new string. This entire resultant string will be returned.

See Also
getWord, getWords, removeWord

function WorldEditor::dropCameraToSelection(%this) 
{
   if(%this.getSelectionSize() == 0) return;

   %pos = %this.getSelectionCentroid();
   %cam = LocalClientConnection.camera.getTransform();

   // set the pnt
   %cam = setWord(%cam, 0, getWord(%pos, 0));
   %cam = setWord(%cam, 1, getWord(%pos, 1));
   %cam = setWord(%cam, 2, getWord(%pos, 2));
   LocalClientConnection.camera.setTransform(%cam);
}