page updated the 31st of December 2007
Linux Installation
Windows Installation
Quick start
Reference Documentation
Version History
Linux Installation
Patch
for Torque : mandatory for Linux
In order to use the debugger for torque you are obliged to patch the
torque C++ code and to compile it.
There is a bug in Torque which freeze the Linux OS ( Ubuntu )
Apply the following patches :
in engine/console/telnetDebugger.cc :
add
after :
void
TelnetDebugger::breakProcess()
{
// check and update the window
status
setwindowLockedDebug(false) ;//PHC
...
}
add
after :
void
TelnetDebugger::debugContinue()
{
// restore the window state as it
was before the break
setwindowLockedDebug(true); //PHC
...
}
add at the bottom of the file this new function :
// This
function fixes an issue on windows and a blocking issue on unix .
// This issue appears in debug mode when the cursor is off (game mode)
and a break is send by the debugger.
//
// -windows : after the break the cursor appears after few seconds and
a lot of move and click with the mouse.
// -Unix : after the break the system is definitively frozen , only
solution : push the reset button on the PC
// :-(
//
// => the main reason of this behavior is that when the cursor
is off : the game window is locked.
// It means that the mouse stay focus on the window and you can not
click outside,
// this is a normal behavior in order move the player , shoot, ...
// When the debugger do a break : the game stop and the debugger wait
for a command.
// But the mouse is always blocked in the game window : it is dead lock
//
// => the solution is to unlock the cursor in the game window
when a break is send by the debugger and
// to restore the state when the debug action is finished ( see
TelnetDebugger::debugContinue)
// If the cursor is on : nothing should be done.
//
void TelnetDebugger::setwindowLockedDebug(bool continu)
{
if (
Platform::getWindowLocked())
{
// put the cursor off
Platform::setWindowLocked(false);
windowLockedTrueFalse = true;
send("DEBUGGER window-unLocked\r\n");
}
if ( continu
&& windowLockedTrueFalse )
{
// put the cursor on if needed
Platform::setWindowLocked(true);
windowLockedTrueFalse = false;
send("DEBUGGER window-Locked\r\n");
}
}
in engine/console/telnetDebugger.h :
add after :
S32 mStackPopBreakIndex;
bool
windowLockedTrueFalse;
add after :
void processConsoleLine(const
char *consoleLine);
void
setwindowLockedDebug(bool continu);
in engine/platform/platform.h :
add after :
static void setWindowLocked(bool
locked);
static bool getWindowLocked();
in engine/platformX86UNIX/x86UNIXWindow.cc :
add after :
void
Platform::setWindowLocked(bool locked)
{
....
}
bool
Platform::getWindowLocked(){
#ifndef DEDICATED
return x86UNIXState->windowLocked();
#endif
}
in engine/platformWin32/winWindow.cc :
add after :
void
Platform::setWindowLocked(bool locked)
{
...
}
bool
Platform::getWindowLocked(){
return windowLocked;
}
in engine/platformMacCarb/macCarbEvents.cc :
add after :
void
Platform::setWindowLocked(bool locked)
{
...
}
bool
Platform::getWindowLocked(){
return platState.mouseLocked ;
}
Software to install
Python
: this
software has been tested on Ubuntu edgy with Python 2.4.4c1
wxPython : this software has
been tested on
Ubuntu edgy with wxPyhton 2.6.0 ( python-wxversion, libwxbase2.6-0,
python-wxgtk2.6, libwxgtk2.6-0)
Debugger for Torque installation
Download the files :
debugger
for torque
Install it in you home
directory or in your /usr/... directory
Windows
Installation
Quick start
In this quick start we
will use the directory example provided with Torque as a basis for the
explanation.
1- Set up the connection
1-1 Click on the menu :
File/'Create or Update Debugger Parameters'
1-2 Select you game directory with the browse button
1-3 Let the default parameters
on windows change
torqueDemo_DEBUG.bin by torqueDemo_DEBUG.exe ( use the browse button to
select it)
1-4 Click on the 'OK' button
In launch parameters command line parameters could be added :
For instance in dedicated mode : -nohomedir -dedicated -mission game/data/missions/test.mis
2- Set the break Point
2-1 Double click in the
tree on "main.cs'
2-2 Move the text until the line 258 appears
2.3 Click in the margin : the red circle will appear and if you select
the tab 'Break Point' you will see the list of 'brak points'
3- Start the debugger
3-1 Click on the button as
below
4- The debugger is ready
This information panel
appears each time that a break point is reached by the debugger.
The blue arrow id positionned on the breaked line.
4-1 click on OK
5- Debugging can start
5-1 click on stepin button
in oder to start the debugging
5-2 The values od the variables used in the function are dispalyed in
the bottom on the window in the 'Watch Values' tab.
5-3 If you click on the
tab 'call stack' : the stack of functions is displayed :
at the top of the list you
see the call of first function called and at the bottom of the list the
current one.
In the middle you have the function called by the function above.
5-4 If you click on the
tab 'compilation errors' : all the errors displayed during scripts
compilation are listed
5-5 If you click on the
tab 'Torque log' : the torque log is displayed
5-6 If you click on a variable and click on Dump the content of the object is dispalyed in the window "Dump display"
Herefater the result :
6- Launch the game
6-1 Click on the button
continue in order to launch the game and continue the debugging in an
other part of the scripts
7- The game is launched
7-1 you can come back to
the chapter 2 in order to set a new break point and continue the
debugging
8 - If the game/debugger seems frozen on LINUX
If you don't see the mouse pointer after starting debugging or after relaunching the game : don't panic !
=> use "escape" key to display the "quit mission" panel , click on "no" and continue to play.
The display of the "quit mission" panel reset the torque engine.
9 - Limitation
It is not possible to have 2 debuggers launched in the same time :
If you launch a client/server application, the client or the server could be debugged, not the both.
I don't know how to solve this issue.
Reference Documentation
IN
WORK

Version
history
version 2.4, 10th of february 2008
- the text could be edited and save in the debugger, the associated .dso file
is automatically updated. Add a new icon to the toolbar in order to save the text
- add 2 new buttons in toolbar :
- save : save the updated program
- dump : aftre selection of a object in "watch values" teh conetcnt of object
is displayed in a dedicated window
Version 2.3 , 3rd of february 2008
- Torque in dedicated mode could be debug with the Torque debugger.
But only one Torque could be debug : the dedicated server or the client
- add new compilation error :
"Unable to find function"
"Missing terrain texture"
"Enable to load"
- start debug
reset tabs on the botton on the screen
- parameters
- Add torque program name into the file name in order to identify the different way
to launch the torque engine : torque, torque debug, torque dedicated, ...
- The field "launch parameter" could be completed with all the parameters used by Torque
Version 2.2.1, 31 dec 2007 : bugs fixes
- toolbar "start" : put in
comment the parameters dbgSetParameters in main.cs
- menu "close all files" : launch the right action instead of help
Version 2.2, 30 dec 2006: new functionalities- add a syntax coloration
to the script code.
- add a menu to extract from the Torque source code all the datablocks
, methods and functions usable by scripts .
Version 2, 30 aug 2006 : first release