Difference between revisions of "Scripting Oolite with JavaScript"

From Elite Wiki
Jump to: navigation, search
(Changed properties/instance variables to consistently start with lowercase, which is more consistent with normal JS usage, PList script usage and ObjC usage. Also changed initialise to initialize.)
(Cleanup, brought up to date.)
Line 1: Line 1:
== JavaScript file format ==
+
[[Oolite]] 1.68 and later supports scripts written in [http://en.wikipedia.org/wiki/ECMAScript ECMAScript] (more commonly known as [http://en.wikipedia.org/wiki/JavaScript JavaScript]) in addition to its traditional model based on [[property lists]]. This page provides an overview of the JavaScript environment. The page [[Oolite JavaScript object model]] provides reference for Oolite-specific objects and methods. The language standards and some tutorials can be found through the Wikipedia links provided above.
  
To use JavaScript for an OXP, place a file script.js in the OXP's Config directory. Do not also include a script.plist or script.oos file.
+
== Using JavaScript ==
  
OXP scripts written in JavaScript are "event driven" - different functions of the script are called in response to state changes in the game, or when other events of interest happen.
+
Currently, JavaScript is only supported for “world scripts”, that is, as a replacement for scripts in ''script.plist''. While a ''script.plist'' file may contain any number of separate scripts, a single JavaScript file may contain only one script.
  
Sometimes the event function will be called periodically, such as <tt>STATUS_DOCKED</tt> and <tt>STATUS_IN_FLIGHT</tt>. These functions will be called about every 10 seconds as long as the game is in that state.
+
If your OXP only uses one script, place a JavaScript file named ''script.js'' (or ''script.es'') in the OXP’s ''Config'' directory. If you wish to use multiple scripts, you may instead create file named ''world-scripts.plist'' in the ''Config'' directory. This [[property list]] file should consist of an array of script names; the named scripts should exist in a directory named ''Scripts'' inside your OXP. As with most “atomic” files (files which cannot be merged), such script files must have a unique name to avoid conflicts with other OXPs. Using the ''world-scripts.plist'' method, you can combine JavaScript, plist and OOS scripts however you wish.
  
Other event functions will only be called when that state becomes true, like <tt>KeyPressed</tt> and <tt>STATUS_EXITING_WITCHSPACE</tt>.
+
Whereas plist scripts are based on polling – all scripts are run at semi-regular intervals, whether they need to be or not – scripts written in JavaScript are “event driven” – different functions of the script are called in response to state changes in the game, or when other events of interest happen. For instance, <code>STATUS_EXITING_WITCHSPACE</code> is called once when the player exits witchspace, and <code>alertConditionChanged</code> is called whenever the alert condition changes.
 +
 
 +
Certain special “tickle” handlers, such as <code>STATUS_DOCKED</code> and <code>STATUS_IN_FLIGHT</code>, will be called periodically. These functions will be called about every 10 seconds as long as the game is in the relevant state. For efficiency, however, it is best to avoid these events if possible.
  
  
 
=== script.js File Template ===
 
=== script.js File Template ===
  
Copy and paste this template into a file called script.js in the OXP Config directory. Ensure you change at least the Name value.
+
Copy and paste this template into a file called script.js in the OXP Config directory. Ensure you change at least the Name value. '''Every script must have a unique name.''' If multiple scripts with the same name are encountered, Oolite will arbitrary select one and discard the others.
 +
 
 +
<pre>this.name          = "My OXP Script";
 +
this.author        = "Your Name Here";
 +
this.copyright      = "(C) 2007 Me.";
 +
this.description    = "This OXP doesn't do very much yet.";
 +
this.version        = "1.0 alpha 1";
  
<pre>
 
this.name = "OXPName"
 
this.description = "A description of what the OXP does."
 
this.version = "1.0"
 
  
// You can copy and paste this function and just change the "initialize"
+
/You can copy and paste this function and just change the "startUp"
// to another event name to handle other OXP events (eg "STATUS_DOCKED",
+
    to another event name to handle other OXP events (eg "STATUS_DOCKED",
// "alertConditionChanged", etc).
+
    "alertConditionChanged", etc).
//
+
*/
this. initialize = function () {
+
this.startUp = function()
     Log("Initialising OXP " +name)
+
{
}
+
     Log("Initialising OXP " + name);
</pre>
+
}</pre>
  
 
=== Scripting Events ===
 
=== Scripting Events ===
Line 32: Line 36:
 
The following events are available to OXP scripts written in JavaScript.
 
The following events are available to OXP scripts written in JavaScript.
  
==== initialize ====
+
==== <code>startUp</code> ====
 +
 
 +
The <code>startUp</code> handler is called after all OXPs have been loaded. It can be used to do once-off initialisation such as registering to listen for certain keystrokes etc.
 +
 
 +
this.startUp = function()
 +
{
 +
      // Your code here
 +
}
 +
 
 +
==== <code>reset</code> ====
  
The <tt>initialize</tt> event is called after all OXPs have been loaded. It can be used to do once-off initialisation such as registering to listen for certain keystrokes etc.
+
The <code>reset</code> handler is called whenever the player is respawned, such as after dying or when loading a saved game. It should be used to reset any local state in the script.
  
  this.initialize = function () {
+
  this.reset = function()
 +
{
 +
      // Your code here
 
  }
 
  }
  
  
 +
<!--
 
==== keyPressed ====
 
==== keyPressed ====
  
Line 49: Line 65:
  
 
  this.keyPressed = function (keycode) {
 
  this.keyPressed = function (keycode) {
  }
+
  }-->
  
 
==== alertConditionChanged ====
 
==== alertConditionChanged ====
  
The <tt>alertConditionChanged</tt> event is called when the alert condition changes. The current alert condition can be read from <tt>Player.AlertCondition</tt> and the current alert flags can be read from <tt>Player.AlertFlags</tt>.
+
The <code>alertConditionChanged</code> handler is called when the alert condition changes. The current alert condition can be read from <code>olayer.alertCondition</code> and the current alert flags can be read from <code>player.alertFlags</code>.
  
  this.alertConditionChanged = function (keycode) {
+
  this.alertConditionChanged = function ()
 +
{
 +
      // Your code here
 
  }
 
  }
  
Line 89: Line 107:
 
  this.STATUS_EXITING_WITCHSPACE = function () {
 
  this.STATUS_EXITING_WITCHSPACE = function () {
 
  }
 
  }
 +
 +
[[Category:Oolite]] [[Category:Oolite scripting]]

Revision as of 01:33, 1 April 2007

Oolite 1.68 and later supports scripts written in ECMAScript (more commonly known as JavaScript) in addition to its traditional model based on property lists. This page provides an overview of the JavaScript environment. The page Oolite JavaScript object model provides reference for Oolite-specific objects and methods. The language standards and some tutorials can be found through the Wikipedia links provided above.

Using JavaScript

Currently, JavaScript is only supported for “world scripts”, that is, as a replacement for scripts in script.plist. While a script.plist file may contain any number of separate scripts, a single JavaScript file may contain only one script.

If your OXP only uses one script, place a JavaScript file named script.js (or script.es) in the OXP’s Config directory. If you wish to use multiple scripts, you may instead create file named world-scripts.plist in the Config directory. This property list file should consist of an array of script names; the named scripts should exist in a directory named Scripts inside your OXP. As with most “atomic” files (files which cannot be merged), such script files must have a unique name to avoid conflicts with other OXPs. Using the world-scripts.plist method, you can combine JavaScript, plist and OOS scripts however you wish.

Whereas plist scripts are based on polling – all scripts are run at semi-regular intervals, whether they need to be or not – scripts written in JavaScript are “event driven” – different functions of the script are called in response to state changes in the game, or when other events of interest happen. For instance, STATUS_EXITING_WITCHSPACE is called once when the player exits witchspace, and alertConditionChanged is called whenever the alert condition changes.

Certain special “tickle” handlers, such as STATUS_DOCKED and STATUS_IN_FLIGHT, will be called periodically. These functions will be called about every 10 seconds as long as the game is in the relevant state. For efficiency, however, it is best to avoid these events if possible.


script.js File Template

Copy and paste this template into a file called script.js in the OXP Config directory. Ensure you change at least the Name value. Every script must have a unique name. If multiple scripts with the same name are encountered, Oolite will arbitrary select one and discard the others.

this.name           = "My OXP Script";
this.author         = "Your Name Here";
this.copyright      = "(C) 2007 Me.";
this.description    = "This OXP doesn't do very much yet.";
this.version        = "1.0 alpha 1";


/*  You can copy and paste this function and just change the "startUp"
    to another event name to handle other OXP events (eg "STATUS_DOCKED",
    "alertConditionChanged", etc).
*/
this.startUp = function()
{
    Log("Initialising OXP " + name);
}

Scripting Events

The following events are available to OXP scripts written in JavaScript.

startUp

The startUp handler is called after all OXPs have been loaded. It can be used to do once-off initialisation such as registering to listen for certain keystrokes etc.

this.startUp = function()
{
     // Your code here
}

reset

The reset handler is called whenever the player is respawned, such as after dying or when loading a saved game. It should be used to reset any local state in the script.

this.reset = function()
{
     // Your code here
}


alertConditionChanged

The alertConditionChanged handler is called when the alert condition changes. The current alert condition can be read from olayer.alertCondition and the current alert flags can be read from player.alertFlags.

this.alertConditionChanged = function ()
{
     // Your code here
}


STATUS_DOCKED

The STATUS_DOCKED event is called periodically while the player is docked at a station or other entity with a docking port.

this.STATUS_DOCKED = function () {
}


STATUS_IN_FLIGHT

The STATUS_IN_FLIGHT event is called periodically while the player is flying in normal space or interstellar space (due to a misjump).

this.STATUS_IN_FLIGHT = function () {
}


STATUS_LAUNCHING

The STATUS_LAUNCHING event is called once when the player has launched from a dock.

this.STATUS_LAUNCHING = function () {
}


STATUS_EXITING_WITCHSPACE

The STATUS_EXITING_WITCHSPACE event is called once when the player arrives in a new system.

this.STATUS_EXITING_WITCHSPACE = function () {
}