Oolite JavaScript Reference: Script

Prototype: Object
Subtypes: none

The Script class represents a JavaScript script. There are currently two categories of script: ship scripts, which are attached to individual ships, and world scripts, which are effectively attached to the player.

Scripting overview

World scripts are run once at game start-up, at which point they may create event handlers. Event handlers are functions with predefined names which are called by the game at specific points. Ship scripts are run when their ship is loaded, and can also create event handlers. An event handler is specified as a property of the Script object itself. For example, to set up an event handler for the willDock event, a script would typically look like this:

this.willDock = function()
{
    // Do stuff when about to dock
    Log("Woo, I’m about to dock!");
}

This assigns an anonymous function with no arguments to the Script object’s willDock property. Another way to achieve the same thing would be:

function willDockEventHandler()
{
    // Do stuff when about to dock
    Log("Woo, I’m about to dock!");
}
this.willDock = willDockEventHandler;

This form has the advantage that it’s easy to remove and re-add the event handler. (Event handlers may be added or removed at any time.)

delete this.willDock;  // stop handling willDock events
this.willDock = willDockEventHandler;  // start handling willDock events again

A property of the Script object which is a function is called a method. The most common use for methods is for event handlers, but a script may assign itself arbitrary methods, and any script may call the methods of anothe Script object. For instance, consider the case of a ship which needs to interact with its escorts in an unusual way. The script for the escorts may define a method such as:

this.escortPerformSpecialManoeuvret(target)
{
    // Do something very clever here
}

which the mothership might do as follows:

// Warning: untested code
function makeEscortsPerformSpecialManoeuvre(target)
{
    this.ship.escorts.forEach(function(escort){escort.script.escortPerformSpecialManoeuvre(this.target)}, this);
}

I can hear the cries of “huh” now, so let’s expand on that a little:

function makeEscortsPerformSpecialManoeuvre()
{
    // The function we want to call for each element of the escorts array.
    function callEscortMethod(escort)
    {
        escort.script.escortPerformSpecialManoeuvre(this.target);
    }
    
    // Get the list of escorts from our ship.
    var escorts = this.ship.escorts;
    
    // For each element in the list, call callEscortMethod().
    escorts.forEach(callEscortMethod, this);
}

Note: it is a good idea to use reasonably unique names for methods. If your ship script implements a doStuff method, and some other ship script implements a doStuff method that does something completely different, one may be called when the other was intended.

Script objects to not have many predefined properties. Instead, the script can set whatever properties it needs. Which properties are used by the game depends on the context in which the script is being used.

Predefined properties

ship

ship : Ship (read-only)

For ship scripts, the ship to which the script is attached. Undefined for world scripts.

N.B. ship refers to the entity that 'owns' the script, which might not be an actual ship. If a specific script is a property of an asteroid as opposed to a ship, this.ship will refer to the asteroid, etc...

Common properties

These are properties scripts can set on themselves which have a standard meaning.

author

author : String

Who wrote the script. Currently unused.

copyright

copyright : String

A copyright statement for the script. Currently unused.

description

description : String

A short description of the script. Currently unused.

name

name : String

The name of the script. World scripts must have a unique name. It’s a good habit to set a name for all scripts. If no name is set when the script is first run, Oolite will make one up. While it is possible to set the name property at any time, the value used after the script is first run is the one Oolite will continue to use.

version

version : String

A string specifying the version of the script. This is used, together with name, for identification in log messages and similar. While it is possible to set the version property at any time, the value used after the script is first run is the one Oolite will continue to use.