Console

The basis of the TorqueScript system and command execution.

Functions

void cls()

Clears the console output.

void debugEnumInstances(string className, string functionName)

Call the given function for each instance of the given class.

Parameters:

• className – Name of the class for which to enumerate instances.
• functionName – Name of function to call and pass each instance of the given class.

bool dumpEngineDocs(string outputFile)

Dumps the engine scripting documentation to the specified file overwriting any existing content.

Parameters:outputFile – The relative or absolute output file path and name. Returns:Returns true if successful.

SimXMLDocument exportEngineAPIToXML()

Create a XML document containing a dump of the entire exported engine API.

Returns:containing a dump of the engine’s export information or NULL if the operation failed.

string getCategoryOfClass(string className)

Returns the category of the given class.

Parameters:className – The name of the class.

string getDescriptionOfClass(string className)

Returns the description string for the named class.

Parameters:className – The name of the class. Returns:The class description in string format.

bool isClass(string identifier)

Returns true if the passed identifier is the name of a declared class.

bool isMemberOfClass(string className, string superClassName)

Returns true if the class is derived from the super class. If either class doesn’t exist this returns false.

Parameters:

• className – The class name.
• superClassName – The super class to look for.

bool isValidObjectName(string name)

Return true if the given name makes for a valid object name.

Parameters:name – Name of object Returns:True if name is allowed, false if denied (usually because it starts with a number, _, or invalid character

SimObject loadObject(string filename)

Loads a serialized object from a file.

Parameters:Name – and path to text file containing the object

bool saveObject(SimObject object, string filename)

Serialize the object to a file.

Parameters:

• object – The object to serialize.
• filename – The file name and path.

void unitTest_runTests()

Run unit tests, or just the tests that prefix match against the searchString.

Variables

string $instantGroup

The group that objects will be added to when they are created.

bool $Con::alwaysUseDebugOutput

Determines whether to send output to the platform’s “debug” system.

bool $Con::logBufferEnabled

If true, the log buffer will be enabled.

int $Con::objectCopyFailures

If greater than zero then it counts the number of object creation failures based on a missing copy object and does not report an error..

int $Con::printLevel

This is deprecated. It is no longer in use and does nothing.

bool $Con::useTimestamp

If true a timestamp is prepended to every console message.

bool $Con::warnUndefinedVariables

If true, a warning will be displayed in the console whenever a undefined variable is used in script.

Debugging

Functionality to help spot program errors. Also provides profiler functions, helpful in determining performance bottlenecks.

Functions

void backtrace()

Prints the scripting call stack to the console log. Used to trace functions called from within functions. Can help discover what functions were called (and not yet exited) before the current point in scripts.

void debug()

Drops the engine into the native C++ debugger. This function triggers a debug break and drops the process into the IDE’s debugger. If the process is not running with a debugger attached it will generate a runtime error on most platforms.

void debugDumpAllObjects()

Dumps all current EngineObject instances to the console.

void debugv(string variableName)

Logs the value of the given variable to the console. Prints a string of the form ” lt variableName gt = lt variable value gt ” to the console.

Parameters:variableName – Name of the local or global variable to print.

Example:

%var = 1;
debugv( "%var" ); // Prints "%var = 1"

void dumpAlloc(int allocNum)

Dumps information about the given allocated memory block.

Parameters:allocNum – Memory block to dump information about.

void dumpMemSnapshot(string fileName)

Dumps a snapshot of current memory to a file. The total memory used will also be output to the console. This function will attempt to create the file if it does not already exist.

Parameters:fileName – Name and path of file to save profiling stats to. Must use forward slashes (/)

Example:

dumpMemSnapshot( "C:/Torque/ProfilerLogs/profilerlog1.txt" );

void dumpUnflaggedAllocs(string fileName)

Dumps all unflagged memory allocations. Dumps all memory allocations that were made after a call to flagCurrentAllocs() . Helpful when used with flagCurrentAllocs() for detecting memory leaks and analyzing general memory usage.

Parameters:fileName – Optional file path and location to dump all memory allocations not flagged by flagCurrentAllocs(). If left blank, data will be dumped to the console.

Example:

dumpMemSnapshot(); // dumps info to console
dumpMemSnapshot( "C:/Torque/profilerlog1.txt" ); // dumps info to file

void flagCurrentAllocs()

Flags all current memory allocations. Flags all current memory allocations for exclusion in subsequent calls to dumpUnflaggedAllocs() . Helpful in detecting memory leaks and analyzing memory usage.

void freeMemoryDump()

Dumps some useful statistics regarding free memory. Dumps an analysis of ‘free chunks’ of memory. Does not print how much memory is free.

void profilerDump()

Dumps current profiling stats to the console window.

void profilerDumpToFile(string fileName)

Dumps current profiling stats to a file.

Parameters:fileName – Name and path of file to save profiling stats to. Must use forward slashes (/). Will attempt to create the file if it does not already exist.

Example:

profilerDumpToFile( "C:/Torque/log1.txt" );

void profilerEnable(bool enable)

Enables or disables the profiler. Data is only gathered while the profiler is enabled.

void profilerMarkerEnable(string markerName, bool enable)

Enable or disable a specific profile.

Parameters:

• enable – Optional paramater to enable or disable the profile.
• markerName – Name of a specific marker to enable or disable.

void profilerReset()

Resets the profiler, clearing it of all its data. If the profiler is currently running, it will first be disabled. All markers will retain their current enabled/disabled status.

int sizeof(string objectOrClass)

Determines the memory consumption of a class or object.

Parameters:objectOrClass – The object or class being measured. Returns:Returns the total size of an object in bytes.

void telnetSetParameters(int port, string consolePass, string listenPass, bool remoteEcho)

Initializes and open the telnet console.

Parameters:

• port – Port to listen on for console connections (0 will shut down listening).
• consolePass – Password for read/write access to console.
• listenPass – Password for read access to console.
• remoteEcho – [optional] Enable echoing back to the client, off by default.

void trace(bool enable)

Enable or disable tracing in the script code VM. When enabled, the script code runtime will trace the invocation and returns from all functions that are called and log them to the console. This is helpful in observing the flow of the script program.

Parameters:enable – New setting for script trace execution, on by default.

void validateMemory()

Used to validate memory space for the game.

Variables

int getAppVersionNumber

Get the version of the application build, as a string.

string getAppVersionString

Get the version of the aplication, as a human readable string.

string getBuildString

Get the type of build, “Debug” or “Release”.

string getCompileTimeString

Get the time of compilation.

string getEngineName

Get the name of the engine product that this is running from, as a string.

int getVersionNumber

Get the version of the engine build, as a string.

string getVersionString

Get the version of the engine build, as a human readable string.

Logging

Functions for logging messages, warnings, and errors to the console.

Classes

• ConsoleLogger

Enumeration

enum LogLevel

Priority levels for logging entries.

Parameters:

• normal – Lowest priority level, no highlighting.
• warning – Mid level priority, tags and highlights possible issues in blue.
• error – Highest priority level, extreme emphasis on this entry. Highlighted in red.

Functions

void dumpConsoleClasses(bool dumpScript, bool dumpEngine)

Dumps all declared console classes to the console.

Parameters:

• dumpScript – Optional parameter specifying whether or not classes defined in script should be dumped.
• dumpEngine – Optional parameter specifying whether or not classes defined in the engine should be dumped.

void dumpConsoleFunctions(bool dumpScript, bool dumpEngine)

Dumps all declared console functions to the console.

Parameters:

• dumpScript – Optional parameter specifying whether or not functions defined in script should be dumped.
• dumpEngine – Optional parameter specitying whether or not functions defined in the engine should be dumped.

void echo(string message, ...)

Logs a message to the console. Concatenates all given arguments to a single string and prints the string to the console. A newline is added automatically after the text.

Parameters:message – Any number of string arguments.

void error(string message, ...)

Logs an error message to the console. Concatenates all given arguments to a single string and prints the string to the console as an error message (in the in-game console, these will show up using a red font by default). A newline is added automatically after the text.

Parameters:message – Any number of string arguments.

void log(string message)

Logs a message to the console.

Parameters:message – The message text.

void logError(string message)

Logs an error message to the console.

Parameters:message – The message text.

void logWarning(string message)

Logs a warning message to the console.

Parameters:message – The message text.

void setLogMode(int mode)

Determines how log files are written. Sets the operational mode of the console logging system. Additionally, when changing the log mode and thus opening a new log file, either of the two mode values may be combined by binary OR with 0x4 to cause the logging system to flush all console log messages that had already been issued to the console system into the newly created log file.

Parameters:mode – Parameter specifying the logging mode. This can be:1: Open and close the console log file for each seperate string of output. This will ensure that all parts get written out to disk and that no parts remain in intermediate buffers even if the process crashes.2: Keep the log file open and write to it continuously. This will make the system operate faster but if the process crashes, parts of the output may not have been written to disk yet and will be missing from the log.

void warn(string message, ...)

Logs a warning message to the console. Concatenates all given arguments to a single string and prints the string to the console as a warning message (in the in-game console, these will show up using a turquoise font by default). A newline is added automatically after the text.

Parameters:message – Any number of string arguments.

Messaging

Script classes and functions used for passing messages and events between classes.

Classes

• EventManager
• Message
• MessageForwarder
• ScriptMsgListener

Functions

bool dispatchMessage(string queueName, string message, string data)

Dispatch a message to a queue.

Parameters:

• queueName – Queue to dispatch the message to
• message – Message to dispatch
• data – Data for message

Returns:

True for success, false for failure

bool dispatchMessageObject(string queueName, string message)

Dispatch a message object to a queue.

Parameters:

• queueName – Queue to dispatch the message to
• message – Message to dispatch

Returns:

true for success, false for failure

bool isQueueRegistered(string queueName)

Determines if a dispatcher queue exists.

Parameters:queueName – String containing the name of queue

bool registerMessageListener(string queueName, string listener)

Registers an event message.

Parameters:

• queueName – String containing the name of queue to attach listener to
• listener – Name of event messenger

void registerMessageQueue(string queueName)

Registeres a dispatcher queue.

Parameters:queueName – String containing the name of queue

void unregisterMessageListener(string queueName, string listener)

Unregisters an event message.

Parameters:

• queueName – String containing the name of queue
• listener – Name of event messenger

void unregisterMessageQueue(string queueName)

Unregisters a dispatcher queue.

Parameters:queueName – String containing the name of queue

Packages

Functions relating to the control of packages.

Functions

void activatePackage(string packageName)

Activates an existing package. The activation occurs by updating the namespace linkage of existing functions and methods. If the package is already activated the function does nothing.

void deactivatePackage(string packageName)

Deactivates a previously activated package. The package is deactivated by removing its namespace linkages to any function or method. If there are any packages above this one in the stack they are deactivated as well. If the package is not on the stack this function does nothing.

string getFunctionPackage(string funcName)

Provides the name of the package the function belongs to.

Parameters:funcName – String containing name of the function Returns:The name of the function’s package

string getMethodPackage(string, string method)

Provides the name of the package the method belongs to.

Parameters:

• namespace – Class or namespace, such as Player
• method – Name of the funciton to search for

Returns:

The name of the method’s package

string getPackageList()

Returns a space delimited list of the active packages in stack order.

bool isPackage(string identifier)

Returns true if the identifier is the name of a declared package.

Scripting

Functions for working with script code.

Classes

• ArrayObject
• ScriptGroup
• ScriptObject
• ScriptTickObject

Functions

string 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. Returns:The result of the function call.

Example:

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

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

bool 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.

Returns:

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

void deleteVariables(string pattern)

Undefine all global variables matching the given name pattern .

Parameters:pattern – A global variable name pattern. Must begin with ‘$’.

Example:

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

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

bool exec(string fileName, bool noCalls, bool journalScript)

Execute the given script file.

Parameters:

• fileName – Path to the file to execute
• noCalls – Deprecated
• journalScript – Deprecated

Returns:

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

Example:

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

bool 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

Returns:

True if script was successfully executed

void 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.

Example:

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

string 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. Returns:The absolute path to the .dso file for the given script file.

string getVariable(string varName)

Returns the value of the named variable or an empty string if not found. Name of the variable to search for

Returns:Value contained by varName, “” if the variable does not exist

bool isDefined(string varName)

Determines if a variable exists and contains a value.

Parameters:varName – Name of the variable to search for Returns:True if the variable was defined in script, false if not

Example:

isDefined( "$myVar" );

bool isFunction(string funcName)

Determines if a function exists or not.

Parameters:funcName – String containing name of the function Returns:True if the function exists, false if not

bool isMethod(string, 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

Returns:

True if the method exists, false if not

void 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

Returns:

True if variable was successfully found and set