Debug OXP

Debug.oxp is a special OXP that enables JavaScript console support in test releases of Oolite (1.70 and later). It also adds a menu with various debug facilities under Mac OS X.

Download (109 KiB)

External JavaScript console support

On all platforms, installing Debug.oxp enables support for external console applications using the Oolite debug console TCP protocol. By default, it will attempt to connect to a console running on the same computer, but this can be changed by specifying a different console-host (and, optionally, console-port) in debugConfig.plist. For external console support on the same computer under Mac OS X, console-host must be explicitly set to “127.0.0.1”; if this is not done, the integrated JavaScript console will be used instead. For information on using a console (integrated or external), see Using the JavaScript console below.

Note: no external console application is available at this time. Support is included in Oolite 1.70 as an incentive for third parties to develop one.

Mac OS X-specific features

Under Mac OS X, the Debug OXP provides a menu with various debugging options and an integrated JavaScript console, as well as enabling external console support as on all platforms.

Debug menu

The Debug menu provides options to

• Show the Oolite run log in the standard Console application.
• Enable or disable various classes of log message at runtime (like editing logcontrol.plist, without the need to restart Oolite).
• Enable various testing features, such as drawing of bounding boxes.
• Show the JavaScript console, and specify when it should be shown automatically. (This may not have any effect with external consoles, depending on the external console implementation.)
• Create a ship of any role near the main station (equivalent to the :spawn macro.

Note: some of these features are implemented by sending JavaScript messages to the console script. If the script has been modified, some features may not work properly.

The Log Message Classes submenu can be modified by editing debugLogMessageClassesMenu.plist, found inside the OXP. This is merged from Config directories in the usual fashion.

Integrated JavaScript console

The integrated JavaScript console provides a window within Oolite which acts as a JavaScript console. It can be shown using the Show JavaScript Console command in the Debug menu, unless external console mode has been enabled by setting console-host in debugConfig.plist.

Using the JavaScript console

The JavaScript console, whether integrated or external, provides a powerful mechanism for interactively manipulating the game world. It can be used to issue simple commands, like player.awardEquipment("EQ_FUEL_INJECTION"). It can be used to inspect properties of entities in the game world. And it can be used to develop scripts, by rewriting and testing methods of live ship scripts and world scripts.

Macros

Macros are a special type of command prefixed with a colon. Instead of being interpreted as a JavaScript command, a macro is looked up in a dictionary, and the result is used as the “real” command. For instance, if you enter the command :listM (short for “list macros”), the macro dictionary is queried for the string “listM”, and (by default) the code for (let prop in macros) { ConsoleMessage('macro-list', ':' + prop) } is found and executed. This code is called the expansion of the macro. The result is a list of macros being printed:

:clr
:clear
:spawn
:bgColor
:showM
:rmFgColor
::
:d
:ds
:listM
:setM
:delM
:fgColor
:rmBgColor
:resetM

As you can see in the example, To see the expansion of a macro without executing it, use :showM:

> :showM :delM
:delM = deleteMacro(PARAM)

When a macro with the word PARAM is executed, PARAM is replaced with any text following the macro name, surrounded in quotation marks. This is how :showM functions, for example; the string “:showM :delM” is expanded to “showMacro(":delM")”, causing the JavaScript function showMacro(), which is part of the console script, to be called. You can see the implementation of showMacro() by entering showMacro – without any parentheses – into the console.

An initial set of macros is loaded from debugConfig.plist. If you edit any macros, using :setM or :delM, all macros are saved in Oolite’s preferences from that point forwards. This means that you don’t have to re-enter any macros you write with :setM after restarting Oolite.

The console script

(under construction)