Oolite JavaScript Reference: Global

Global variables and functions are visible to all scripts. They are also properties of global, which is itself a global variable and hence a property of itself.

Properties

clock

clock : Clock (read-only)

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

defaultFont

defaultFont : Object (read-only)

An object with a single method, measureString(string), which returns the width of the specified string, as it would be shown on the screen, in ems. One em is the intrinsic unit size of a font; for example, if a font is rendered at 12 points, 1 em = 12 pt. The mission screen text area is 32 em wide.

galaxyNumber

galaxyNumber : Number (read-only)

Returns the number of the galaxy the player is in.

See also: galaxyID

global

global : Global (read-only)

All global variables and functions are actually properties of the global object. The global object is a property of itself, and this is it.

guiScreen

guiScreen : String (read-only)

Returns the screen the player is looking at. If in flight, this is "GUI_SCREEN_MAIN". In 1.76, the other possible values are "GUI_SCREEN_INTRO1", "GUI_SCREEN_INTRO2", "GUI_SCREEN_STATUS"(F5), "GUI_SCREEN_MANIFEST"(F5F5), "GUI_SCREEN_EQUIP_SHIP"(F3), "GUI_SCREEN_SHIPYARD"(F3F3), "GUI_SCREEN_LONG_RANGE_CHART"(F6F6), "GUI_SCREEN_SHORT_RANGE_CHART"(F6), "GUI_SCREEN_SYSTEM_DATA"(F7), "GUI_SCREEN_MARKET"(F8), "GUI_SCREEN_CONTRACTS", "GUI_SCREEN_OPTIONS", "GUI_SCREEN_GAMEOPTIONS", "GUI_SCREEN_LOAD", "GUI_SCREEN_SAVE", "GUI_SCREEN_SAVE_OVERWRITE", "GUI_SCREEN_STICKMAPPER", "GUI_SCREEN_MISSION" and "GUI_SCREEN_REPORT".

In 1.77, "GUI_SCREEN_INTERFACES"(F4) is added, and "GUI_SCREEN_CONTRACTS" is removed.

In 1.81, "GUI_SCREEN_MARKETINFO"(F8F8) is added.

manifest

manifest : Manifest (read-only)

An alias to player.ship.manifest.

mission

mission : Mission (read-only)

See Oolite JavaScript Reference: Mission.

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

Do not use false in missionVariables! It will return true because it will be parsed as a string. Use 0 or 1 to store boolean values.

You can store arrays using JSON stringify and parse methods. For example:

this.$MyArray = [];

this.startUp = function() {
       var s = missionVariables.$MyArray;
       if( s && s.length > 0 ) this.$MyArray = JSON.parse(s);
}

this.playerWillSaveGame = function(message) {
       missionVariables.$MyArray = JSON.stringify(this.$MyArray);
}

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 significant 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.

* On a computer where the loop for (var i = 0; i < 1000; i++) {} takes just 0.62 msec, the same loop with missionVarriables for (missionVariables.i = 0; missionVariables.i < 1000; missionVariables.i++) {} consumes a full 38 msec. That is 60 times longer.

oolite

oolite : Oolite (read-only)

An object describing properties of the Oolite application; see Oolite JavaScript Reference: Oolite.

player

player : Player (read-only)

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

system

system : System (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. (In end-user stable builds, this will be a read-only property with the value 1.)

worldScriptNames

worldScriptNames : Array of strings (read-only)

A list of the names of world script objects, the keys of worldScripts.

worldScripts

worldScripts : Object (read-only)

All loaded world script objects. The keys are the name properties of the scripts.

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, to apply gradual changes in ship state, to build large data structures without risking reaching processing time limits by trying to do it all at once, or to watch variables which need a same-frame response to changes. 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(), and for repeated events with a longer repeat interval, use Timers instead.

See RFC: frame callbacks (2011)

clearExtraGuiScreenKeys

This method was added in Oolite test release 1.91.

function clearExtraGuiScreenKeys(guiScreen: string, key : string)

Clears additional keys that have been defined for use on a particular gui screen with setExtraGuiScreenKeys().

guiScreen is the gui screen that will have it's additional keys cleared. Valid possibilities are: GUI_SCREEN_OPTIONS, GUI_SCREEN_EQUIP_SHIP, GUI_SCREEN_SHIPYARD, GUI_SCREEN_INTERFACES, GUI_SCREEN_STATUS, GUI_SCREEN_MANIFEST, GUI_SCREEN_SHORT_RANGE_CHART, GUI_SCREEN_LONG_RANGE_CHART, GUI_SCREEN_SYSTEM_DATA, GUI_SCREEN_MARKET and GUI_SCREEN_MARKETINFO.
key is the key used to register the keys originally, usually "this.name"

Example

clearExtraGuiScreenKeys("GUI_SCREEN_MANIFEST", this.name);

See also: setExtraGuiScreenKeys()

displayNameForCommodity

function displayNameForCommodity(commodityName : String) : String

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

Note See discussion at https://bb.oolite.space/viewtopic.php?f=3&t=12242 (2012)

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 string expansions. When local key/value pairs are provided, they take precedence over any other values.

In Oolite 1.79 or later, this method uses a higher quality random number generator which does not have noticeable correlation problems when used for recursive expansion.

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().

In Oolite 1.79 or later, this method uses a higher quality random number generator which does not have noticeable correlation problems when used for recursive expansion.

Example:

expandMissionText("oolite_trumble_title");

formatCredits

function formatCredits(value : number, [includeDeciCredits : boolean, [includeCurrencySymbol : boolean]]) : String

Converts the value parameter to a string formatted in a currency friendly manner. If includeDeciCredits is true the string will be formatted to 1 decimal place. If includeCurrencySymbol is true an appropriate currency symbol following any localisation rules is included. The default currency symbol is a terminal ₢.

formatInteger

function formatInteger(value : number) : String

Converts the value parameter to a string formatted as an integer following any localisation rules in place.

getGuiColorSettingForKey

This method was added in Oolite test release 1.87.

function getGuiColorSettingForKey(keyname : string) : Array

Returns the current color for a particular keyname (referenced in the gui-settings.plist file). Returns an array of RGBA values.

See also: setGuiColorSettingForKey()

getScreenBackgroundForKey

This method was added in Oolite test release 1.85.

function getScreenBackgroundForKey(keyname : string) : guiTextureSpecifier

Returns the guiTextureSpecifier for a particular keyname (referenced in the screenbackgrounds.plist file).

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.

Example:

getScreenBackgroundForKey("long_range_chart_mission");

See also: setScreenBackgroundForKey()

isValidFrameCallback

function isValidFrameCallback(trackingID: TrackingID) : Boolean

Returns true if trackingID identifies a frame callback which has been registered with addFrameCallback() and not yet removed. (There should be no need to use this except for debugging and testing.)

See also: addFrameCallback(), removeFrameCallback()

log

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

Writes a message to Oolite's log. The optional messageClass parameter can be used to specify which type of message is written to the log. The default messageClass is script.debug.message. When set to true, the messages will be written to the log file. The classes to be logged are set in the file logcontrol.plist. messageClasses not listed in logcontrol.plist are always logged.

Example:

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

You can temporarily enable/disable logging the above message by typing in the console:

console.setDisplayMessagesInClass("myOXP.init", true/false)

pauseGame

function pauseGame() : Boolean

Pauses the game. It does not work on screens that cannot be paused by keyboard: mission screens, long range chart, arrival report, save menu. In those cases, the method returns false. Otherwise, it pauses the game and returns true.

This was added in v1.87 (the exact version is unconfirmed)

See also: Scriptable pause?

randomInhabitantsDescription

function randomInhabitantsDescription([plural : boolean, default true]) : String

Returns a random sentient species name, like "Large Red Fat Insects" or "Human Colonials", following the same pattern (and probability distribution) as for planet inhabitants.

Example:

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

randomName

function randomName() : String

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()

setExtraGuiScreenKeys

This method was added in Oolite test release 1.91.

function setExtraGuiScreenKeys(key : string, options : dictionary)

Allows additional keys to be defined for use on a particular gui screen.

"key" is a unique identifier, usually set as the script name.
"options" is a dictionary with the following properties:

• guiScreen (string): the gui screen to which the extra keys will be attached. Valid possibilities are: GUI_SCREEN_OPTIONS, GUI_SCREEN_EQUIP_SHIP, GUI_SCREEN_SHIPYARD, GUI_SCREEN_INTERFACES, GUI_SCREEN_STATUS, GUI_SCREEN_MANIFEST, GUI_SCREEN_SHORT_RANGE_CHART, GUI_SCREEN_LONG_RANGE_CHART, GUI_SCREEN_SYSTEM_DATA, GUI_SCREEN_MARKET and GUI_SCREEN_MARKETINFO
• registerKeys (dictionary): the key definitions to be registered. For example: options["registerKeys"]["myKey"] = [{key:"h",mod1:true}]; would register the Ctrl+h key, linking it to "myKey" as an ID.
• callback (function): the function to call when the use presses one of the registered keys. The ID defined in the registerKeys properties will be passed to the function as a parameter.

Example

setExtraGuiScreenKeys(this.name,
  {
    guiScreen:"GUI_SCREEN_MANIFEST",
    registerKeys:{"key1":[{key:"g",mod1:true}],
    callback:this.$myGuiScreenCallback.bind(this)
  }
);

This code registers the Ctrl+g keypress on the F5F5 Manifest screen. The function callback, $myGuiScreenCallback will be passed "key1" as a property when the Ctrl+g is pressed on that screen.

See also: clearExtraGuiScreenKeys()

setGuiColorSettingForKey

This method was added in Oolite test release 1.87.

function setGuiColorSettingorKey(keyname : string , Colour specifier : string) 

Override the color setting for a particular keyname (referenced in the gui-settings.plist file) with the specified color. This override is only for the current play-session and does not get written to gui-settings.plist.

Example:

setGuiColorSettingForKey("screen_title_color", "whiteColor");

See also: getGuiColorSettingForKey()

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.

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.

Example:

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

See also: #setScreenOverlay & Screenbackgrounds.plist

setScreenBackgroundForKey

This method was added in Oolite test release 1.85.

function setScreenBackgroundForKey(keyname : string, image : guiTextureSpecifier) 

Override the background for a particular keyname (referenced in the screenbackgrounds.plist file) with the specified image. Override is only for the current play-session only and does not get written out to screenbackgrounds.plist.

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.

Example:

setScreenBackgroundForKey("long_range_chart_mission", { name: "my_mission_background.png", height: 480 });

See also: getScreenBackgroundForKey()

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

See also: Screenbackgrounds.plist

takeSnapShot

function takeSnapShot([filename : String]) : Boolean

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

Reserved Words

Quaternion

Oolite_JavaScript_Reference:_Quaternion

Vector3D

Oolite_JavaScript_Reference:_Vector3D