Variables in Oolite JavaScripts

JavaScript worldScripts and shipScripts can declare and manipulate variables of several types. This page gives a brief overview of how to work with variables and how to avoid common pitfalls.

Local and Global variables

Variables in JavaScript can be of local or global scope. Global scope variables should generally be avoided in Oolite scripts as they are accessible to all loaded scripts, and are likely to create conflicts between OXPs.

myVariable = x;

will create a global variable and should be avoided.

this.myVariable = x;

will limit the scope of the variable to the current (this) script and is the recommended method. However, this may end up in conflict with a future world/ship script event, so

this.$myVariable = x;

or

this._myVariable = x;

is preferred as there will never be a world or ship script event with a name starting '_' or '$'.

var myVariable = x;

can be used safely within a function to declare a variable that has a local scope to that function only. 'var' should not be used to declare a variable outside of a function as the resulting variable will have a global scope. There is no need to prefix function-scoped variables with '_' or '$'.

Mission Variables

Mission variables should be used when it is important that the contents be stored between sessions in the player's save game, or if the contents need to be displayed on a mission screen (see Missiontext.plist). It is essential that mission variables are given a unique name that will not be used by another OXP to avoid conflicts between OXPs. Using the OXP's name as a common prefix for an OXP's mission variables is the recommended method to create a unique mission variable name. For example

missionVariables.myoxpname_myFirstMissionVariable = x;

Manipulating mission variables in script takes more processing time than manipulating other variables. As such many OXP makers include code to convert mission variables to a this.variable format when the game is started, and convert them back to a mission variable when the game is about to be saved. For example

this.startUp = function() // event handler that is run when Oolite starts, or a save game is loaded.
{
 if (missionVariables.myoxpname_myFirstMissionVariable) // tests to see if that variable exists
 {this.myoxpname_myFirstMissionVariable = missionVariables.myoxpname_myFirstMissionVariable;}
}

this.playerWillSaveGame = function() // event handler that is run just before the game is saved.
{missionVariables.myoxpname_myFirstMissionVariable = this.myoxpname_myFirstMissionVariable;}

More information about mission variables can be found at Oolite JavaScript Reference: Global#missionVariables and Mission variable.

Data Types

Variables can contain boolean (true or false), numbers, strings ("xxx"), and arrays of numbers or strings as data types. Some example of the usage of arrays includes:

this._myFirstArray = [1,2,3];
this._mySecondArray = ["pirate","trader","hunter"];
return this._myFirstArray.length; // will return 3
return this._myFirstArray[0]; // will return the first entry in the Array, 0 in this case.
return this._mySecondArray[1]; // will return the second entry in the Array, "trader" in this case.

For advanced users the Oolite scripting engine also has support for variables in JSON (JavaScript Object Notation) format.