Oolite JavaScript Reference: World script event handlers

This page provides a list of event handlers which can be implemented inside world scripts JavaScript scripts for Oolite. Additionally, ship script handlers called on the player's ship will cause an equivalent world script event.

Most event handlers can be used both in world scripts and in ship scripts. Generally speaking, handlers starting with "ship" can be used for both scripts and those starting with "player" are meant only for the player (= can only be used in a world script). Exceptions on this rule are mentioned with the individual handlers below.

World scripts can be either found inside Config\script.js, or be distinctly named .js files inside the Scripts directory - in the latter case, the worldScript.plist will list the active world scripts.

World scripts are always active.

The list of event handlers will change from version to version (usually additions of extra handlers). For this reason, any variables or functions you create as this.variable should have a name beginning with '_' or '$' - e.g. this._variable or this.$variable - to avoid potential conflicts with future event handlers (which will never start with '_' or '$').

The startUp handler is called after all OXPs have been loaded. This also means that it is called every time the player loads a game, begins a new game or presses space after dying. It can be used to do one-off initialisation such as copying mission variables into this.* properties for efficiency or setting up data arrays to be used by the script in other handlers. (world script only)

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

`playerWillSaveGame`

The playerWillSaveGame handler is called whenever the player saves a game. The transferred message is one of the following strings: 'standardSave', 'autoSave' or 'quickSave'

this.playerWillSaveGame = function(message : String)
{
     // Your code here
}

Using this event is useful for storing temporary variables in missionVariables, just before the game gets saved. missionVariables are slow in use compared to normal JS variables, therefor their use should be minimised for efficient code. The main benefit of using missionVariables is that they are saved in a saved game.

Docking

`shipWillDockWithStation`

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

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

At this moment "ship.dockedStation == null", "ship.docked == true", "ship.status == STATUS_DOCKING"

`shipDockedWithStation`

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

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

At this moment "ship.dockedStation == the station", "ship.docked == true", "ship.status == STATUS_DOCKED" and "gui_screen" is either GUI_SCREEN_STATUS or GUI_SCREEN_REPORT. However, any identical handler from an other oxp could have changed those values. Never count on it but double check when important.

`shipWillLaunchFromStation`

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

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

At this moment "ship.dockedStation == the station", "ship.docked == false", "ship.status == STATUS_LAUNCHING".

`shipLaunchedFromStation`

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

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

At this moment "ship.dockedStation == null", "ship.docked == false", "ship.status == STATUS_IN_FLIGHT".

`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
}

`playerRequestedDockingClearance`

The playerRequestedDockingClearance handler is called when a station answers on a docking request of the player by targeting the station and pressing L (shift-l).

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

Message is a string and can take the values: "DOCKING_CLEARANCE_GRANTED", "DOCKING_CLEARANCE_DENIED_TRAFFIC_OUTBOUND", "DOCKING_CLEARANCE_DENIED_TRAFFIC_INBOUND", "DOCKING_CLEARANCE_DENIED_SHIP_FUGITIVE", "DOCKING_CLEARANCE_NOT_REQUIRED", "DOCKING_CLEARANCE_EXTENDED" or "DOCKING_CLEARANCE_CANCELLED".

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. The seconds parameter is a number specifying the number of seconds the countdown is running for.

this.playerStartedJumpCountdown = function(type, seconds)
{
     // 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. The current values are:

"insufficient fuel" - the ship no longer has enough fuel to make the jump (e.g. injector use or fuel leak).
"blocked" - a heavy ship is near the player (specifically object mass / object distance² >= 10.0, and object distance <= scanner range).
"malfunction" - the jump malfunctioned in a way that leaves the player ship in the current system.
"malfunction" - the Galactic Hyperdrive is damaged or removed during a galactic jump countdown.

Also theoretically possible but unlikely in current Oolite:

"too far" - the jump destination is outside the 7LY range (but wasn't when the countdown started).
"no target" - the jump destination is the current location (but wasn't when the countdown started).

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. Use this event to set up elements which need to be present in-system after the player exits witchspace.

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
}

`playerEnteredNewGalaxy`

The playerEnteredNewGalaxy handler is called just before shipWillExitWitchspace.

the sequence of events for a player jumping to a different galaxy is as follows:

shipWillEnterWitchspace (world event)
playerWillEnterWitchspace (NPC ship event)
playerEnteredNewGalaxy (world event)
shipWillExitWitchspace (world event)
shipExitedWitchspace (world event)

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

Enter/Exit Aegis

`shipEnteredStationAegis`

The shipEnteredStationAegis handler is called when the player enters the aegis of the main-station (2x scanner range from main-station). Other stations than the main-station don't give aegis messages.

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

`shipExitedStationAegis`

The shipExitedStationAegis handler is called when the player leaves the aegis of the main-station (2x scanner range from main-station).

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

`shipEnteredPlanetaryVicinity`

The shipEnteredPlanetaryVicinity handler is called when the player enters the planet aegis (3x planet radius).

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

`shipExitedPlanetaryVicinity`

The shipExitedPlanetaryVicinity handler is called when the player leaves the planet aegis (3x planet radius).

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

`shipApproachingPlanetSurface`

The shipApproachingPlanetSurface handler is called when the player is very close to the planet (crosses a border ± 500 meter above the surface).

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

`shipLeavingPlanetSurface`

The shipLeavingPlanetSurface handler is called when the player leaves the planet (crosses a border ± 500 meter above the surface).

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

Combat

`alertConditionChanged`

The alertConditionChanged handler is called when the player’s alert status (player.alertCondition) changes. Only the player and stations have an alert condition. (world script and station scripts)

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

`playerTargetedMissile`

The playerTargetedMissile handler is called when the player targets the nearest missile by pressing T (shift-t) on the keybord.

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

`shipAttackedOther`

The shipAttackedOther handler is called when the player hits another with a laser shot. other is the identity of the ship being hit.

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

`shipAttackedWithMissile`

The shipAttackedWithMissile handler is called when a missile is fired. missile contains the missile entity and whom the identity of the ship that launched the missile.

this.shipAttackedWithMissile = function(missile, whom)
{
     // Your code here
}

`shipBeingAttacked`

The shipBeingAttacked handler is called when a laser shot hits. whom the identity of the ship that attacked.

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

`shipBeingAttackedByCloaked`

The shipBeingAttackedByCloaked handler is called when a laser shot from a cloaked ship hits. Guess what, there is no parameter because he is cloaked!

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

`shipKilledOther`

The shipKilledOther handler is called when a ship kills an other ship. whom the identity of the ship that was killed. damageType is the type of damage. (Handler added in test version 1.75)

this.shipKilledOther = function(whom,damageType)
{
     // Your code here
}

`shipTargetDestroyed`

The shipTargetDestroyed handler is called when the target gets destroyed. target contains the destroyed target entity. This command is always preceded by the shipTargetLost handler.

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

`shipDied`

The shipDied handler is called when the ship or player dies. Expect a reset() shortly when it is the player ship.

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

whom contains the entity that caused the kill. why is the cause written as string and is one of: "removed", "hit a planet", "energy damage", "scrape damage", "heat damage", "cascade weapon".
("cascade weapon" is new in 1.74 and "removed" / "energy damage" were accidentally switched in 1.73)

`shipFiredMissile`

The shipFiredMissile handler is called when a missile is fired. missile contains the missile entity and target the identity of the target. The handler is send to the ship that launched the missile.

this.shipFiredMissile = function(missile, target)
{
     // Your code here
}

`shipTargetLost`

The shipTargetLost handler is called when the target gets lost. target contains the lost target entity.

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

`shipTargetCloaked`

The shipTargetCloaked handler is called when the target cloakes.

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

Equipment and Cargo

`equipmentDestroyed`

The equipmentDestroyed handler is called when equipment gets destroyed completely beyond repair. (in strict mode) (world script only)

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

`equipmentDamaged`

The equipmentDamaged handler is called when equipment gets damaged. (world script only)

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

`equipmentRepaired`

This method was added in Oolite test release 1.77.

The equipmentRepaired handler is called when equipment gets repaired. (world script only)

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

`playerBoughtCargo`

This method was added in Oolite test release 1.77.

The playerBoughtCargo handler is called when cargo is bought at the market screen. commodity contains the non-localised name for the cargo. You can get the localised name using expandDescription("[commodity-name "+commodity+"]");. price is price per unit in tenths of a credit.

this.playerBoughtCargo = function(commodity, units, price)
{
     // Your code here
}

`playerBoughtEquipment`

The playerBoughtEquipment handler is called when equipment is bought at the outfit screen.

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

`playerBoughtNewShip`

The playerBoughtNewShip handler is called when a new ship is bought. May be needed to re-evaluate the old equipment as buying a new ship does not trigger equipment removal.

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

`playerSoldCargo`

This method was added in Oolite test release 1.77.

The playerSoldCargo handler is called when cargo is sold at the market screen. commodity contains the non-localised name for the cargo. You can get the localised name using expandDescription("[commodity-name "+commodity+"]");. price is price per unit in tenths of a credit.

this.playerSoldCargo = function(commodity, units, price)
{
     // Your code here
}

`shipScoopedFuel`

This method was added in Oolite test release 1.77.

The shipScoopedFuel handler is called whenever the player's ship transfers 0.1LY of fuel from the scoops to the tank.

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

`shipScoopedOther`

The shipScoopedOther handler is called when a ship scoops cargo. The scooped item is transferred as argument.
If the cargo is scripted cargo, but not otherwise, then the scooped cargo itself gets the handler shipWasScooped with the scooper as argument.

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

Other

`compassTargetChanged`

The compassTargetChanged handler is called when a new target is selected. Mode can be any of the following:

COMPASS_MODE_BASIC
COMPASS_MODE_PLANET
COMPASS_MODE_STATION
COMPASS_MODE_SUN
COMPASS_MODE_TARGET
COMPASS_MODE_BEACONS

script example

this.compassTargetChanged = function(whom, mode)
{
     log(' Now targeting ' + whom);
     // Your code here
}

`dayChanged`

This method was added in Oolite test release 1.77.

The dayChanged handler is called each time a new day starts. At very low frame rates while the clock is updating, it is possible for this handler to be called twice in the same frame. Therefore, clock.days will not be correct for one of the calls. Use the day number passed to the function instead.

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

`guiScreenChanged`

The guiScreenChanged handler is called when the guiScreen changes. "from" is the screen it is changing from and "to" is the screen were it initially switched to. Note that the screen can have changed again in the meantime by the action of other oxps. Therefor, it will generally better to test for the global guiScreen to see which page is really on display instead of using the "to" parameter. (world script only)
This handler will not fire for every screen the player can switch to, but only when switching to any of the following screens:

1.76: GUI_SCREEN_MAIN, GUI_SCREEN_STATUS, GUI_SCREEN_MANIFEST, GUI_SCREEN_SYSTEM_DATA, GUI_SCREEN_OPTIONS, GUI_SCREEN_EQUIP_SHIP, GUI_SCREEN_SHIPYARD, GUI_SCREEN_SHORT_RANGE_CHART, GUI_SCREEN_LONG_RANGE_CHART, GUI_SCREEN_MARKET, GUI_SCREEN_CONTRACTS, GUI_SCREEN_REPORT

1.77: adds GUI_SCREEN_INTERFACES

this.guiScreenChanged = function(to, from)
{
     // Your code here
}

`guiScreenWillChange`

The guiScreenWillChange handler is called when the guiScreen is about to change. It only fires for the screens: GUI_SCREEN_EQUIP_SHIP, GUI_SCREEN_MANIFEST, GUI_SCREEN_MARKET, GUI_SCREEN_SHIPYARD and GUI_SCREEN_SYSTEM_DATA (in 1.77, also GUI_SCREEN_STATUS). On these screens a script could change the content of the page to be displayed. (world script only)

this.guiScreenWillChange = function(to, from)
{
     // Your code here
}

`missionChoiceWasReset`

The missionChoiceWasReset handler is called when the mission choice is set to null via script (either using the legacy script method resetMissionChice, or using mission.choice = null; in javascript)

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

`missionScreenEnded`

The missionScreenEnded handler is called when the missionscreen ends. Note that an other script may have put up a new missionscreen in the meantime. (world script only)

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

`missionScreenOpportunity`

The missionScreenOpportunity handler is called if there are no mission / report screens active, and the player is docked to a station. It gets fired at game startup, upon docking, and after a docking report or previous mission screen has ended. (world script only)

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

This handler works a bit different as other handlers. It fires for every installed oxp, until an oxp creates a mission screen during this handler. Than it stops. When the mission screen ends and there is no callback function that created a new mission screen, than the missionScreenOpportunity is send again to all installed oxps, starting with the oxp that used the mission screen as last one. All this means that when this handler fires, it is safe to show a mission screen and no further test are needed.

`reportScreenEnded`

The reportScreenEnded handler is called when the last arrival-report screen ends. This is a screen that should not be written by a missionscreen. The code should wait until this eventhandler fires. Note that an other script may have put up a new missionscreen in the meantime. (world script only)

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

`shipCollided`

The shipCollided handler is send after a collision with otherShip.

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

`shipSpawned`

The shipSpawned handler is called after an NPC ship has been added to the system. After a witchspace jump it means that first all ships are added to the system, then all the relevant shipSpawned events are triggered.
This handler for the woldScript is new since Oolite 1.74. After the event is sent to the shipScript, it is now also send to the worldScript with the added entity as argument.

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

`shipLaunchedEscapePod`

The shipLaunchedEscapePod handler is called when the player bails out. This will be followed by a shipWillDockWithStation()/shipDockedWithStation() pair after a few seconds.

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

`viewDirectionChanged`

The viewDirectionChanged handler is called when the player view changes, with a string to indicate which view the player is facing. Amongst its possible values are "VIEW_FORWARD", "VIEW_AFT", "VIEW_PORT", "VIEW_STARBOARD", "VIEW_CUSTOM", "VIEW_GUI_DISPLAY".

this.viewDirectionChanged = function(viewString)
{
  if (viewString == "VIEW_PORT")
  {
     // Your code here
  }
}

Defunct

`tickle` (removed in 1.77)

The tickle handler is called periodically-ish, whenever the old plist scripts are updated. tickle() is deprecated. In new code, use appropriate event handlers or timers instead.

Missing Events

All the initially planned events have been implemented in 1.74.

If there are other events you would like to be able to respond to, please write a request on the forum.

See also: ship_script_event_handlers

Oolite JavaScript Reference: World script event handlers

Contents

Game State

startUp

playerWillSaveGame

Docking

shipWillDockWithStation

shipDockedWithStation

shipWillLaunchFromStation

shipLaunchedFromStation

playerStartedAutoPilot

playerCancelledAutoPilot

playerDockingRefused

playerRequestedDockingClearance

Witchspace Jumps

playerStartedJumpCountdown

playerCancelledJumpCountdown

playerJumpFailed

shipWillEnterWitchspace

shipWillExitWitchspace

shipExitedWitchspace

playerEnteredNewGalaxy

Enter/Exit Aegis

shipEnteredStationAegis

shipExitedStationAegis

shipEnteredPlanetaryVicinity

shipExitedPlanetaryVicinity

shipApproachingPlanetSurface

shipLeavingPlanetSurface

Combat

alertConditionChanged

playerTargetedMissile

shipAttackedOther

shipAttackedWithMissile

shipBeingAttacked

shipBeingAttackedByCloaked

shipKilledOther

shipTargetDestroyed

shipDied

shipFiredMissile

shipTargetLost

shipTargetCloaked

Equipment and Cargo

equipmentDestroyed

equipmentDamaged

equipmentRepaired

playerBoughtCargo

playerBoughtEquipment

playerBoughtNewShip

playerSoldCargo

shipScoopedFuel

shipScoopedOther

Other

compassTargetChanged

dayChanged

guiScreenChanged

guiScreenWillChange

missionChoiceWasReset

missionScreenEnded

missionScreenOpportunity

reportScreenEnded

shipCollided

shipSpawned

shipLaunchedEscapePod

viewDirectionChanged

Defunct

tickle (removed in 1.77)

Missing Events

Navigation menu

Search

`startUp`

`playerWillSaveGame`

`shipWillDockWithStation`

`shipDockedWithStation`

`shipWillLaunchFromStation`

`shipLaunchedFromStation`

`playerStartedAutoPilot`

`playerCancelledAutoPilot`

`playerDockingRefused`

`playerRequestedDockingClearance`

`playerStartedJumpCountdown`

`playerCancelledJumpCountdown`

`playerJumpFailed`

`shipWillEnterWitchspace`

`shipWillExitWitchspace`

`shipExitedWitchspace`

`playerEnteredNewGalaxy`

`shipEnteredStationAegis`

`shipExitedStationAegis`

`shipEnteredPlanetaryVicinity`

`shipExitedPlanetaryVicinity`

`shipApproachingPlanetSurface`

`shipLeavingPlanetSurface`

`alertConditionChanged`

`playerTargetedMissile`

`shipAttackedOther`

`shipAttackedWithMissile`

`shipBeingAttacked`

`shipBeingAttackedByCloaked`

`shipKilledOther`

`shipTargetDestroyed`

`shipDied`

`shipFiredMissile`

`shipTargetLost`

`shipTargetCloaked`

`equipmentDestroyed`

`equipmentDamaged`

`equipmentRepaired`

`playerBoughtCargo`

`playerBoughtEquipment`

`playerBoughtNewShip`

`playerSoldCargo`

`shipScoopedFuel`

`shipScoopedOther`

`compassTargetChanged`

`dayChanged`

`guiScreenChanged`

`guiScreenWillChange`

`missionChoiceWasReset`

`missionScreenEnded`

`missionScreenOpportunity`

`reportScreenEnded`

`shipCollided`

`shipSpawned`

`shipLaunchedEscapePod`

`viewDirectionChanged`

`tickle` (removed in 1.77)