Difference between revisions of "Oolite JavaScript Reference: Script"

From Elite Wiki
(Scripting overview: Property naming, and update examples)
(9 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
<small>'''Prototype:''' <code>Object</code></small><br />
 
<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, 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==
 
==Scripting overview==
Line 9: Line 9:
 
  {
 
  {
 
     // Do stuff when about to dock
 
     // 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.
function willDockEventHandler()
 
{
 
    // Do stuff when about to dock
 
    Log("Woo, I’m about to dock!");
 
}
 
this.willDock = willDockEventHandler;
 
 
 
This form has the advantage that it’s easy to remove and re-add the event handler. (Event handlers may be added or removed at any time.)
 
delete this.willDock;  // stop handling willDock events
 
this.willDock = willDockEventHandler;  // start handling willDock events again
 
  
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.escortPerformSpecialManoeuvret(target)
+
  this._escortPerformSpecialManoeuvre = function (target)
 
  {
 
  {
 
     // Do something very clever here
 
     // Do something very clever here
Line 31: Line 21:
 
which the mothership might do as follows:
 
which the mothership might do as follows:
 
  // Warning: untested code
 
  // Warning: untested code
  function makeEscortsPerformSpecialManoeuvre(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:
 
I can hear the cries of “huh” now, so let’s expand on that a little:
  function makeEscortsPerformSpecialManoeuvre()
+
  this._makeEscortsPerformSpecialManoeuvre = function (target)
 
  {
 
  {
 
     // The function we want to call for each element of the escorts array.
 
     // The function we want to call for each element of the escorts array.
 
     function callEscortMethod(escort)
 
     function callEscortMethod(escort)
 
     {
 
     {
         escort.script.escortPerformSpecialManoeuvre(this.target);
+
         escort.script._escortPerformSpecialManoeuvre(this.target);
 
     }
 
     }
 
      
 
      
Line 50: Line 40:
 
     escorts.forEach(callEscortMethod, this);
 
     escorts.forEach(callEscortMethod, this);
 
  }
 
  }
Note: it is a good idea to use reasonably unique names for methods. If your ship script implements a <code>doStuff</code> method, and some other ship script implements a <code>doStuff</code> method that does something completely different, one may be called when the other was intended.
 
  
<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. 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==
 
==Predefined properties==
 
===<code>ship</code>===
 
===<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.
 
For ship scripts, the ship to which the script is attached. Undefined for world scripts.
  
 +
'''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==
 
==Common properties==
These are properties scripts can set on themselves which have a standard meaning.
+
These are properties scripts can set on themselves which have a standard meaning. In Oolite 1.79 and later, the <code>author</code>, <code>license</code> and <code>version</code> properties will be set automatically from the [[manifest.plist]] file if one is available, and so do not need to be included in the script file itself.
  
 
===<code>author</code>===
 
===<code>author</code>===
 
  '''author''' : String
 
  '''author''' : String
Who wrote the script. Currently unused.
+
Who wrote the script. This property is currently not checked by any Oolite core functionality.
  
 
===<code>copyright</code>===
 
===<code>copyright</code>===
 
  '''copyright''' : String
 
  '''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>===
 
===<code>description</code>===
 
  '''description''' : String
 
  '''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>license</code>===
 +
'''license''' : String
 +
A statement of the license for the script. This property is currently not checked by any Oolite core functionality.
  
 
===<code>name</code>===
 
===<code>name</code>===
 
  '''name''' : String
 
  '''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.
 
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.
 +
 +
Starting in Oolite 1.75, any underscores (“_”) or spaces will be removed from the beginning and end of the name property.
  
 
===<code>version</code>===
 
===<code>version</code>===
 
  '''version''' : String
 
  '''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 scripting]]
+
[[Category:Oolite JavaScript Reference]]

Revision as of 20:59, 19 May 2014

Prototype: Object
Subtypes: none

The Script 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

World scripts are run once at game start-up, at which point they may create event handlers. Event handlers are functions with predefined names which are called by the game at specific points. Ship scripts are run when their ship is loaded, and can also create event handlers. An event handler is specified as a property of the Script object itself. For example, to set up an event handler for the willDock event, a script would typically look like this:

this.willDock = function()
{
    // Do stuff when about to dock
    log("Woo, I’m about to dock!");
}

This assigns an anonymous function with no arguments to the Script object’s willDock property.

A property of the Script 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 Script 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)
{
    // Do something very clever here
}

which the mothership might do as follows:

// Warning: untested code
this._makeEscortsPerformSpecialManoeuvre = function (target)
{
    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)
{
    // The function we want to call for each element of the escorts array.
    function callEscortMethod(escort)
    {
        escort.script._escortPerformSpecialManoeuvre(this.target);
    }
    
    // Get the list of escorts from our ship.
    var escorts = this.ship.escorts;
    
    // For each element in the list, call callEscortMethod().
    escorts.forEach(callEscortMethod, this);
}

Script 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

ship

ship : Ship (read-only)

For ship scripts, the ship to which the script is attached. Undefined for world scripts.

Note ship refers to the 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

These are properties scripts can set on themselves which have a standard meaning. In Oolite 1.79 and later, the author, license and version properties will be set automatically from the manifest.plist file if one is available, and so do not need to be included in the script file itself.

author

author : String

Who wrote the script. This property is currently not checked by any Oolite core functionality.

copyright

copyright : String

A copyright statement for the script. This property is currently not checked by any Oolite core functionality.

description

description : String

A short description of the script. This property is currently not checked by any Oolite core functionality.

license

license : String

A statement of the license for the script. This property is currently not checked by any Oolite core functionality.

name

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 name property at any time, the value used after the script is first run is the one Oolite will continue to use.

Starting in Oolite 1.75, any underscores (“_”) or spaces will be removed from the beginning and end of the name property.

version

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