Oolite JavaScript Reference: Script

Prototype: Object
Subtypes: none

The Script class represents a JavaScript script. There are several categories of scripts: ship scripts which are attached to individual ships/in-game entities and world scripts which are effectively attached to the player. There are also Condition scripts, Equipment scripts, Market Scripts and Visual Effects Scripts.

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.

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 another 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._escortPerformSpecialManoeuvre = function (target)
{
    // Do something very clever here
}

which the mothership might do as follows:

// Warning: untested code
this._makeEscortsPerformSpecialManoeuvre = function (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:

this._makeEscortsPerformSpecialManoeuvre = function (target)
{
    // 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);
}

Script objects do 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. Note that properties not intended to be event handlers should have names starting with an '_' or '$' character, so that future additions of Oolite event handlers do not cause a conflict.

Predefined properties

ship

ship : Ship (read-only)

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

Note ship refers to the Ship object that “owns” the script, which might not be a ship from a player perspective; it may be a station, missile, asteroid etc.

Common properties

These are properties scripts can set on themselves which have a standard meaning. In Oolite 1.79 and later, the author, license and version properties will be set automatically from the manifest.plist file if one is available, and so do not need to be included in the script file itself.

author

author : String

Who wrote the script. This property is currently not checked by any Oolite core functionality.

copyright

copyright : String

A copyright statement for the script. This property is currently not checked by any Oolite core functionality.

description

description : String

A short description of the script. This property is currently not checked by any Oolite core functionality.

license

license : String

A statement of the license for the script. This property is currently not checked by any Oolite core functionality.

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.

Starting in Oolite 1.75, any underscores (“_”) or spaces will be removed from the beginning and end of the name property.

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. It is recommended to have this value equal the version of the OXP containing the script.