TorqueScript/IDE/Guide/DebuggerForTorque
From TDN
Contents |
Introduction
...
Download
Debugger for Torque (Linux and Windows)
Local Mirror (v2.4, Zip format)
Installation
Linux Installation
Install it in you home directory or in your /usr/... directory
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 :
1) 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");
}
}
2) in engine/console/telnetDebugger.h:
add after :
S32 mStackPopBreakIndex; bool windowLockedTrueFalse;
add after :
void processConsoleLine(const char *consoleLine); void setwindowLockedDebug(bool continu);
3) in engine/platform/platform.h:
add after :
static void setWindowLocked(bool locked); static bool getWindowLocked();
4) in engine/platformX86UNIX/x86UNIXWindow.cc:
add after :
void Platform::setWindowLocked(bool locked)
{
....
}
bool Platform::getWindowLocked(){
#ifndef DEDICATED
return x86UNIXState->windowLocked();
#endif
}
5) in engine/platformWin32/winWindow.cc:
add after :
void Platform::setWindowLocked(bool locked)
{
...
}
bool Platform::getWindowLocked(){
return windowLocked;
}
6) in engine/platformMacCarb/macCarbEvents.cc:
add after :
void Platform::setWindowLocked(bool locked)
{
...
}
bool Platform::getWindowLocked(){
return platState.mouseLocked ;
}
Software Requirements
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)
Windows Installation
Recommended: you can patch Torque as explained above.
Install it in your personal directory or in your C:\... directory
Software Requirements
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
Foot Notes
Author: Philippe C
Original Page: Debugger Documentation
