Oolite JavaScript Reference: Ship script event handlers

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

Ship scripts are linked to Oolite either using the appropriate shipdata.plist setting or via javascript using ship.setScript and are only active when the ship is present. More than one ship can be assigned the same ship script. Each ship will create its own separate copy of the script, each one independent from the others.

(this page has just recently been split from world script event handlers, bear with us while we tidy up the content)

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 == nil", "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.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. (world script only)

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

shipLaunchedFromStation

The shipLaunchedFromStation handler is called at the end of the launch tunnel effect. (The station parameter is added at release 1.73)

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

Witchspace Jumps

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 recommended time to set up elements which need to be present in-system when the player arrives.

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.

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 a station's alert status (Station.alertCondition) changes. Only the player and stations have an alert condition. The equivalent player event is handled inside world scripts.

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

escortAttack

The escortAttack handler is sent to all escorts of a mothership that are deployed. The mother first changes the escorts AI to interceptAI.plist and also sets the escort target to his own target before sending this handler to the escorts.

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

playerTargetedMissile

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

Deprecated in 1.74 in favour of the more generic shipTargetAcquired

this.playerTargetedMissile = function(missile)
{
     // 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. There is no parameter provided to identify the cloaked ship.

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

shipCloakActivated

The shipCloakActivated handler is called whenever the script's target ship activates its cloaking device. No parameters are required for this handler (added in test version 1.74).

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

shipCloakDeactivated

The shipCloakDeactivated handler is called whenever the script's target ship deactivates its cloaking device. No parameters are required for this handler (added in test version 1.74).

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

shipDestroyedTarget

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

this.shipDestroyedTarget = 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)

shipEnergyBecameFull

The shipEnergyBecameFull handler is called when the energy level reaches it's maximum value again.

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

shipEnergyIsLow

The shipEnergyIsLow handler is called every time when a ship gets energy damage while the energy level lies below 25% of it's maximum value.

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

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. (Handler added in test version 1.74)

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

shipLostTarget

The shipLostTarget handler is called when the target gets lost. target contains the lost target entity.
(As with Oolite 1.71 this is not yet working properly. It returns not the right target but just "unknown". It does nothing when a target is lost because of "out of range")

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

shipTargetAcquired

The shipTargetAcquired handler is called whenever a new target is selected. (Handler added in test version 1.74)

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

shipTargetCloaked

The shipTargetCloaked handler is called when the target cloakes.

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

Miscellaneous

commsMessageReceived

The commsMessageReceived handler is send when receiving a message from other ships. Handler is added in Oolite 1.75

commsMessageReceived = function(message: string, sender: ship)
{
     // Your code here
}

The message contains always two lines (as seen on screen for the player). The first line is the displayName of the sending ship, terminated with a colon and a return symbol and a space. The second line is the message itself. In JS this can easy be split again with:

var messages = message.split(":\n ");

This will put the displayName in "messages[0]" and the pure message in "messages[1]".

shipCollided

The shipCollided handler is send after a collision with otherShip.

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

shipScoopedOther

The shipScoopedOther handler is called when a ship scoops scripted_cargo. ("cargo_type" = CARGO_SCRIPTED_ITEM) Other cargo, even scooping escapepods, doesn't trigger a handler.
The scooped item is transferred as argument. The scooped cargo itselfs gets the handler: shipWasScooped with the scooper as argument.

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

shipLaunchedEscapePod

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

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

NPC only

escortAccepted

The escortAccepted handler is called for mother ships that have accepted an escort. The escort simultaneously gets a shipAcceptedEscort event.

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

escortDock

The escortDock handler is called by a mother ships that uses the AI command: dockEscorts. Escorts are instructed to change AI into dockingAI.plist and enter the ABORT state of this AI after a certain delay. Than this event is send to all his escorts, each with a different delay with 3 seconds spacing.

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

offenceCommittedNearby

The offenceCommittedNearby handler is only send to police ships in scanner range of a hostile action. It transfers the attacker and the victim to the police vessel.

this.offenceCommittedNearby = function(attacker, victim)
{
     // Your code here
}

playerWillEnterWitchspace

The playerWillEnterWitchspace handler is called just before a witchspace jump starts and after the shipWillEnterWitchspace handler fires. It is send to all ships in the system to signal that the player is about to leave the system. (By jump or by wormhole)

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

shipAcceptedEscort

The shipAcceptedEscort handler is called for ships that are accepted as escort. The mother simultaneously gets a escortAccepted event.

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

shipExitedWormhole

The shipExitedWormhole handler is called when a ship exits a wormhole.

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

shipSpawned

The shipSpawned handler is called for newly added ships. It does not trigger on adding but on the first update after adding. On a witchspace jump it means that first all ships are added to the system, then afterwards all the shipSpawned() events are triggered.

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

shipWillEnterWormhole

The shipWillEnterWormhole handler is called when a ship enters a wormhole. only)

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

spawnedAsEscort

The spawnedAsEscort handler is called for newly added escort ships. It does trigger on adding the ship and before the shipSpawned() handlers is activated. It has the mothership as argument.

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

shipWasScooped

The shipWasScooped handler is send to the cargopod when a ship scoops scripted_cargo. ("cargo_type" = CARGO_SCRIPTED_ITEM) The scooper is transferred as argument. The scooper itself gets a trigger on the handler shipScoopedOther. (ship script only)

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

Stations only

otherShipDocked

The otherShipDocked handler is called with a station script only, when an ship docks. It has the docked ship as argument.

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

stationLaunchedShip

The stationLaunchedShip handler is called with a station script only, when a ship launches. It has the launched ship as argument.
Starting with 1.74 is also triggers for player.ship launches.

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

Missing Events

All initially planned events have a corresponding event handler in v1.74.

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

See also: world_script_event_handlers