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. (e.g. no spaces or periods are allowed to let is work on any OS). 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".

Example:

takeSnapShot('mission_target_1');