Oolite JavaScript Reference: Global

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

Properties

clock

clock : Object(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

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

Returns an expanded mission text, substituting any tokens and keys inside square brackets inside the original missiontext.plist value with its corresponding expanded string. If 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:

expandMissionText('oolite_trumble_title'); 

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.');  

setScreenBackground

function setScreenBackground(image : String) 

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

Example:

setScreenBackground('oolite-nova-system.png');

setScreenOverlay

function setScreenOverlay(image : String) 

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

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');