Scripting

More...

Classes:

class

ArrayObject

Data structure for storing indexed sequences of key/value pairs.

class

ScriptGroup

Essentially a SimGroup, but with onAdd and onRemove script callbacks.

class

ScriptObject

A script-level OOP object which allows binding of a class, superClass and arguments along with declaration of methods.

class

ScriptTickObject

A ScriptObject that responds to tick and frame events.

class

SimGroup

A collection of SimObjects that are owned by the group.

class

SimSet

A collection of SimObjects.

Functions

string

call(string functionName, string args...)

Apply the given arguments to the specified global function and return the result of the call.

bool

compile(string fileName, bool overrideNoDSO)

Compile a file to bytecode.

void

deleteVariables(string pattern)

Undefine all global variables matching the given name pattern.

bool

exec(string fileName, bool noCalls, bool journalScript)

Execute the given script file.

bool

execPrefs(string relativeFileName, bool noCalls, bool journalScript)

Manually execute a special script file that contains game or editor preferences.

void

export(string pattern, string filename, bool append)

Write out the definitions of all global variables matching the given name pattern.

string

getDSOPath(string scriptFileName)

Get the absolute path to the file in which the compiled code for the given script file will be stored.

string

getVariable(string varName)

Returns the value of the named variable or an empty string if not found.

bool

isDefined(string varName, string varValue)

Determines if a variable exists and contains a value.

bool

isFunction(string funcName)

Determines if a function exists or not.

bool

isMethod(string nameSpace, string method)

Determines if a class/namespace method exists.

void

setVariable(string varName, string value)

Sets the value of the named variable.

Detailed Description

Functions

call(string functionName, string args...)

Apply the given arguments to the specified global function and return the result of the call.

Parameters:

functionName

The name of the function to call. This function must be in the global namespace, i.e. you cannot call a function in a namespace through call. Use eval() for that.

return:

The result of the function call.

function myFunction( %arg )
{
  return ( %arg SPC "World!" );
}

echo( call( "myFunction", "Hello" ) ); // Prints "Hello World!" to the console.

compile(string fileName, bool overrideNoDSO)

Compile a file to bytecode.

This function will read the TorqueScript code in the specified file, compile it to internal bytecode, and, if DSO generation is enabled or overrideNoDDSO is true, will store the compiled code in a .dso file in the current DSO path mirrorring the path of fileName.

Parameters:

fileName	Path to the file to compile to bytecode.
overrideNoDSO	If true, force generation of DSOs even if the engine is compiled to not generate write compiled code to DSO files.

return:

True if the file was successfully compiled, false if not.

note:
The definitions contained in the given file will not be made available and no code will actually be executed. Use exec() for that.

see:

getDSOPath

see:

exec

deleteVariables(string pattern)

Undefine all global variables matching the given name pattern.

Parameters:

pattern

A global variable name pattern. Must begin with '$'.

// Define a global variable in the "My" namespace.
$My::Variable = "value";

// Undefine all variable in the "My" namespace.
deleteVariables( "$My::*" );

see:

strIsMatchExpr

exec(string fileName, bool noCalls, bool journalScript)

Execute the given script file.

Parameters:

fileName	Path to the file to execute
noCalls	Deprecated
journalScript	Deprecated

return:

True if the script was successfully executed, false if not.

// Execute the init.cs script file found in the same directory as the current script file.
exec( "./init.cs" );

see:

compile

see:

eval

execPrefs(string relativeFileName, bool noCalls, bool journalScript)

Manually execute a special script file that contains game or editor preferences.

Parameters:

relativeFileName	Name and path to file from project folder
noCalls	Deprecated
journalScript	Deprecated

return:

True if script was successfully executed

note:
Appears to be useless in Torque 3D, should be deprecated

export(string pattern, string filename, bool append)

Write out the definitions of all global variables matching the given name pattern.

If fileName is not "", the variable definitions are written to the specified file. Otherwise the definitions will be printed to the console.

The output are valid TorqueScript statements that can be executed to restore the global variable values.

Parameters:

pattern	A global variable name pattern. Must begin with '$'.
filename	Path of the file to which to write the definitions or "" to write the definitions to the console.
append	If true and fileName is not "", then the definitions are appended to the specified file. Otherwise existing contents of the file (if any) will be overwritten.

// Write out all preference variables to a prefs.cs file.
export( "$prefs::*", "prefs.cs" );

getDSOPath(string scriptFileName)

Get the absolute path to the file in which the compiled code for the given script file will be stored.

Parameters:

scriptFileName

Path to the .cs script file.

return:

The absolute path to the .dso file for the given script file.

note:
The compiler will store newly compiled DSOs in the prefs path but pre-existing DSOs will be loaded from the current paths.

see:

compile

see:

getPrefsPath

getVariable(string varName)

Returns the value of the named variable or an empty string if not found.

@varName Name of the variable to search for

return:

Value contained by varName, "" if the variable does not exist

isDefined(string varName, string varValue)

Determines if a variable exists and contains a value.

Parameters:

varName

Name of the variable to search for

return:

True if the variable was defined in script, false if not

isDefined( "$myVar" );

isFunction(string funcName)

Determines if a function exists or not.

Parameters:

funcName

String containing name of the function

return:

True if the function exists, false if not

isMethod(string nameSpace, string method)

Determines if a class/namespace method exists.

Parameters:

namespace	Class or namespace, such as Player
method	Name of the function to search for

return:

True if the method exists, false if not

setVariable(string varName, string value)

Sets the value of the named variable.

Parameters:

varName	Name of the variable to locate
value	New value of the variable

return:

True if variable was successfully found and set