Difference between revisions of "Oolite JavaScript Reference: Script"
(→Common properties: 1.79 updates) |
(→Scripting overview: Property naming, and update examples) |
||
| 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. |
+ | 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. |
+ | this._makeEscortsPerformSpecialManoeuvre = function (target) |
{ |
{ |
||
| − | this.ship.escorts.forEach(function(escort){escort.script. |
+ | 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. |
+ | 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. |
+ | 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== |
||
Latest revision as of 21: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.
Contents
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.
