Difference between revisions of "Scripting Oolite with JavaScript"

From Elite Wiki
Jump to: navigation, search
 
Line 2: Line 2:
  
 
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.
 
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.
 +
 +
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.
 +
 +
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.
 +
 +
Other event functions will only be called when that state becomes true, like <tt>KeyPressed</tt> and <tt>STATUS_EXITING_WITCHSPACE</tt>.
 +
  
 
=== 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.
 +
 
<pre>
 
<pre>
// Copy and paste this template into a file called script.js in the OXP Config directory
 
//
 
 
this.Name = "OXPName"
 
this.Name = "OXPName"
 
this.Descriptipn = "A description of what the OXP does."
 
this.Descriptipn = "A description of what the OXP does."
Line 25: Line 33:
 
==== Initialise ====
 
==== Initialise ====
  
The initialise 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 <tt>Initialise</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.
  
 
  this.Initialise = function () {
 
  this.Initialise = function () {
Line 33: Line 41:
 
==== KeyPressed ====
 
==== KeyPressed ====
  
The KeyPressed event is called when a key the OXP is listening for has been pressed. It will be called once for each time the key is pressed, and will not be called again until the key is released and then pressed again.
+
The <tt>KeyPressed</tt> event is called when a key the OXP is listening for has been pressed. It will be called once for each time the key is pressed, and will not be called again until the key is released and then pressed again.
  
The keycode argument gives the keycode of the key that was pressed. This can be used to determine which key was pressed if the OXP is listening for more than one key.
+
The <tt>keycode</tt> argument gives the keycode of the key that was pressed. This can be used to determine which key was pressed if the OXP is listening for more than one key.
  
 
  this.KeyPressed = function (keycode) {
 
  this.KeyPressed = function (keycode) {
Line 43: Line 51:
 
==== AlertConditionChanged ====
 
==== AlertConditionChanged ====
  
The AlertConditionChanged event is called when the alert condition changes. The current alert condition can be read from Player.AlertCondition and the current alert flags can be read from Player.AlertFlags.
+
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>.
  
 
  this.AlertConditionChanged = function (keycode) {
 
  this.AlertConditionChanged = function (keycode) {
Line 51: Line 59:
 
==== STATUS_DOCKED ====
 
==== STATUS_DOCKED ====
  
The STATUS_DOCKED event is called periodically while the player is docked at a station or other entity with a docking port.
+
The <tt>STATUS_DOCKED</tt> event is called periodically while the player is docked at a station or other entity with a docking port.
  
 
  this.STATUS_DOCKED = function () {
 
  this.STATUS_DOCKED = function () {
Line 57: Line 65:
  
  
==== STATUS_IN_FIGHT ====
+
==== STATUS_IN_FLIGHT ====
  
The STATUS_IN_FIGHT event is called periodically while the player is flying in normal space or interstellar space (due to a misjump).
+
The <tt>STATUS_IN_FLIGHT</tt> event is called periodically while the player is flying in normal space or interstellar space (due to a misjump).
  
  this.STATUS_IN_FIGHT = function () {
+
  this.STATUS_IN_FLIGHT = function () {
 
  }
 
  }
  
Line 67: Line 75:
 
==== STATUS_LAUNCHING ====
 
==== STATUS_LAUNCHING ====
  
The STATUS_LAUNCHING event is called once when the player has launched from a dock.
+
The <tt>STATUS_LAUNCHING</tt> event is called once when the player has launched from a dock.
  
 
  this.STATUS_LAUNCHING = function () {
 
  this.STATUS_LAUNCHING = function () {
Line 75: Line 83:
 
==== STATUS_EXITING_WITCHSPACE ====
 
==== STATUS_EXITING_WITCHSPACE ====
  
The STATUS_EXITING_WITCHSPACE event is called once when the player arrives in a new system.
+
The <tt>STATUS_EXITING_WITCHSPACE</tt> event is called once when the player arrives in a new system.
  
 
  this.STATUS_EXITING_WITCHSPACE = function () {
 
  this.STATUS_EXITING_WITCHSPACE = function () {
 
  }
 
  }

Revision as of 02:59, 16 January 2007

JavaScript file format

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.

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.

Sometimes the event function will be called periodically, such as STATUS_DOCKED and STATUS_IN_FLIGHT. These functions will be called about every 10 seconds as long as the game is in that state.

Other event functions will only be called when that state becomes true, like KeyPressed and STATUS_EXITING_WITCHSPACE.


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.

this.Name = "OXPName"
this.Descriptipn = "A description of what the OXP does."
this.Version = "1.0"

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

Scripting Events

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

Initialise

The Initialise 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.

this.Initialise = function () {
}


KeyPressed

The KeyPressed event is called when a key the OXP is listening for has been pressed. It will be called once for each time the key is pressed, and will not be called again until the key is released and then pressed again.

The keycode argument gives the keycode of the key that was pressed. This can be used to determine which key was pressed if the OXP is listening for more than one key.

this.KeyPressed = function (keycode) {
}


AlertConditionChanged

The AlertConditionChanged event is called when the alert condition changes. The current alert condition can be read from Player.AlertCondition and the current alert flags can be read from Player.AlertFlags.

this.AlertConditionChanged = function (keycode) {
}


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 () {
}