Samuel Savage
April 14, 2008
Susan Conry
A Graphical System for Debugging World of Warcraft User
Interface Scripts Enhanced with Automation
Abstract
The goal of my thesis is to investigate mechanisms for helping programmers debug World
of Warcraft application programming interface (API) scripts. These mechanisms should be
useful to those new to this API and those who have already developed long-standing
scripts. By providing extensive feedback, this project will help budding programmers
understand the syntax and dynamic behavior that the Lua and XML languages exhibit.
Those who have already attained a higher level of programming skill will be able to take
advantage of auto-correction routines and recommendations the system can make to
enhance their adherence to the standards of the languages.
This project will see completion in a graphical user interface that is able to partially
automate the process of debugging XML and Lua scripts using Blizzard’s API. The
completed system should be able to identify potentially problematic parts of code and
provide an explanation as to why the identified features have been flagged. It should keep
a table of variables and functions, both in the global API and in the user’s local code to
enable easy reference. It should update its own internal references and rules as the API is
updated over time and show functions that have become deprecated or protected. The
program should be able to fire events into the user’s interface in order to show what would
occur on specific events in comparison with the user’s desired response to those events. It
should be able to flag variables to be saved between sessions, track resource usage, autocomplete functions and variable names, auto-correct light syntax errors or provide possible
corrections, and give explanations for errors. It should be able to automatically generate
comments and enable the user to place breakpoints and step through each function.
Introduction
With just a few simple mouse clicks, a user can now completely customize the way an
operating system is themed. In various applications, such as Firefox and Thunderbird, the
user can also customize the application's "look and feel". In November, 2004, Blizzard
Entertainment, Inc. released World of Warcraft1, a game used by ten million people across
North America, Europe, and Asia that allows each player to customize his or her user
interface (UI) [2]. Blizzard provides a default game interface (written in Lua and XML)
that displays the game in the absence of a user-created interface. Blizzard encourages
users to create their own unique user interface that customizes the feel and interaction of
the game. Unfortunately, Blizzard does not provide a development environment for this.
Thus, there is currently no graphical tool that allows a coder to debug his or her scripts. In
order to tell if his/her code is working correctly, the programmer must have an active
World of Warcraft account and must run the game. For the effects of changes in the code
to be seen, the game must be completely exited and restarted. This can be costly, in time,
1
World of Warcraft is a massively multiplayer online role playing game. It enables thousands of players to
create a character and come together online to battle against the world and each other. To learn more, please
visit <http://www.worldofwarcraft.com/info/basics/guide.html>.
Samuel Savage
April 14, 2008
Susan Conry
money, and computer resources. A tool or system that allows interactive debugging of
World of Warcraft user interface scripts (and does so with automatic features) would be an
invaluable resource.
In order to develop a customized interface for World of Warcraft, the user must be familiar
with both Lua and XML. The dominant features of Lua are identified as follows:
"Lua is a powerful, fast, light-weight, embeddable scripting language. It combines
simple procedural syntax with powerful data description constructs based on
associative arrays and extensible semantics. Lua is dynamically typed, runs by
interpreting bytecode for a register-based virtual machine, and has automatic
memory management with incremental garbage collection, making it ideal for
configuration, scripting, and rapid prototyping." [3,4]
Extensible Markup Language (XML) is a self-descriptive data transmitter in the same
family of languages as HTML. In an XML script, the user creates his/her own tags to
represent various data forms. XML is used to create the visual frames and elements that
World of Warcraft displays. [5,6] Lua contains the functions and variables and XML
provides the graphical user interface.
Graphical debugging is not a new concept. Microsoft Visual Studio implements a
graphical system for debugging various programming languages. The theory of automated
debugging has also been around for quite some time [1]. A system that is able to
automatically detect infinite loops, identify grossly faulty code, and auto-correct some
kinds of errors would be an invaluable resource to any programmer.
General Implementation
I intend to use Microsoft Visual Studio C++ to implement the graphical user interface for
this project. There already exists add-on functionality for Visual Studio that enables a user
to write World of Warcraft UI scripts. My project would extend this environment to allow
interactive debugging of UI scripts. In the event that this is not a tractable problem, I could
develop the debugger as a stand-alone project. Because Lua and XML are scripting
languages, they do not need to be compiled. This makes a stand-alone implementation
easier, as it only has to interpret the language.
Specific Implementation
The overall goal of my project is to develop a graphical debugger for Blizzard’s World of
Warcraft API. The extension of this into a semi-automatic debugger would form the major
contribution of the project. As mentioned above, there are a few key features that the
debugger should exhibit.

Remembering variables and functions – In Lua, it is legal to use variables and
functions without declaring them beforehand. As the interpreter scans the language, it
remembers the variables and functions that the user uses. Because this language is not
-2-
Samuel Savage
April 14, 2008
Susan Conry
strongly typed, a programmer can sometimes miss-type names and inadvertently create
new variables. This mistake can cost the user innumerable hours debugging run-time
errors. To accomplish this feature, a mechanism would need to be built whereby the
user can be reminded of variables, constants, and names already in use. This would
require maintaining a structure similar to a compiler’s symbol table. The feature would
then make use of the information stored in this structure and would behave in a manner
similar to the Visual Studio API. It would display a drop down box with class member
names at appropriate times while a developer is typing new code.
If the system maintains information about the variables that a user uses, it can autocomplete these names, avoiding spelling errors altogether. Also having a knowledge
base of built in constants and API functions can help the user to avoid unnecessary
search. Thus the user could spend more time developing his/her algorithm and less
time implementing this algorithm. Heuristics could be used to suggest legal values for
different variables. In this way, the debugger can enforce type specification on
important variables, enabling it to flag assignment statements as valid or invalid. There
is already a rudimentary structure within the Visual Studio add-on that would facilitate
this development.
The values of some variables can be changed by the user as the UI runs. For instance,
if the background color of the UI defaults to blue and the user changes the background
color when running the UI, this updated value should be saved to a file before the game
is exited so that the next game session will look the same. World of Warcraft keeps a
special file for each UI add-on that maintains variables of this kind. This is called the
“SavedVariables” file. Customizable options are maintained in this file, allowing the
UI to remember the user’s variables from session to session. Being able to flag these
variables as “SavedVariables” in the script would ensure that the UI remembers their
values across run-times. The development of a “symbol table” would facilitate this.

Event firing and error handling – The World of Warcraft user interface is event
driven. This means that the functions in the script must run in response to events
occurring in the game. For the user to be able to tell if his/her functions work properly,
events would need to be fired into the UI. Currently, the author of a script may specify
a set of events for the event handler to capture. If an event occurs and the author has
not specified what should be done in response to that event, the system will not
respond to that event. The interface to be developed in this system would allow the
user to indicate what functions should be executing on occurrence of each event
through interaction with a graphical window. It would also notify the user if an
“unhandled” event occurs or an “incorrectly handled” event occurs. Thus, the GUI
would provide the user with a set of allowable event types and a set of user defined
functions. It would then permit the user to associate event types with functions, so that
the dynamic behavior can be effectively monitored.
To determine which events are incorrectly handled, the debugger must be able to watch
variables and functions to see if event triggers change them. If a function runs that has
not been associated with an event, the user should be notified. The debugger could
-3-
Samuel Savage
April 14, 2008
Susan Conry
also allow the user to specify an action to automatically associate these functions with
the “illegal” events, if that is the user’s intention.
Debugging scripts could be further facilitated by allowing the user to set breakpoints
and incrementally step through lines of code. At a breakpoint, execution would halt
and a set of active functions and pending events would be displayed. The user should
also be able to add variables to a watch window, thereby displaying their current value.
Employing assertion statements would add further functionality to the debugger and
allow the user to be notified when code does not behave according to plan.

Evolution as a language – There is a set of base functions made available for use in
the Blizzard API. Because Blizzard updates World of Warcraft regularly, some of
these changes made to the API could affect the graphical debugger. As Blizzard
releases online documentation for each change, some functions made available in the
API could become deprecated. These functions are no longer valid, as they have been
replaced by other functions, or removed altogether. Some functions are labeled as
protected. These functions cannot be used by user created interface scripts. They can
only be accessed by Blizzard-signed add-ons and the default user interface. Functions
and variables that have been deprecated or protected should be flagged by the debugger
for the user so that he/she may know not to use them. My system would make a list of
base functions available to the author through the GUI. This list would be maintained
periodically via access to the Blizzard web source. It would be able to access posted
changes to change its log of available functions, reflecting deprecation and protection
updates.

Speculative Execution – As mentioned above, partially automating the debugging
process can greatly assist the user. To do this, a piece of the debugger should be able
to take a set of valid inputs and outputs for the user’s program in addition to a set of
“rules”. This should allow the debugger to identify, at a gross level, whether or not the
program is faulty. For instance, Blizzard allows a user to track his/her quest progress
on the screen. If a user created interface wants to enable a player to automatically track
this progress, the user would specify a Boolean input, a display frame output, and the
OnLoad event in its “rule set”. The debugger would look at these and assert that if the
Boolean is true and an OnLoad event is fired, the display is shown. When the Boolean
is false, and the event is fired, the display should not be shown. If any event other than
the OnLoad event causes a change in this display, then there is an error. There is also
an error if the Boolean does not contain the correct value for automatic display.
For this to be accomplished there must be a way to express what the program is
supposed to do. This is defined in the “rule set”. For the above example, the user
would create a rule that specifies the OnLoad event causes the ToggleVisibility
function. By checking if the frame is visible, the debugger can attest to the validity of
the function. Control statements and loops are specific areas of code that should
receive attention. The debugger should check that variables are not NULL before the
user attempts to perform actions based on those variables. There must be checks across
the code to assert that loop expressions are advancing toward failure.
-4-
Samuel Savage
April 14, 2008
Susan Conry
In addition, there should be analysis routines to detect faulty syntax. Upon detection of
faulty syntax, the program should prompt the user for permission to auto-correct. The
user could also insist that the program automatically correct all similar mistakes. For
instance, if the user wants the program to automatically correct for misspelled switch
statements, and do so for all related errors, the program would also correct other
misspelled keywords. This auto-correction routine would be based on an internal
representation of the grammar of the language.
Example Scripts
A typical add-on usually consists of three files: the table of contents (TOC) file, the Lua
script file, and the XML script file. The TOC file is required for every add-on. It is what
World of Warcraft uses to know that a user-defined add-on exists. In this file, there should
be the game version for which the add-on is intended and the name of the files that define
the add-on. Figure 1 shows the TOC file for an example add-on, testScript.
Figure 1 – The Table of Contents file for my add-on.
In this file, we see that testScript.lua defines the execution code of our add-on (Figure 3)
and testScript.xml defines the way our add-on should be displayed (Figure 2). The first
block of the XML file consists of URL’s to find documentation for the XML language and
the Blizzard API. The next line links this XML file to its Lua script. The meat of this file
is found in the frame. All add-ons must have a frame. This is the entity in the add-on to
which the Lua script is tied. In order for an add-on to execute code, it needs a “parent”
frame. In this example, the frame is hidden, that is, it cannot be seen by the user, but exists
only to allow two functions to be executed: the OnLOad function and the OnEvent
function. The OnLoad function is called when this add-on is loaded. The add-on will be
automatically loaded when a user logs into the game world (assuming the TOC file is
written correctly). The OnEvent function is called whenever an event is fired in the game.
-5-
Samuel Savage
April 14, 2008
Susan Conry
Figure 2 – The XML file for my add-on.
Figure 3 – The Lua file for my add-on.
The Lua file is the workhorse of this add-on. This is what defines what the add-on should
do. At the top, there is a structure that should be saved between sessions (as specified by
the TOC file). Any number of variables can be placed inside this structure. Here, there is
only one: a Boolean specifying whether a chat message should be printed. When the
OnLoad function is called, the user is told if he/she will be notified of chat messages.
Here, it is also specified that we only want the CHAT_MSG event to be sent to our frame.
Each time this event is fired, the OnEvent function is called and a message is printed to the
chat box. This message can be given a color code in the form alpha red green blue, with
two hexadecimal numbers for each value.
-6-
Samuel Savage
April 14, 2008
Susan Conry
The debugger should be able to take the XML file and display its respective frame(s). It
should then allow the user to fire events into the Lua file. Ideally, it would update a central
screen as events are fired and write out success/error messages to a debug pane (as shown
in Figure 4). In the case of the above example scripts, no frame would be displayed in the
main window (but a chat box and other default elements would be). When the user fires
the CHAT_MSG event, the message would be displayed in the chat box. Any other events
fired should not affect the main window.
In another window the user should be able to define the “rules” for his/her code. These
“rules” would trigger print outs of success and errors based on the overall design. The
system would also display pop up windows during the coding of the add-on to alert the
user when auto-correction routines have been run (if enabled).
Figure 4 – Example debugger GUI.
Limitations and Extendibility
The changes the program makes in a user's source file might be difficult to track. In
Microsoft Visual Studio, the file can be changed outside of the VS environment, and then
VS will "refresh" to reflect the newly changed document. I don't know if Open Source
programs support the same convenience. It might be that this program will only work on
Windows and only work with MS Visual Studio. It might also be the case that the user
must close and reopen his/her document when debugging takes place. I would prefer the
former to the latter, as it would be more convenient, but part of this investigation involves
exploration of what is possible.
-7-
Samuel Savage
April 14, 2008
Susan Conry
The proposed World of Warcraft API that is envisioned reflects a specific implementation
of general ideas discussed in this proposal. Remembering variables and functions, autocorrection routines, and incorporation of an easily updated database are features that can be
extended to other languages. HTML, for example, is a scripting language that appears to
be quite similar to Lua, making this project easily extensible. Languages such as C++ and
Java do not appear as similar to Lua or XML. Because of that, areas of this project would
probably not extend to these languages. For instance, because C++ and Java have typed
variables, the debugger would not need to remember variable names and types. A symbol
table is automatically created by the compiler for these languages. Elements like autocorrection and error handling would be more important for these languages. The type of
target language would affect the elements of this project to maintain and extend.
Timeline
Spring 2008
► Write Proposal
► Become familiar with Lua and XML
► Become familiar with language processing and error handling
 Benchmark: Successful Proposal
Summer 2008
► Acquire data structure for variable and function names/types
► Code for debugger GUI
► Code for event firing
 Benchmark: Able to render scripts and fire events
Fall 2008
► Code heuristics for error handling
► Code for updating
 Benchmark: Able to automate corrections
Spring 2009
► Finalize debugger
► Add aesthetic enhancements
► Complete and defend thesis
 Benchmark: Completed thesis
References
[1]
Sussman, G.A. (1973) A Computational Model of Skill Acquisition. MIT AI
Laboratory, Memo AI-TR-297.
[2]
Blizzard Entertainment, Inc. World of Warcraft® Reaches New Milestone: 10
Million Sbuscribers. January 22, 2008. <http://blizzard.com/us/press/080122.html>
(March 14, 2008)
[3]
R. Ierusalimschy, L. H. de Figueiredo, W. Celes. Lua 5.1 Reference Manual.
January 19, 2008. <http://www.lua.org/manual/5.1/> (March 14, 2008)
[4]
Lua. About. March 7, 2008. <http://www.lua.org/about.html> (March 14, 2008)
-8-
Samuel Savage
[5]
[6]
April 14, 2008
Susan Conry
W3Schools. XML Tutorial. <http://www.w3schools.com/xml/default.asp> (March
14, 2008)
W3Schools. Introduction to XML.
<http://www.w3schools.com/xml/xml_whatis.asp> (March 14, 2008)
-9-