Section Index


1. OpenAL || 2. Debugging || 3. String Manipulation || 4. Networking || 5. Console || 6. Device I/O || 7. File I/O
8. Packages || 9. Objects || 10. Event Scheduling || 11. Datablocks || 12. Video / Texturing || 13. Special || 14. Resource Management
15. Scene || 16. Containers and Raycasts || 17. Editors || 18. Build || 19. Time || 20. GUIs || 21. Math


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.


Contents

Debugging

This category of console functions includes functions used to debug or to otherwise examine the scripting environment, the 3D world, engine performance, et cetera.



debug()

Purpose
Use the debug function to cause the engine to issue a debug break and to break into an active debugger.

Returns
No return value.

Notes
For this to work, the engine must have been compiled with either TORQUE_DEBUG, or INTERNAL_RELEASE defined.



dumpConsoleClasses()

Purpose
Use the dumpConsoleClasses function to prints all registered classes and the console methods associated with them to the console.

Returns
No return value.

Notes
This will dump all classes and methods that were registered from within the engine, AND from the console via scripts.

See Also
dumpConsoleFunctions



dumpConsoleFunctions()

Purpose
Use the dumpConsoleFunctions function to prints all registered functions to the console.

Returns
No return value.

Notes
This will dump all funtions that were registered from within the engine, AND from the console via scripts.

See Also
dumpConsoleMethods



setEchoFileLoads( enable )

Purpose
Use the setEchoFileLoads function to enable/disable echoing of file loads (to console).

Syntax
enable
– A boolean value. If ths value is true, extra information will be dumped to the console when files are loaded.

Notes
This does not completely disable messages, but rather adds additional methods when echoing is set to true. File loads will always echo a compile statement if compiling is required, and an exec statement at all times.



setInteriorRenderMode( mode )

Purpose
Use the setInteriorRenderMode function to enable various interior rendering modes used for mesh debugging.

Syntax
mode
– A numeric value between 0 and 16. Please see the 'Interior Render Modes' table below.

Returns
No return value.

Notes
For this to work, the engine must have been compiled with TORQUE_DEBUG defined.

See Also
GLEnableOutline



Render Mode
Mode Name
Meaning
0
Normal
 Normal.
1
Render Lines
 Render interior brush outlines only.
2
Detail
 Render interior brushes with flat coloration. White colored blocks indicate  brushes that do not change with LOD changes. Red colored blocks will change.
3
Ambiguous
 Shows ambiguous polygons. (Good models have none.)
4
Orphan
 Shows orphaned polygons. (Good models have none.)
5
Light Map
 Shows lightmaps on flat (white) shaded model.
6
Textures Only
 Shows textures without lightmaps.
7
Portal Zones
 Colorizes portalized zones to make them distinct and easily identifiable.
8
Outside Visible
 Marks insides of interiors as white and outsides as red.
 Tip: An interior with no portals is marked as all RED
9
Collison Fans
 Displays calculated (by exporter) collision fans with axes showing face  directions.
10
Strips
 Shows surfaces divided into colorized triangle strips. Each strip has a distinct  color from adjacent strips.
 Tip: Large triangles generally give best performance, but strips can be too large  in some instances.
11
NULL Surfaces
 Renders all faces with a NULL texture applied as RED.
 Tip: Excluding portals, no red surfaces should be visible without taking the  camera into walls, or you will have a hole/gap in your surface.
12
Large Textures
 All large textures will be rendered with a colorized shading:

 Blue - Width or height equal to 256 pixels.
 Green - Width or height equal to 512 pixels.
 Red - Width or height greater than or equal to pixels.
13
Hull Surfaces
 Renders HULL surfaces with distinct flat colors.
14
Vehicle Hull Surfaces
 Renders specialized Vehicle HULL surfaces with distinct flat colors.
15
Vertex Colors
---Currently Unavailable---
16
Detail Levels
 Renders entire interior at current LOD coloration. (See LOD colors below.)



Level of Detail (LOD)
Debug Color
0
White
1
Blue
2
Green
3
Red
4
Yellow
...
Please see source code.



playJournal( namedFile , doBreak )

Purpose
Use the playJournal function to play back a journal from namedFile and to optionally break (into an active debugger) after loading the Journal. This allow us to debug engine bugs by reproducing them consistently repeatedly.

Syntax
namedFile
– A full path to a valid journal file. Usually, journal names end with the extension .jrn.
doBreak – A boolean value. If true, the engine will load the journal and then assert a break (to break into an active debugger). If not true, the engine will play back the journal with no break.

Returns
No return value.

Notes
The journaling system is a vital tool for debugging complex or hard to reproduce engine and script bugs.

See Also
saveJournal

playJournal(  "~/myJournal.jrn"  , true );  // Break after loading journal.
playJournal(  "~/myJournal.jrn"  ); // Just play journal 



saveJournal( namedFile )

Purpose
Use the saveJournal function to save a new journal of the current game.

Syntax
namedFile
– A full path specifying the file to save this journal to. Usually, journal names end with the extension .jrn.

Returns
No return value.

See Also
playJournal

saveJournal( "~/myJournal.jrn" );



inputLog( fileName )

Purpose
Use the inputLog function to enables/disable logging of DirectInput events to a log file specified by fileName.

Syntax
fileName
– A valid path to a file in which to store a log of DirectInput events.

Returns
For this to work, the engine must have been compiled with LOG_INPUT defined.

Notes
Once started, input logging cannot be stopped, so only apply this in debug scenarios.

See Also
setLogMode

inputLog( "DirectInput.log");



setLogMode( mode )

Purpose
Use the setLogMode function to set the logging level based on bits that are set in the mode argument.

Syntax
mode
– A bitmask enabling various types of logging. See 'Logging Modes' table below.

Returns
No return value.

Notes
This is a general debug method and should be used in all but release cases and perhaps even then.

See Also
intputLog

SetLogMode( 6 ); // Dump console output before this to file and leave file open.



Mode Bitmask
Description
1
Open file and append. Close file on each log write. This allows us to edit the file in a separate editor without having to quit and without getting a file lock conflict.
2
Open file and leave it open. This is more efficient for lots of logging, but we may not be able to view the file till we exit the game. (Note: *NIX users can just tail the file: 'tail -fn 100 filename')
4
Dump anything that has been printed to the console so far. This is needed because the console doesn't get turned on right away, and some output would otherwise be missed.



dumpUnflaggedAllocs( fileName )

Purpose
Use the dumpUnflaggedAllocs function to dump all allocations that were made subsequent to a call to flagCurrentAllocs. This function, in association with flagCurrentAllocs, is used for detecting memory leaks and analyzing memory usage in general.

Syntax
filename
– A valid path and filename in which to dump the current memory allocation information.

Returns
No return value.

Notes
For this to work, the engine must have been compiled with DEBUG_GUARD defined.

See Also
flagCurrentAllocs



flagCurrentAllocs()

Purpose
Use the flagCurrentAllocs function to mark all current memory allocations in preparation for a subsequent call or calls to dumpUnflaggedAllocs. This function, in association with dumpUnflaggedAllocs, is used for detecting memory leaks and analyzing memory usage in general.

Returns
No return value.

Notes
For this to work, the engine must have been compiled with DEBUG_GUARD defined.

See Also
dumpUnflaggedAllocs



freeMemoryDump()

Purpose
Use the freeMemoryDump function to dump the current 'memory free' statistics to the console.

Returns
No return value.

Notes
This does not print how much memory is free, but rather an analysis of 'free chunks' of memory.



GLEnableLogging( enable )

Purpose
Use the GLEnableLogging function to enable/disable the gathering of OpenGL metrics.

Syntax
enable
– A boolean value. If set to true, the engine will gather various OpenGL metrics and dump them to a file named gl_log.txt. If set to false, logging is stopped, the last writes to the log are flushed, and the file is closed.

Returns
No return value.

Notes
For this to work, the engine must have been compiled with either TORQUE_DEBUG or INTERNAL_RELEASE defined. Always be sure to do a disable after an enable to flush the last log data to the log file.

See Also
GLEnableMetrics, metrics



GLEnableMetrics( enable )

Purpose
Use the GLEnableMetrics function to enable or disable logging of OpenGL texture and video metrics.

Syntax
enable
– A boolean value. When this is set to true, texture and video (triangles and primitives) logging is enabled and dumped as part of calls to certain metrics.

Returns
No return value.

Notes
For this to work, the engine must have been compiled with either TORQUE_DEBUG or INTERNAL_RELEASE defined. Use the metrics function to get at this information. Also, once this feature is enabled, the following globals will be available for inspection/examination:

OpenGL::triCount0 – Terrain triangles
OpenGL::triCount1 – DIF triangles
OpenGL::triCount2 – DTS triangles
OpenGL::triCount3 – Uncategorized triangles

OpenGL::primCount0 - Terrain primitives
OpenGL::primCount1 – DIF primitives
OpenGL::primCount2 – DTS primitives
OpenGL::primCount3 – Uncategorized primitives

See Also
GLEnableLogging, metrics



metrics( metric )

Purpose
Use the metrics function to enable a display of specified metric information in upper left corner of screen.

Syntax
metric
– The class of metrics to display. Please see the 'metric' table below for specific metrics.

Returns
No return value.

Notes
For this to work, the engine must have been compiled with TORQUE_DEBUG defined.

See Also
GLEnableMetrics



Metric
Measures
audio

 fps metrics +
 OH: Open Handles
 OLH: Open Looping Handles
 AS: Active Streams
 NAS: Null Active Streams
 LAS: Active Looping Streams
 LS: Total Looping Streams
 ILS: Inactive Looping Streams
 CLS: Culled Looping Streams

debug

 fps metrics +
 NTL: Texels Loaded.
 TRP: Percentage of resident memory (on card) used by textures.
 NP: Number of primitves being rendered.
 NT: Number of textures in use.
 NO: Number of objects being rendered.

interior

 fps metrics +
 NTL: Texels Loaded.
 TRP: Percentage of resident memory (on card) used by textures.
 INP: Number of primitves being rendered, for interiors only.
 INT: Number of textures in use, for interiors only.
 INO: Number of objects being rendered, for interiors only.

fps

 FPS: Frames Per Second
 MSPF: Milliseconds per frame

time

 fps metrics +
 Sim Time: Sim time to date. Time since engine started.
 Mod: Ticks since engine started.

terrain

 fps metrics +
 L0: Numer of terrain blocks rendering at level zero.
 FMC: Full mipmap count.
 DTC: Dynamic texture count.
 UNU: Unused texture count.
 STC: Static texture count.
 DTSU: Dynamic texture space used.
 STSU: Static texture space used.
 FRB: Terrain blocks not rendered due to full fogging.

texture

Requires: GLEnableMetrics(true);

 fps metrics +
 NTL: Number of texels loaded.
 TRP: Percentage of resident memory (on card) used by textures.
 TCM: Texture cache misses.

video

Requires: GLEnableMetrics(true);

 fps metrics +
 TC: Total triangle count.
 PC: Total primitive count.
 T_T: Terrain triangle count.
 T_P: Terrain primitive count.
 I_T: Interiors triangle count.
 I_P: Interiors primitive count.
 TS_T: Shape (DTS) triangle count.
 TS_P: Shape (DTS) primitive count.
 ?_T: Uncategorized triangle count.
 ?_P: Uncategorized primitive count.

vehicle

 fps metrics +
 R: Integration retry count.
 C: Search count.
 P: Polygon count for vehicles.
 V: Vertex count for vehicles.

water

 fps metrics +
 Tri#: Water triangle count.
 Pnt#: Water point (vertex) count.
 Hz#: Water haze point count.



dbgSetParameters ( port , password )

Purpose
Use the dbgSetParameters function to set the debug connection password for a specific port.

Syntax
port
– The IP port to set the password on.
password – The password for this port. Set this to a NULL string to clear the password for the port.

Returns
No return value.

dbgSetParameters( 1130 , “edochi” );



dNetSetLogging( enable )

Purpose
Use the dNetSetLogging function to enable (or disable) network packet logging to the console.

Syntax
enable
– A boolean value. If set to true, network packet logging is enabled, otherwise it is disabled.

Returns
No return value.

dnetSetLogging(1);



profilerDump()

Purpose
Use the profilerDump function to dump engine profile statistics to the console.

Returns
No return value.

Used to dump NetStringTable statistics to the console

profilerDump();



profilerDumpToFile( filename )

Purpose
Use the profilerDumpToFile function to dump engine profile statistics to a file.

Syntax
filename
– A string value specifying a full or partial path to a file for writing the profiler statistics to.

Returns
No return value.



profilerEnable( enable )

Purpose
Use the profileEnable function to enable (or disable) engine profiling.

Syntax
enable
– A boolean value. If set to true and the engine was compiled with DEBUG specified, engine profiling is enabled, otherwise it is disabled.

Returns
No return value.

Note
TGE 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.

Please read GPGTGE Volume 2 to learn more about this.

profilerEnable(false);



profilerMarkerEnable( markerName , enable )

Purpose
Use the profilerMarkerEnable function to enable (or disable) specific profiling markers.

Syntax
markerName
– The name of a marker (as specified using the C++ MACRO PROFILER_START) to be enabled/disabled.
enable – A boolean value. If set to true, the specified marker will be enabled for profiling, otherwise it will be disabled.

Returns
No return value.

profilerMarkerEnable( mark , true );



profilerReset( )

Purpose
Use the profilerReset function to reset the profile gathering mechanism. This clears the current counters, but all markers retain their current enable/disable status.

Returns
No return value.



backtrace()

Purpose
Use the backtrace function to print the current callstack to the console. This is used to trace functions called from within functions and can help discover what functions were called (and not yet exited) before the current point in your scripts.

Returns
No return value.



trace( enable )

Purpose
Use the trace function to enable (or disable) function call tracing. If enabled, tracing will print a message every time a function is entered, showing what arguments it received, and it will print a message every time a function is exited, showing the return value (or last value of last statement) for that function.

Syntax
enable
– A boolean value. If set to true, tracing is enabled, otherwise it is disabled.

Returns
No return value.


Section Index


1. OpenAL || 2. Debugging || 3. String Manipulation || 4. Networking || 5. Console || 6. Device I/O || 7. File I/O
8. Packages || 9. Objects || 10. Event Scheduling || 11. Datablocks || 12. Video / Texturing || 13. Special || 14. Resource Management
15. Scene || 16. Containers and Raycasts || 17. Editors || 18. Build || 19. Time || 20. GUIs || 21. Math