Oolite JavaScript Reference: Global

The Global environment includes all Oolite objects and methods accessible by all scripts at all times.

Properties

clock

clock : Clock (read-only)

This property allows an OXP to access the game clock's properties and methods.

galaxyNumber

galaxyNumber : Number(read-only)

Returns the number ot the galaxy the player is in.

guiScreen

guiScreen : String(read-only)

Returns the screen the player is looking at. If in flight, it's set to "GUI_SCREEN_MAIN".

manifest

manifest : Object(read-only)

This property allows an OXP to directly access the player ship's manifest properties.

mission

mission : Object(read-only)

This property allows an OXP to access misson methods.

missionVariables

missionVariables : Object(read-only)

The missionVariables object stores values that are stored in saved games. This is the main way for scripts to store information permanently.

Whenever a value is assigned to a property of missionVariables, it is converted to a string object and tracked with the player. When the value is read, it will be converted to a number if possible, otherwise returned as a string. Example:

missionVariables.exampleVar = 42;
let x = missionVariables.exampleVar; // x is now the number 42

Mission variables can also be used in legacy scripts and in descriptions.plist string expansions, by prefixing the name with “mission_”. Example:

expandDescription("My variable is [mission_exampleVar].")

Setting and retrieving mission variables has a small but non-trivial overhead. If a function needs to use a mission variable value several times, it is strongly recommended that it be copied into a local variable and, if necessary, stored back once. Example:

let x = missionVariables.exampleVar;
if (x < 3)  x = processSmallValue(x);
else  x = processBigValue(x);
missionVariables.exampleVar = x;

Mission variable names may not begin with an underscore (“_”). Unassigned mission variables are always null.

oolite

oolite : Object(read-only)

This property allows an OXP to access oolite's properties and methods.

player

player : Object(read-only)

This property allows an OXP to access the player object's properties and methods.

system

system : Object(read-only)

This property allows an OXP to access the current system's properties and methods.

timeAccelerationFactor

timeAccelerationFactor : Number(read/write)

Also known as TAF. Will change the ratio between game real time and actual real time (default is 1). The accepted range is between 0.0625 (1/16) and 16. Attempting to set numbers outside this range will reset the TAF to 1.

worldScripts

worldScripts : Object(read-only)

This property allows an OXP to access all world scripts, their properties and functions.

Example:

log(worldScripts['oolite-nova'].version);

Methods

addFrameCallback

function addFrameCallback(callback : Function) : TrackingID

Registers a frame callback which will be invoked every frame, after entity updates but before rendering. This can be used to implement animations. The return value is a tracking ID which may be passed to removeFrameCallback(); the type and meaning of the tracking ID is unspecified and may change at any time. Frame callbacks are automatically removed when the game resets (for instance, when the player dies), but not at any other time.

The callback is passed one parameter, delta, which is the time since the last frame (in game clock time). Frame callbacks fire even when the game is paused, in which case delta is 0.

Example:

var sum = 0;
this.fcb = addFrameCallback(function (delta)
{
    sum += delta;
    log("Time elapsed: " + sum + " (delta: " + delta + ")");
}

See also: removeFrameCallback(), isValidFrameCallback()

displayNameForCommodity

function displayNameForCommodity(commodityName : String) 

Returns the display name corresponding to the specified commodity. Useful in conjunction with localisation OXPs, or expansions that rename commodities depending on which station / system the player is at.

expandDescription

function expandDescription(description : String [, locals : Object (Dictionary)]) : String

Expands a string, substituting special tokens and any key inside square brackets with the substitution rules for Communications. When local key/value pairs are provided, they take precedence over any other values. (buggy at the time of writing, fixed for 1.74.2 and later versions.)

Example:

expandDescription('My ball is [my_color].', { 'my_color': 'red' }); 

expandMissionText

function expandMissionText(textKey: String [, locals : Object (Dictionary)]) : String

Load a string specified by textKey from missiontext.plist, then perform expandDescription()-type substitutions on it, and also replace “\n” with line breaks. The local parameter works as with expandDescription().

Example:

expandMissionText('oolite_trumble_title');

isValidFrameCallback

function isValidFrameCallback(trackingID: TrackingID) : boolean

Returns true if trackingID identifies a frame callback which has been registered with addFrameCallback() and not yet removed.

See also: addFrameCallback(), removeFrameCallback()

log

function log([messageClass : String ,] message : String)

Writes a message to Oolite's log. The optional messageClass can be used to specify which type of message is written to the log.

Example:

log('myOXP.init','MyOXP initialised and ready!');

randomInhabitantsDescription

function randomInhabitantsDescription([plural : boolean])

Returns a random capitalised word, suitable to describe one sentient being, or - if using the optional plural argument - a group of sentients.

Example:

player.consoleMessage("You'll meet a " +  randomInhabitantsDescription() +
                     ". She'll be with a group of " + randomInhabitantsDescription(true) +'.');

randomName

function randomName()

Returns a random capitalised word, suitable for use as name, or indeed surname.

Example:

player.consoleMessage(randomName() + ' ' + randomName() +' rules this system with an iron fist.');

removeFrameCallback

function removeFrameCallback(trackingID : TrackingID)

Removes a frame callback previously registered with addFrameCallback().

See also: addFrameCallback(), isValidFrameCallback()

setScreenBackground

function setScreenBackground(image : guiTextureSpecifier) 

Temporary override that sets the background of the current gui screen to the specified image. Override is lost after the player switches screens.

In Oolite 1.75 and later, guiTextureSpecifier can be either a string or an object with the required key name and optional keys width and height. If neither width nor height is specified, the dimensions of the image are used. If only one is specified, the other is calculated such that the image is not distorted. The scale unit is 1/480 of the height of the window; in other words, the window is always considered 480 units high, and the width depends on the aspect ratio of the window.

In earlier test releases, only a string is accepted and the width and height are always those of the texture after loading.

Example:

setScreenBackground({ name: "oolite-nova-system.png", height: 512 });

setScreenOverlay

function setScreenOverlay(image : guiTextureSpecifier) 

Temporary override that sets the overlay of the current gui screen to the specified image. Override is lost after the player switches screens.

See setScreenBackground() for a discussion of guiTextureSpecifier.

Example:

setScreenOverlay('trumblebox.png');

takeSnapShot

function takeSnapShot([filename : String]) : Bool

Saves a snapshot of the current screen to your hard disk. A filename is optional. When a name is used, only alphanumeric values and "-" and "_" are allowed for the filename. The appropriate extension for the used operating system (like .png) is added by Oolite and should not be part of the filename.
When a filename already exists, it is not overwritten but the string "-xxx" is added, starting with "-001".
takeSnapShot() will not be available in the stable release version of Oolite, but will be available in a special OXP developer release.

Example:

takeSnapShot('mission_target_1');