UnrealScript Debugger Interface

Overview

Let's look at the typical debugging session and what goes in to it. Before you can debug UnrealScript you need to compile your scripts in debug mode (by adding "-debug" to the command line, e.g. UDK make -debug). This adds additional control and mapping information to the compiled packages. Once you have scripts that are compiled with debug information, you can activate the debugger in the engine via one of two methods. The first, is by using the "-autodebug" command line switch which causes UE3 to activate the script debugger the moment the first UnrealScript bytecode is processed. Alternatively, the "toggledebugger" console command can be used from the game console to activate the debugger and immediately break.

Let's look at what happens when you activate the debugger (using either method):

1. First UE3 loads the interface DLL. By default, it will load the file "DebuggerInterface.dll" however this setting can be override in the Debugger.ini file. This DLL is the conduit for sending debug commands to the engine and getting results back.
   
2. Once loaded, UE3 immediately calls the exported function SetCallback() which creates the communication conduit back to the engine. It then clears the 3 variable watch lists (locals, globals, and user watches).
   
3. Finally, it calls the exported function ShowDllForm which then displays or activates the debugger.
   

The original external debugger interface was a small Borland Delphi forms DLL and the interface has remained the same for backwards compatibility. Let's look at the functions that need to be exported from the interface DLL.

Interface

There are 19 functions that the debugger interface needs to implement. They are:

void SetCallback(void* CallbackFunc)
 This is the most important function in to manage in the DLL. When first activated, the engine attempts to setup a callback through this function. You should store the function pointer passed in and use it to communicate with the engine later. We will discuss what commands can be sent later on.

void ShowDllForm()
 When called, ShowDLLForm() needs to be able to activate the window of the debugger and make it visible.

void BuildHierarchy()
void ClearHierarchy()
These two functions are called when the engine wants to signal the debugger that is it about to send over the currently loaded class hierarchy. Between them, UE3 will make several AddClassToHierarchy() calls, passing in a tree of all classes loaded.

void AddClassToHierarchy(const char* ClassName)
This function is used to add a class to the debugger's class hierarchy. The original debugger maintained a list of loaded class in a hierarchal tree view. This information is passed as strings using the following format: .. So for example you might have: "core..object" (because object has no parent) "engine.object.actor" "utgame.gameinfo.utgame" What the debugger does with this information is up to the external application.

void ClearWatch(int WatchType)
void ClearAWatch(int WatchType)
UE3 supports 3 different types of watches: locals, globals and user watches. This function is called when UE3 wants to clear one of those lists. It supports the following watch types:

1. Local Watches
   
2. Global Watches
   
3. User Watches
   

int AddAWatch(int WatchType, int ParentIndex, const char* VarName, const char* VarValue)
The engine uses this function to update the debuggers watch list. A single variable often results in multiple AddAWatch() calls. For example, adding a watch for a vector (a struct with 3 children) will result in 4 AddAWatch() calls: the first call for the variable and 3 calls for X, Y and Z. The parameters for this function are:

   • WatchType: The watch type is the same type of value used in ClearWatch().
   • ParentIndex: This is the unique index of its parent in the current object. As the engine recurses through an object looking for members variables to add, each one will get a unique index.
   • VarName: This is the name of the variable.
   • VarValue: This will be the value to display or additional display data about the variable.

The return result for AddAWatch() needs to be a unique ID that describes this particular variable in a watch list.

Let's look at the vector example more closely. Take the following script code:

function TestFunc()
{
    local vector TestVec;
    TestVec.X = 10;
    TestVec.Y=20;
    TestVec.Z=30;
    log(TestVec);
}

If you set a breakpoint on the log statement, when the debugger breaks, the first thing UE3 does is clear the local watches using ClearWatch(0). It then attempts to add the watch for TestVec. This results in the following AddAWatch() calls:

AddAWatch(0, 0, "!TestVec",""); // Should return 1
AddAWatch(0,1,"X","10"); // Should return 2
AddAWatch(0,1,"Y","20"); // Should return 3
AddAWatch(0,1,"Z","20"); // Should return 4

void LockList(int WatchList)
void UnlockList(int WatchList)
These two functions are called when UE3 is about to make an update to a given watch list. The debugger should take whatever steps needed to make the update as smooth as possible until the UnlockList() function is called.

void AddBreakpoint(const char* ClassName, int LineNo)
void RemoveBreakpoint(const char* ClassName, int LineNo)
When UE3 needs to add to the display a breakpoint that it is tracking, it calls AddBreakPoint to register it with the debugger. ClassName is the name of the class where the breakpoint exists and LineNo is the line number. The external debugger is responsible for tracking these and displaying the breakpoint on the associated line. Likewise, RemoveBreakPoint() tells the debugger to remove an existing breakpoint.

void EditorLoadClass(const char* ClassName)
UE3 uses this function to instruct the debugger to load the script for the class specified by the ClassName variable. ClassName is be passed as .. The debugger will be responsible for splitting the string and loading the proper file.

void EditorGotoLine(int LineNo, int bHighlight)
UE3 uses this function to instruct the debugger to display a specific line in the current source file. NOTE that EditorGotoLine() will always be preceded by an EditorLoadClass() call.

void AddLineToLog(const char* Text)
UE3 calls this function when it needs to output something to the debugger's log file. Text is the string to add.

void CallStackClear()
When UE3 breaks and needs to update the call stack in the debugger, the first thing it will do is execute a CallStackClear(). This should signal the debugger that UE3 wants to rebuild the calls stack.

void CallStackAdd(const char* CallStackEntry)
After a break, UE3 makes several CallStackAdd() calls in order to build the call stack on the debugger. The debugger should take the data the comes in and display it somewhere. The CallStackEntry is a string that contains the class name as well as line number.

void SetCurrentObjectName(const char* ObjectName)
UE3 uses this function to set the name of the current object in the debugger. It's called during each internal update call. You can do with this information as you see fit.

void DebugWindowState(int StateCode)
This function is not currently used.

The Callback

We've examined how UE3 communicates with the debugger, now lets look at the other direction. The debugger needs to communicate with UE3 via the callback function. When the interface DLL is bound to the engine, the engine will register its callback. Through this callback, you can pass several commands and all are passed as strings.

The typedef for the callback is as follows:

typedef void (*CallbackPointer)(const char*);

Here is list of commands:

addbreakpoint

<classname>  <linenumber>

<classname>  <linenumber>

<varname>

<varname>

<stackid>

<watchtext>

<0=false|1=true>