Torque 3D - Script Manual: Debugging

TorqueScript

Main   Class List   Namespace List   Online

Debugging
[Console]

Functionality to help spot program errors. More...

Functions

void backtrace ()
 Prints the scripting call stack to the console log.
void debug ()
 Drops the engine into the native C++ debugger.
void debugDumpAllObjects ()
 Dumps all current EngineObject instances to the console.
void debugv (string variableName)
 Logs the value of the given variable to the console.
void dumpAlloc (int allocNum)
 Dumps information about the given allocated memory block.
void dumpMemSnapshot (string fileName)
 Dumps a snapshot of current memory to a file.
void dumpUnflaggedAllocs (string fileName="")
 Dumps all unflagged memory allocations.
void flagCurrentAllocs ()
 Flags all current memory allocations.
void freeMemoryDump ()
 Dumps some useful statistics regarding free memory.
void profilerDump ()
 Dumps current profiling stats to the console window.
void profilerDumpToFile (string fileName)
 Dumps current profiling stats to a file.
void profilerEnable (bool enable)
 Enables or disables the profiler.
void profilerMarkerEnable (string markerName, bool enable=true)
 Enable or disable a specific profile.
void profilerReset ()
 Resets the profiler, clearing it of all its data.
int sizeof (string objectOrClass)
 Determines the memory consumption of a class or object.
void telnetSetParameters (int port, string consolePass, string listenPass, bool remoteEcho=false)
 Initializes and open the telnet console.
void trace (bool enable=true)
 Enable or disable tracing in the script code VM.
void validateMemory ()
 Used to validate memory space for the game.

Variables

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 build, as a string.
string getVersionString
 Get the version of the build, as a string.

Detailed Description

Functionality to help spot program errors.

Also provides profiler functions, helpful in determining performance bottlenecks.


Function Documentation

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.

Note:
This function is not available in shipping builds.
void debugDumpAllObjects (  ) 

Dumps all current EngineObject instances to the console.

Note:
This function is only available in debug builds.
void debugv ( string  variableName  ) 

Logs the value of the given variable to the console.

Prints a string of the form "<variableName> = <variable value>" 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.
Note:
Available in debug builds only. In torqueConfig.h, TORQUE_DISABLE_MEMORY_MANAGER must be undefined to use this function.
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" );
Note:
Available in debug builds only. In torqueConfig.h, TORQUE_DISABLE_MEMORY_MANAGER must be undefined to use this function.
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
Note:
Available in debug builds only. In torqueConfig.h, TORQUE_DISABLE_MEMORY_MANAGER must be undefined to use this function.
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.

Note:
Markers disabled with profilerMarkerEnable() will be skipped over. If the profiler is currently running, it will be disabled.
void profilerDumpToFile ( string  fileName  ) 

Dumps current profiling stats to a file.

Note:
If the profiler is currently running, it will be disabled.
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.

Note:
Profiler is not available in shipping builds. T3D has predefined profiling areas surrounded by markers, but you may need to define additional markers (in C++) around areas you wish to profile, by using the PROFILE_START( markerName ); and PROFILE_END(); macros.
void profilerMarkerEnable ( string  markerName,
bool  enable = true 
)

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.
Note:
Calling this function will first call profilerReset(), clearing all data from profiler. All profile markers are enabled by default.
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 = false 
)

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 = true  ) 

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.


Variable Documentation

Get the type of build, "Debug" or "Release".

Get the time of compilation.

string getEngineName

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

Get the version of the build, as a string.

Get the version of the build, as a string.



Copyright © GarageGames, LLC. All Rights Reserved.