Oolite JavaScript Reference: World script event handlers

Note: this documentation is incomplete and out of date. It will be updated soon.

This page provides an exhaustive list of event handlers which can be implemented by JavaScript scripts for Oolite.

Game State

startUp

The startUp handler is called after all OXPs have been loaded. It can be used to do one-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
}

Docking

willDock

The willDock handler is called at the beginning of the docking tunnel effect.

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

didDock

The didDock handler is called at the end of the docking tunnel effect.

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

willLaunch

The willLaunch handler is called at the beginning of the launch tunnel effect.

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

didLaunch

The didLaunch handler is called at the end of the launch tunnel effect.

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

didStartAutoPilot

The didStartAutoPilot handler is called when the player starts autopilot docking. It is not called for the instantaneous dock command.

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

didAbortAutoPilot

The didAbortAutoPilot handler is called when the player cancels autopilot docking.

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

didRecieveDockingRefusal

The didRecieveDockingRefusal handler is called when a station refuses to provide autopilot docking instructions.

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

Witchspace Jumps

didBeginJumpCountDown

The didBeginJumpCountDown handler is called when the user starts a witchspace or galactic witchspace jump countdown. The type parameter is a string specifying which type of jump is occuring; currently, the possible values are “standard” and “galactic”. Other values may be added in future.

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

didCancelJumpCountDown

The didCancelJumpCountDown handler is called when the user cancels a witchspace or galactic witchspace jump countdown.

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

didFailToJump

The didFailToJump handler is called at the end of a witchspace or galactic witchspace countdown, if the jump is not possible. The reason parameter is a string specifying why the jump failed; currently, the possible values are “blocked”, “too far” and “insufficient fuel”. Other values may be added in future.

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

willEnterWitchSpace

The willEnterWitchSpace handler is called immediately before a witchspace jump, while the player is still in the starting system. The cause parameter is a string specifying what sort of jump is occuring; currently, the possible values are “standard jump”, “galactic jump” and “wormhole”. Other values may be added in future.

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

willExitWitchSpace

The willExitWitchSpace handler is called as a witchspace jump concludes. When it is called, the player is (from a program perspective) in the destination system, but the tunnel effect has not yet been shown. This is the reccomended time to set up elements which, so to speak, were already there when the player arrived.

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

didExitWitchSpace

The didExitWitchSpace handler is called after a witchspace jump has concluded and the tunnel effect has been shown.

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

Other

alertConditionChanged

The alertConditionChanged handler is called when the player’s alert status (player.alertCondition) changes.

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

didBecomeDead

The didBecomeDead handler is called when the player dies. Expect a reset() shortly.

this.didBecomeDead = function(whom, why)
{
     // Your code here
}

didLaunchEscapePod

The didLaunchEscapePod handler is called when the player bails out. This will be followed by a willDock()/didDock() pair after a few seconds.

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

tickle

The tickle handler is called periodically-ish, whenever the old plist scripts are updated. For performance reasons, it is reccomended that you avoid using this if possible, but it may be needed until the planned timer mechanism is implemented.

The status parameter is a string containing the player’s current status - “STATUS_IN_FLIGHT” and “STATUS_DOCKED” being commonly-seen examples.

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

Not Yet Implemented

Handlers do not yet exist for the following events:

• Enter/exit station aegis.
• Target changed.
• Advanced space compass mode changed.
• Cloaking device events.

Additionally, there are plans for a timer mechanism whereby a script can request that a function be called at a specific point in the future. If there are other events you would like to be able to respond to, please write a request on the forum.