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
shipWillDockWithStation
The shipWillDockWithStation handler is called at the beginning of the docking tunnel effect.
this.shipWillDockWithStation = function(station)
{
// Your code here
}
shipDockedWithStation
The shipDockedWithStation handler is called at the end of the docking tunnel effect.
this.shipDockedWithStation = function(station)
{
// Your code here
}
shipWillLaunchFromStation
The shipWillLaunchFromStation handler is called at the beginning of the launch tunnel effect. (Is this code still in?)
this.shipWillLaunchFromStation = function()
{
// Your code here
}
shipLaunchedFromStation
The shipLaunchedFromStation handler is called at the end of the launch tunnel effect.
this.shipLaunchedFromStation = 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
}
playerDockingRefused
The playerDockingRefused handler is called when a station refuses to provide autopilot docking instructions.
this. playerDockingRefused = 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
}
playerJumpFailed
The playerJumpFailed 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.playerJumpFailed = function(reason)
{
// Your code here
}
shipWillEnterWitchspace
The shipWillEnterWitchspace 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.shipWillEnterWitchspace = function(cause)
{
// Your code here
}
shipWillExitWitchspace
The shipWillExitWitchspace 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.shipWillExitWitchspace = function()
{
// Your code here
}
shipExitedWitchspace
The shipExitedWitchspace handler is called after a witchspace jump has concluded and the tunnel effect has been shown.
this.shipExitedWitchspace = function()
{
// Your code here
}
shipWillEnterWormhole
The shipWillEnterWormhole handler is called before entering the wormhole.
this.shipWillEnterWormhole = function()
{
// Your code here
}
shipExitedWormhole
The shipExitedWormhole handler is called after leaving the wormhole.
this.shipExitedWormhole = function()
{
// Your code here
}
playerEnteredNewGalaxy
The playerEnteredNewGalaxy handler is called just before a witchspace jump starts.
this.playerEnteredNewGalaxy = function(galaxyNumber)
{
// 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
}
shipDied
The shipDied handler is called when the player dies. Expect a reset() shortly.
this.shipDied = function(whom, why)
{
// Your code here
}
The shipScoopedOther handler is called when the player scoops cargo. (Cargo receives a shipWasScooped handler.)
this.shipScoopedOther = function(whom)
{
// Your code here
}
didLaunchEscapePod
The shipLaunchedEscapePod handler is called when the player bails out. This will be followed by a willDock()/didDock() pair after a few seconds.
this.shipLaunchedEscapePod = function(escapepod)
{
// 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.
