Variables in Oolite JavaScripts - Revision history

Norby: /* Data Types */

2016-06-05T15:07:40Z

‎Data Types

Cim: /* Data Types */ Make it a good example with _ prefix

2012-07-11T14:24:05Z

‎Data Types: Make it a good example with _ prefix

Cim: /* Local and Global variables */ _ or $ local namespace

2012-07-11T14:23:12Z

‎Local and Global variables: _ or $ local namespace

Capt. Murphy: /* Mission Variables */

2011-08-13T06:22:23Z

‎Mission Variables

Capt. Murphy: /* Mission Variables */

2011-08-13T06:19:26Z

‎Mission Variables

Capt. Murphy: /* Mission Variables */

2011-08-13T06:11:53Z

‎Mission Variables

Capt. Murphy: Created page with '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 com…'

2011-08-13T06:08:40Z

Created page with '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 com…'

New page

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.

<pre>myVariable = x;</pre>

will create a global variable and should be avoided.

<pre>this.myVariable = x;</pre>

will limit the scope of the variable to the current (''this'') script and is the recommended method.

<pre>var myVariable = x;</pre>

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.

== 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

<pre>missionVariables.myoxpname_myFirstMissionVariable = xxx</pre>

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

<pre>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;}
</pre>

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:

<pre>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.
</pre>

For advanced users the Oolite scripting engine also has support for variables in [http://en.wikipedia.org/wiki/JSON JSON (JavaScript Object Notation)] format.

[[Category:Oolite scripting]]

@@ Line 49: / Line 49: @@
 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._myFirstArray[0]; // will return the first entry in the Array, 1 in this case.
 return this._mySecondArray[1]; // will return the second entry in the Array, "trader" in this case.
 </pre>

@@ Line 21: / Line 21: @@
 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
-<pre>missionVariables.myoxpname_myFirstMissionVariable = xxx;</pre>
+<pre>missionVariables.myoxpname_myFirstMissionVariable = x;</pre>
 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

@@ Line 46: / Line 46: @@
 Some example of the usage of arrays includes:
-<pre>this.myFirstArray = [1,2,3];
+<pre>this._myFirstArray = [1,2,3];
-this.mySecondArray = ["pirate","trader","hunter"];
+this._mySecondArray = ["pirate","trader","hunter"];
-return this.myFirstArray.length; // will return 3
+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._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.
+return this._mySecondArray[1]; // will return the second entry in the Array, "trader" in this case.
 </pre>

@@ Line 11: / Line 11: @@
 <pre>this.myVariable = x;</pre>
-will limit the scope of the variable to the current (''this'') script and is the recommended method.
+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
 <pre>var myVariable = x;</pre>
-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.
+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 ==

@@ Line 35: / Line 35: @@
 </pre>
-More information about mission variables can be found at [[Oolite_JavaScript_Reference:_Global#missionVariables]] and [[Mission_variable]].
+More information about mission variables can be found at [[Oolite JavaScript Reference: Global#missionVariables]] and [[Mission variable]].
 == Data Types ==