Oolite JavaScript Reference: Script - Revision history

Cim: /* Scripting overview */ Property naming, and update examples

2014-05-19T20:59:10Z

‎Scripting overview: Property naming, and update examples

Cim: /* Common properties */ 1.79 updates

2014-05-19T20:56:19Z

‎Common properties: 1.79 updates

GGShinobi: /* Scripting overview */ typo

2013-01-21T06:55:33Z

‎Scripting overview: typo

Ahruman: Cleanup, made stuff valid. Absolutely do not declare functions as “function x()” in global scope in Oolite scripts.

2010-06-28T08:51:14Z

Cleanup, made stuff valid. Absolutely do not declare functions as “function x()” in global scope in Oolite scripts.

Kaks at 15:52, 27 June 2010

2010-06-27T15:52:45Z

Kaks: /* ship */

2010-06-27T15:51:30Z

‎ship

Kaks: /* ship */

2010-06-27T15:50:31Z

‎ship

Ahruman at 14:29, 20 June 2010

2010-06-20T14:29:09Z

Ahruman: Moving Oolite JS reference into a correctly-named subcategory of Oolite scripting.

2010-06-19T14:05:57Z

Moving Oolite JS reference into a *correctly-named* subcategory of Oolite scripting.

Ahruman: Moving Oolite JS reference into a subcategory of Oolite scripting.

2010-06-19T13:56:14Z

Moving Oolite JS reference into a subcategory of Oolite scripting.

@@ Line 15: / Line 15: @@
 A property of the <code>Script</code> object which is a function is called a '''method'''. The most common use for methods is for event handlers, but a script may assign itself arbitrary methods, and any script may call the methods of another <code>Script</code> object. For instance, consider the case of a ship which needs to interact with its escorts in an unusual way. The script for the escorts may define a method such as:
- this.escortPerformSpecialManoeuvre = function (target)
+ this._escortPerformSpecialManoeuvre = function (target)
+ {
      // Do something very clever here
@@ Line 21: / Line 21: @@
 which the mothership might do as follows:
  // Warning: untested code
- this.makeEscortsPerformSpecialManoeuvre = function (target)
+ this._makeEscortsPerformSpecialManoeuvre = function (target)
+ {
-     this.ship.escorts.forEach(function(escort){escort.script.escortPerformSpecialManoeuvre(this.target)}, this);
+     this.ship.escorts.forEach(function(escort){escort.script._escortPerformSpecialManoeuvre(this.target)}, this);
+ }
 I can hear the cries of “huh” now, so let’s expand on that a little:
- this.makeEscortsPerformSpecialManoeuvre = function (target)
+ this._makeEscortsPerformSpecialManoeuvre = function (target)
+ {
      // The function we want to call for each element of the escorts array.
      function callEscortMethod(escort)
+     {
-         escort.script.escortPerformSpecialManoeuvre(this.target);
+         escort.script._escortPerformSpecialManoeuvre(this.target);
+     }
@@ Line 41: / Line 41: @@
+ }
-<code>Script</code> objects do not have many predefined properties. Instead, the script can set whatever properties it needs. Which properties are used by the game depends on the context in which the script is being used.
+<code>Script</code> objects do not have many predefined properties. Instead, the script can set whatever properties it needs. Which properties are used by the game depends on the context in which the script is being used. Note that properties not intended to be event handlers should have names starting with an '_' or '$' character, so that future additions of Oolite event handlers do not cause a conflict.
 ==Predefined properties==

@@ Line 51: / Line 51: @@
 ==Common properties==
 ===<code>author</code>===
  '''author''' : String
 ===<code>copyright</code>===
  '''copyright''' : String
-A copyright statement for the script. Currently unused.
+A copyright statement for the script. This property is currently not checked by any Oolite core functionality.
 ===<code>description</code>===
  '''description''' : String
-A short description of the script. Currently unused.
+A short description of the script. This property is currently not checked by any Oolite core functionality.
 ===<code>name</code>===
@@ Line 73: / Line 73: @@
 ===<code>version</code>===
  '''version''' : String
-A string specifying the version of the script. This is used, together with name, for identification in log messages and similar. While it is possible to set the <code>version</code> property at any time, the value used after the script is first run is the one Oolite will continue to use.
+A string specifying the version of the script. This is used, together with name, for identification in log messages and similar. While it is possible to set the <code>version</code> property at any time, the value used after the script is first run is the one Oolite will continue to use. It is recommended to have this value equal the version of the OXP containing the script.
 [[Category:Oolite JavaScript Reference]]

@@ Line 14: / Line 14: @@
 This assigns an anonymous function with no arguments to the <code>Script</code> object’s <code>willDock</code> property.
-A property of the <code>Script</code> object which is a function is called a '''method'''. The most common use for methods is for event handlers, but a script may assign itself arbitrary methods, and any script may call the methods of anothe <code>Script</code> object. For instance, consider the case of a ship which needs to interact with its escorts in an unusual way. The script for the escorts may define a method such as:
+A property of the <code>Script</code> object which is a function is called a '''method'''. The most common use for methods is for event handlers, but a script may assign itself arbitrary methods, and any script may call the methods of another <code>Script</code> object. For instance, consider the case of a ship which needs to interact with its escorts in an unusual way. The script for the escorts may define a method such as:
  this.escortPerformSpecialManoeuvre = function (target)
+ {

@@ Line 1: / Line 1: @@
 <small>'''Prototype:''' <code>Object</code></small><br />
-<small>'''Subtypes:''' none
+<small>'''Subtypes:''' none</small>
-The '''<code>Script</code>''' class represents a JavaScript script. There are currently two categories of script: ''ship scripts'', which are attached to individual ships / in-game entities, and ''world scripts'', which are effectively attached to the player.
+The '''<code>Script</code>''' class represents a JavaScript script. There are currently two categories of script: ''ship scripts'', which are attached to individual ships/in-game entities, and ''world scripts'', which are effectively attached to the player.
 ==Scripting overview==
@@ Line 9: / Line 9: @@
+ {
      // Do stuff when about to dock
-     Log("Woo, I’m about to dock!");
+     log("Woo, I’m about to dock!");
+ }
-This assigns an anonymous function with no arguments to the <code>Script</code> object’s <code>willDock</code> property. Another way to achieve the same thing would be:
+This assigns an anonymous function with no arguments to the <code>Script</code> object’s <code>willDock</code> property.
 A property of the <code>Script</code> object which is a function is called a '''method'''. The most common use for methods is for event handlers, but a script may assign itself arbitrary methods, and any script may call the methods of anothe <code>Script</code> object. For instance, consider the case of a ship which needs to interact with its escorts in an unusual way. The script for the escorts may define a method such as:
- this.escortPerformSpecialManoeuvret(target)
+ this.escortPerformSpecialManoeuvre = function (target)
+ {
      // Do something very clever here
@@ Line 21: / Line 21: @@
 which the mothership might do as follows:
  // Warning: untested code
+ {
      this.ship.escorts.forEach(function(escort){escort.script.escortPerformSpecialManoeuvre(this.target)}, this);
+ }
 I can hear the cries of “huh” now, so let’s expand on that a little:
+ {
      // The function we want to call for each element of the escorts array.
@@ Line 40: / Line 40: @@
      escorts.forEach(callEscortMethod, this);
+ }
-<code>Script</code> objects to not have many predefined properties. Instead, the script can set whatever properties it needs. Which properties are used by the game depends on the context in which the script is being used.
+<code>Script</code> objects do not have many predefined properties. Instead, the script can set whatever properties it needs. Which properties are used by the game depends on the context in which the script is being used.
 ==Predefined properties==
@@ Line 49: / Line 48: @@
 For ship scripts, the ship to which the script is attached. Undefined for world scripts.
-'''N.B.''' ship refers to the entity that 'owns' the script, which might not be an actual ship. If a specific script is a property of an asteroid as opposed to a ship, ''this.ship'' will refer to the asteroid, etc...
+'''Note''' <code>ship</code> refers to the {{oojsclass|Ship}} object that “owns” the script, which might not be a ship from a player perspective; it may be a station, missile, asteroid etc.
 ==Common properties==
@@ Line 69: / Line 68: @@
  '''name''' : String
 The name of the script. World scripts must have a unique name. It’s a good habit to set a name for all scripts. If no name is set when the script is first run, Oolite will make one up. While it is possible to set the <code>name</code> property at any time, the value used after the script is first run is the one Oolite will continue to use.
 ===<code>version</code>===

@@ Line 2: / Line 2: @@
 <small>'''Subtypes:''' none
-The '''<code>Script</code>''' class represents a JavaScript script. There are currently two categories of script: ''ship scripts'', which are attached to individual ships, and ''world scripts'', which are effectively attached to the player.
+The '''<code>Script</code>''' class represents a JavaScript script. There are currently two categories of script: ''ship scripts'', which are attached to individual ships / in-game entities, and ''world scripts'', which are effectively attached to the player.
 ==Scripting overview==

← Older revision		Revision as of 15:50, 27 June 2010
Line 59:		Line 59:
	For ship scripts, the ship to which the script is attached. Undefined for world scripts.		For ship scripts, the ship to which the script is attached. Undefined for world scripts.

		+	'''N.B.''' ship refers to the entity that 'owns' the script, which might not be an actual ship. If a specific script is a property of an asteroid as opposed to a ship, this.ship will refer to the asteroid, etc...

	==Common properties==		==Common properties==

@@ Line 56: / Line 56: @@
 ==Predefined properties==
 ===<code>ship</code>===
- ship [read-only [[Oolite JavaScript Reference: Ship|Ship]]]
+ '''ship''' : [[Oolite JavaScript Reference: Ship|Ship]] (read-only)
 For ship scripts, the ship to which the script is attached. Undefined for world scripts.

← Older revision		Revision as of 14:05, 19 June 2010
Line 83:		Line 83:
	A string specifying the version of the script. This is used, together with name, for identification in log messages and similar. While it is possible to set the <code>version</code> property at any time, the value used after the script is first run is the one Oolite will continue to use.		A string specifying the version of the script. This is used, together with name, for identification in log messages and similar. While it is possible to set the <code>version</code> property at any time, the value used after the script is first run is the one Oolite will continue to use.

−	[[Category:Oolite JavaScript ~~reference~~]]	+	[[Category:Oolite JavaScript Reference]]

← Older revision		Revision as of 13:56, 19 June 2010
Line 83:		Line 83:
	A string specifying the version of the script. This is used, together with name, for identification in log messages and similar. While it is possible to set the <code>version</code> property at any time, the value used after the script is first run is the one Oolite will continue to use.		A string specifying the version of the script. This is used, together with name, for identification in log messages and similar. While it is possible to set the <code>version</code> property at any time, the value used after the script is first run is the one Oolite will continue to use.

−	[[Category:Oolite ~~scripting~~]]	+	[[Category:Oolite JavaScript reference]]

Oolite JavaScript Reference: Script - Revision history

Cim: /* Scripting overview */ Property naming, and update examples

Cim: /* Common properties */ 1.79 updates

GGShinobi: /* Scripting overview */ typo

Ahruman: Cleanup, made stuff valid. Absolutely do not declare functions as “function x()” in global scope in Oolite scripts.

Kaks at 15:52, 27 June 2010

Kaks: /* ship */

Kaks: /* ship */

Ahruman at 14:29, 20 June 2010

Ahruman: Moving Oolite JS reference into a *correctly-named* subcategory of Oolite scripting.

Ahruman: Moving Oolite JS reference into a subcategory of Oolite scripting.

Ahruman: Moving Oolite JS reference into a correctly-named subcategory of Oolite scripting.