Search public documentation:
UE3 Home > Editor & Tools Programming > UnrealScript Debugger Interface
UE3 Home > UnrealScript > UnrealScript Debugger Interface
UE3 Home > UnrealScript > UnrealScript Debugger Interface
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):
- 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.
- 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).
- Finally, it calls the exported function ShowDllForm which then displays or activates the debugger.
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()
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:
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:
- Local Watches
- Global Watches
- User Watches
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;
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
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.
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
These commands are used to tell UE3 to add/remove breakpoints.
These commands tell UE3 to add/remove user defined watches. You should fully describe it (for example: pawn.playerreplicationinfo.playername). clearwatch
This command takes no parameters and will clear all user watches. changestack
This command causes the engine to jump to a given position in the callstack. setdatawatch
This command sets a breakpoint on data access of a given variable. breakonnone
Use the breakonnone command to instruct the debugger to break whenever an access none error occurs. break
Tells UE3 to break as soon as possible. stopdebugging
This command shuts down the debugger and stop the debugging session. go
These commands control the execution of the debugger. But wait.. so if I send the "addwatch" command to UE3 I get the AddAWatch() interface call? That's correct. Think of UE3 as where things happen, and your interface DLL as the thing that renders what's happening. So when you send the "addwatch" command, UE3 first verifies that the path to the object is valid, then it internally sets up a watch on that object and then when it's all done, it will tell the interface that it's watching a given object. It's that simple.. right :)
Before we end, let's look at what actually happens when you break the debugger. This should give you an idea of what to look for in your external application. When you send the "break" command to the callback, UE3 will start the process. It sets a flag that says break upon the execution of the next script byte code. When that happens, it performs several steps.
- UE3 tells the interface what class and line it's on through calls to EditorLoadClass() and EditorGotoLine().
- It then sets the ObjectName with SetCurrentObjectName.
- Next it refreshes all watches, first by calling ClearAWatch() and then calling AddAWatch() multiple times.
- It then refreshes the call stack by calling CallStackClear() followed by multiple calls to CallStackAdd().