Difference between revisions of "Oolite JavaScript Reference: Script"

From Elite Wiki
(Common properties: 1.79 updates)
m (Common properties: added code tags)
 
(5 intermediate revisions by 2 users not shown)
Line 2: Line 2:
 
<small>'''Subtypes:''' none</small>
 
<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 several categories of scripts: ''ship scripts'' which are attached to individual ships/in-game entities and ''world scripts'' which are effectively attached to the player.  There are also ''[[Oolite JavaScript Reference: Condition scripts| Condition scripts]]'', ''[[Oolite JavaScript Reference: Equipment scripts| Equipment scripts]]'', ''[[Oolite JavaScript Reference: Market Scripts| Market Scripts]]'' and ''[[Oolite JavaScript Reference: VisualEffect#Effect Scripts|Visual Effects Scripts]]''.
  
 
==Scripting overview==
 
==Scripting overview==
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:
 
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
 
     // Do something very clever here
Line 21: Line 21:
 
which the mothership might do as follows:
 
which the mothership might do as follows:
 
  // Warning: untested code
 
  // 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:
 
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.
 
     // 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 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==
 
==Predefined properties==
 
===<code>ship</code>===
 
===<code>ship</code>===
 
  '''ship''' : [[Oolite JavaScript Reference: Ship|Ship]] (read-only)
 
  '''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, this is the ship to which the script is attached. For world scripts, it is undefined.
  
'''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.
+
'''Note''' that <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==
Line 71: Line 71:
 
===<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 <code>name</code>. It’s a good habit to set a <code>name</code> for all scripts. If no <code>name</code> 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.
+
Starting in Oolite 1.75, any underscores (“_”) or spaces will be removed from the beginning and end of the <code>name</code> 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. It is recommended to have this value equal the version of the OXP containing the script.
+
A string specifying the version of the script. This is used, together with <code>name</code>, 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]]
 
[[Category:Oolite JavaScript Reference]]

Latest revision as of 15:43, 30 October 2022

Prototype: Object
Subtypes: none

The Script class represents a JavaScript script. There are several categories of scripts: ship scripts which are attached to individual ships/in-game entities and world scripts which are effectively attached to the player. There are also Condition scripts, Equipment scripts, Market Scripts and Visual Effects Scripts.

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, this is the ship to which the script is attached. For world scripts, it is undefined.

Note that 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.