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

recommended : you can patch Torque as explained here

install
    python
    wxpython

    debugger for torque
Install it in your personal directory or in your C:\... directory

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

connection


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'

break point

3- Start the debugger

3-1 Click on the button as below
start


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
debugger ready


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.
step in


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.

call stack


5-4 If you click on the tab 'compilation errors' : all the errors displayed during scripts compilation are listed

compilation


5-5 If you click on the tab 'Torque log' : the torque log is displayed

torquelog

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

contniue

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

torque launch


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