Introduction

Torque provides some powerful debugging features for TorqueScript developers. This page describes the low level protocol for communication with the TelnetDebugger. Unless you're developing a debugging tool you are better served by selecting an existing TorqueScript IDE.

Initialization

Before a debug client can connect you need to setup the TelnetDebugger server. Using the following console function you can set the connection port, password string, and as of 1.4 you can optionally halt script execution until a client connects:

dbgSetParameters( port, password [, waitForClient] );

 // Example:
 dbgSetParameters( 6060, "torqueiscool" );

You can either type this into the console with your game running or you can put the line into main.cs, for example. Once those parameters are set, you can use your IDE/debugger of choice to connect using the port and password while your game is running.

Another method to set the TelnetDebugger settings involves the command line options -dbgPort and -dbgPassword to set these parameters on launch.

Protocol Overview

The TelnetDebugger implements a simple plain text protocol. Each command sent or recieved on a connection is terminated by carriage return and line feed pair ("\r\n"). Note that this means that you cannot pass data with embedded "\r\n"s. The simplicity of this protocol makes for quick development of tools.

Connecting

When a client first connects to the TelnetDebugger server the first thing it expects to recieve is the password followed by a "\r\n". If the password is correct the client will receive the string "PASS Connected." from the server. If it is incorrect you will get "PASS WrongPassword." and the connection will be dropped.

Now once the password is accepted you will be in one of two states. If waitForClient was not set or set to false when you initialized the TelnetDebugger server then script execution will continue.

If you have set waitForClient to true then the connection will now be in a waiting state. This gives your tool time to send some initial commands like setting startup breakpoints. Once you're ready for the debug session to start you either send the command CONTINUE to continue script execution or STEPIN to have the debugger break on the next line of execution. Both of these commands are explained below.

Commands

These are the commands a client can send to the TelnetDebugger server.

CEVAL consoleLine

This evaluates the console line. This only works when the TelnetDebugger is in a running state. Nothing is returned from the server, but any echo will be sent to the console output.

BRKVARSET varName passct expr

Not yet implemented!

BRKVARCLR varName

Not yet implemented!

BRKSET file line clear passCount expr

This sets a breakpoint on a particular file and line. It must pass passCount number times for it to break. If clear is true, the breakpoint will be cleared after hit. Use passCount 0 to break always. The expr will be evaluated when the breakpoint is reached and break if the result is true.

If the protocol version is 1 and the file is not currently loaded or the line is not a breakable line then the command is ignored and no breakpoint is set.

If the protocol version is 2 and the line is not a breakable line a BRKMOV or BRKCLR message is sent back to the client.

The expression is not optional, if you want to always break, pass true.

BRKNEXT

If the server is in the running state this will stop execution at the next breakable line.

BRKCLR file line

This clears a breakpoint if one is set at the file and line.

BRKCLRALL

This clears all breakpoints on the server.

CONTINUE

If the server is stopped this will continue script execution. It returns the message RUNNING to the client.

STEPIN

If script execution is stopped this steps to the next breakable line. It returns the message RUNNING to the client.

STEPOVER

If script execution is stopped this steps to the next breakable line within the current or calling stack frame. It returns the message RUNNING to the client.

STEPOUT

If script execution is stopped this steps to the next breakable line within the calling stack frame. It returns the message RUNNING to the client.

EVAL tag frame expr

Use this command to evaluate some script expression on the server. The expression can be any valid TorqueScript expression. The frame number specifies what callstack frame to execute the expression on, but doesn't work on the old version 1 protocol. The tag is a value (it can be a string or number) used by the client to identify the expression output. This command will return the message EVALOUT to the client.

FILELIST

This returns a list of script files currently loaded on the server. It returns the FILELISTOUT message.

BREAKLIST file

This returns a list of breakable lines for the file if it is loaded else a DBGERR message is sent. It returns the BREAKLISTOUT message.

Client Messages

These are messages the TelnetDebugger server sends to a connected client. This usually occurs as a response to a command, except for COUT which is returned everytime a line is added to the console log.

DBGERR errorMessage

Sent when we encounter an error with a command.

BREAK file1 line1 function1 file2 line2 function2 ...

Sent when the debugger hits a breakpoint. It lists out one file/line/function triplet for each stack level. The first one is the top of the stack.

COUT consoleOutput

This is sent for every line of text echoed to the console.

EVALOUT tag exprResult

Sent in response to an EVAL command, it returns the eval's tag and the result of the expression or "".

BRKMOV file line newline

This is sent when a BRKSET is being applied to a different line from what was originally requested by the client. This usually occurs when a breakpoint is requested on a line which contains no breakable code. This is only sent in version 2 of the protocol.

BRKCLR file line

This is sent when a BRKSET cannot be applied because a breakable line cannot be found for that file on or below the requested line. This is only sent in version 2 of the protocol.

RUNNING

This is sent whenever the server returns to a running state.

FILELISTOUT file1 file2 file3 file4 ...

Sent in response to the FILELIST command. Each is the file path relative to the root Torque folder for a script that is currently loaded.

BREAKLISTOUT file skipBreakCount skipLines breakLines skipLines breakLines ...

In response to a BREAKLIST command this message is sent with a list of skip/break line pairs. To get the actual breakable lines you loop for skipBreakCount incrementing your current line counter by skipLines and then adding each breakLines in sequence.

Special Variables

There are two special variables set by the TelnetDebugger server which a client can query via an EVAL command:

$Debug::protocolVersion

Contains the version of the debug protocol the TelnetDebugger supports. Version 1 is the original protocol pre-1.4. Version 2 is the new protocol found in 1.4. Use this number to detect older clients if you plan on supporting them.

$Debug::result

Temporary variable used in breakpoint and watch evaluation. You can query this to get the last evaluated result.

Known Bugs

There is currently no facility in the protocol for notifying the debugger about new scripts being loaded, so the debugger will have to discover these scripts when the game stops the next time. This means that you can't set a breakpoint in a script before that script has loaded, and expect to hit that breakpoint the first time the game gets to that point.

This is actually getting fixed (and is fixed on CVS). The server will send LOAD filename for each code block that gets loaded.