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 }
playerStartedAutoPilot
The playerStartedAutoPilot
handler is called when the player starts autopilot docking. It is not called for the instantaneous dock command.
this.playerStartedAutoPilot = function() { // Your code here }
playerCancelledAutoPilot
The playerCancelledAutoPilot
handler is called when the player cancels autopilot docking.
this.playerCancelledAutoPilot = 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
playerStartedJumpCountdown
The playerStartedJumpCountdown
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.playerStartedJumpCountdown = function(type) { // Your code here }
playerCancelledJumpCountdown
The playerCancelledJumpCountdown
handler is called when the user cancels a witchspace or galactic witchspace jump countdown.
this.playerCancelledJumpCountdown = 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 }
shipScoopedOther
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.