Introduction

A large part of the game like components, GUI scripts or the AI are written in Javascript. If you have programmed C++ or used Javascript for websites you probably know how important a good debugger can be and how much it helps to find bugs or learn how a part of code works. The web based Tools like Firebug can't be used for 0 A.D. because the debugger has to be very closely connected to the Javascript runtime. However, there's a dedicated tool for 0 A.D. and the Pyrogenesis engine being developed at the moment that should hopefully be ready to use soon.

Technical background

The DebuggingServer component makes debugging commands like (ToggleBreakpoint, Step, Continue etc...) available using a mongoose webserver. The format used for return values is JSON, which should be easy to parse from a Web-GUI. The Debugger uses the JSDBGAPI provided by Spidermonkey 1.8.5. Newer versions of Spidermonkey provide a simplified new API (along with memory leak fixes, performance improvements and more), but unfortunately Mozilla isn't interested in doing the work and publishing a independent build from Firefox at the moment. We had a ​discussion about that on IRC.

The JSDBGAPI isn't thread-safe and also our current implementation of ScriptInterfaces (which are basically abstractions of Spidermonkey) isn't thread-safe either. As a general rule, all Javascript objects are tied to one ScriptInterface which represents one Javascript runtime and one Javascript context and can only be used in one thread. We do use multiple threads, but each of them only uses one ScriptInterface. One major difficulty about implementing a debugger is not to violate these constraints.

The idea is that there's one CThreadDebugger class which is responsible for tracking hooks, callbacks, breakpoints and general state information for each of those ScriptInterfaces. The class CDebuggingServer manages multiple threads using multiple objects of CThreadDebugger. It passes commands from the mongoose webserver (triggered by the user) to the CThreadDebugger objects and retrieves state information from these objects and returns it to the user as JSON. The DebuggingServer makes sure not to access any Spidermonkey functions or Javascript objects directly (because they belong to the ScriptInterface's thread). The DebuggingServer itself should also be thread-safe to accept multiple request asynchronously.

Available commands

This section lists all currently implemented commands and gives some examples of data they return.

Toggling (setting/removing) breakpoints:

http://127.0.0.1:9000/ToggleBreakpoint?filename=gui/gamesetup/gamesetup.js&line=1502

Returns: Nothing

Get the status of all threads

http://127.0.0.1:9000/GetThreadDebuggerStatus

Returns:

{ "ThreadDebuggerID" : 1,"ScriptInterfaceName" : "GUI","ThreadInBreak" : true,"BreakFileName" : "gui/gamesetup/gamesetup.js","BreakLine" : 1502 }

Note: BreakFileName and BreakLine should be considered "undefined" if ThreadInBreak is false!

Continue

Continue the execution until the next breakpoint is hit.

http://127.0.0.1:9000/Continue?threadDebuggerID=1

Arguments:

• threadDebuggerID: The ThreadDebuggerID of the thread that should be continued. You can get this ID by calling GetThreadDebuggerStatus.

Returns: Nothing

Note: The command has no effect if the thread is not stopped.

Step

Step the execution. Honestly I'm not sure what it exactly does at the moment. After calling it a few times it steps to the next line. Probably it executes each assignment/operation separately. I will figure it out and improve it for a next patch.

http://127.0.0.1:9000/Step?threadDebuggerID=1

Arguments:

• threadDebuggerID: The ThreadDebuggerID of the thread that should be stepped. You can get this ID by calling GetThreadDebuggerStatus.

Returns: Nothing

Getting Callstacks

Returns the callstacks of all threads that are in break mode.

http://127.0.0.1:9000/GetAllCallstacks

Returns:

{ "CallStacks" : [{"ThreadDebuggerID" : 1, "CallStack" : ["keywordTestOR","annonymous","testFilter","initMapNameList","selectMapType","__eventhandler31 (selectionchange)","initMain","onTick","__eventhandler28 (tick)"]}] }

keywordTestOR is the innermost function which got called by an annonymous function, which got called by "testFilter" etc... You also get the ThreadDebuggerID to know which thread is meant.

Getting a stack frame

Returns all variables and their content of the specified thread and nesting level.

http://127.0.0.1:9000/GetStackFrame?nestingLevel=0&threadDebuggerID=1

Returns:

... need to find a shorter example ...

Arguments:

• nestingLevel If you look at the function above (GetCallstack), nestingLevel=0 would point to the innermost stackframe (keywordTestOR). Native functions as "eventhandler31" don't return any data.
• threadDebuggerID The thread you want to get the a stack frame from.

Getting a list of .js files

Returns all full Vfs paths ending with *.js loaded into the Vfs.

http://127.0.0.1:9000/EnumVfsJSFiles

Returns (shortened)

["globalscripts/Math.js","globalscripts/Technologies.js","hwdetect/hwdetect.js","hwdetect/test.js","gui/aiconfig/aiconfig.js","gui/civinfo/civinfo.js"] 

Getting a file

Returns a whole file without any formatting (no JSON).

http://127.0.0.1:9000/GetFile?filename=globalscripts/Math.js

Returns: A file as plaintext.

Arguments:

• filename A full Vfs path to a file