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.

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.

Note that a ship script event which affects the player ship (therefore not those marked NPC only, station only, etc.) will also appear as a world script event.

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

This handler was added for npc ships with test release 1.75, before it was a worldScript only handler.

The shipWillLaunchFromStation handler is called for ship scripts on ship creation, before the shipSpawned event.

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

shipLaunchedFromStation

The shipLaunchedFromStation handler is called at the end of the launch tract, when the ship has clearly left the station and AI updating begins.

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

stationWithdrewDockingClearance

This method was added in Oolite test release 1.79. The stationWithdrewDockingClearance handler is received when the station the ship is trying to dock with unexpectedly withdraws clearance (e.g. if station.abortAllDockings is called).

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

Witchspace Jumps

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
}

shipExitedWormhole

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

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

shipWillEnterWormhole

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

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

shipWitchspaceBlocked

This method was added in Oolite test release 1.79.

The shipWitchspaceBlocked handler is called when a ship is prevented from entering witchspace by the presence of a nearby large mass. The blocking object is passed as a parameter

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

wormholeSuggested

This method was added in Oolite test release 1.79.

The wormholeSuggested handler is called when another ship enters witchspace and suggests that this ship follows. The wormhole used is passed as a parameter. This is most commonly called when a group leader enters witchspace and wishes to take its escorts with it.

this.wormholeSuggested = function(wormhole)
{
     // 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

cascadeWeaponDetected

This method was added in Oolite test release 1.77.

The cascadeWeaponDetected handler fires when a Q-bomb (or equivalent device) detonates within scanner range of the player. The stock Q-mine (and potentially OXP equivalents) will also send this handler at the start of the countdown, giving ships more time to react. The weapon entity will be passed as a parameter.

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

defenseTargetDestroyed

This method was added in Oolite test release 1.79. The defenseTargetDestroyed handler is sent when a defense (i.e. secondary) target is destroyed. A reference to the destroyed ship (which will become invalid shortly) is passed as a parameter.

this.defenseTargetDestroyed = function(target)
{
     // 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
}

helpRequestReceived

This method was added in Oolite test release 1.79.

The helpRequestReceived handler is sent when an ally of this ship is being attacked and requires help. There are two parameters, the ally and the enemy.

this.helpRequestReceived = function(ally, enemy)
{
     // Your code here
}

shipAttackedOther

The shipAttackedOther handler is called when this ship hits another with a laser shot. other is the identity of the ship being hit (added in test version 1.74.2).

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. There is no parameter provided to identify the cloaked ship.

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

shipBeingAttackedUnsuccessfully

This method was added in Oolite test release 1.77.

The shipBeingAttackedUnsuccessfully handler is called when a laser shot narrowly misses the ship, when fired by an uncloaked ship intending to hit. whom the identity of the ship that attacked.

this.shipBeingAttackedUnsuccessfully = function(whom)
{
     // 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
 }

shipTargetDestroyed

The shipTargetDestroyed handler is called when the target gets destroyed by this ship. 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.

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 its 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 its maximum value.

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

shipHitByECM

The shipHitByECM handler is called when a ship receives a ECM pulse. pulsesRemaining contains the number of pulses that still have to be send by the sending ship. When a ship activates his ecm, he will send 4 pulses with 0.5 seconds interval and increasing range.: 6400 --> 12800 --> 19200 --> 25600. (Handler added in test version 1.71)

this.shipHitByECM = function(pulsesRemaining)
{
     // 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
}

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
}

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
}

shipTargetLost

The shipTargetLost handler is called when the target gets lost. target contains the lost target entity.
(Handler introduced in 1.74 as replacement with consistent name for the old handler: 'shipLostTarget'.)

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

shipTakingDamage

The shipTakingDamage handler is called when a ship sustains damage. Handler is added in Oolite 1.75
It transfers the amount of damage, who caused the damage and the type of damage.

For the player ship, only damage not absorbed by the shields will appear in amount, but the handler will be called anyway with zero as the amount if the shields absorb all the damage.

this.shipTakingDamage = function(amount, whom, type)
{
     // Your code here
}

Miscellaneous

cargoDumpedNearby

This method was added in Oolite test release 1.79. The cargoDumpedNearby handler is sent when a nearby ship dumps a cargo pod.

this.cargoDumpedNearby = function(cargo: ship, releasedBy: ship)
{
     // Your code here
}

commsMessageReceived

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

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

distressMessageReceived

The distressMessageReceived handler is sent when receiving a distress message from other ships. Handler is added in Oolite 1.75

this.distressMessageReceived = function(aggressor: ship, sender: ship)
{
     // Your code here
}

shipAchievedDesiredRange

This method was added in Oolite test release 1.79. The shipAchievedDesiredRange handler is called when the ship reaches the desired range from its destination during certain flight behaviours.

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

shipAIFrustrated

This method was added in Oolite test release 1.79. The shipAIFrustrated handler is called when the ship's low-level behaviour is unable to achieve the desired result (e.g. a performFlee request is not getting further from the target). A short string describing the context of the frustration is passed as a parameter.

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

shipBountyChanged

This method was added in Oolite test release 1.77.

The shipBountyChanged handler is sent when an event tries to change the bounty level of the ship. delta may be zero, positive or negative. reason is a string that may either contain a standard value or a custom value set by an OXP. The standard values are:

• setup actions: Bounty level settings in the system populator or as a side effect of launching a ship from a station with a particular role.
• scripted: OXP scripted changes to bounties, with no specified cause.
• attacked police: The ship attacked a police ship
• attacked main station: The ship attacked the main station
• attacked innocent: The ship attacked a Clean ship and was seen doing so
• seen by police: The ship was seen by police committing a crime
• distress call: A police ship responded to a distress call from a ship that this ship is attacking
• illegal exports: The ship launched from a main station while carrying illegal goods (player only)
• assisting offenders: The bounty adjustment applied when a clean ship escorts an offender, or vice versa (NPC only)
• new galaxy: The ship entered a new galaxy (player only)
• new system: The ship entered a new system
• paid fine: The ship was marked for fines by police, and then paid them on docking (player only)
• escape pod: The ship is a replacement ship from escape pod insurance (player only)
• assisting police: The ship helped out a police ship in combat
• unknown: The bounty changed for an unknown reason. This should not occur.

this.shipBountyChanged = function(delta,reason)
{
     // Your code here
}

shipCloseContact

The shipCloseContact handler is sent when approaching otherShip and when "track_contacts" in shipData is true.

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

shipCollided

The shipCollided handler is sent after a collision with otherShip.

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

shipNowFacingDestination

This method was added in Oolite test release 1.79. The shipNowFacingDestination handler is called when the ship is facing its destination during certain flight behaviours.

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

shipReachedEndPoint

The shipReachedEndPoint handler is sent after reaching the last navigation point when in mode performFlyRacepoints.

shipReachedEndPoint = function()
{
     // Your code here
}

shipReachedNavPoint

The shipReachedNavPoint handler is sent after reaching a navigation point when in mode performFlyRacepoints.

this.shipReachedNavPoint = function()
{
     // 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. Starting with Oolite 1.77 this handler will fire on every scooped object.

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, passengers)
{
     // Your code here
}

escapepod contains the main pod with the pilot. passengers will be added with Oolite 1.77 and is an array with passenger pods for those ships that have more than one escape-capsule defined.

NPC only

coordinatesForEscortPosition

The coordinatesForEscortPosition handler fires whenever the game engine wishes to know the positions of escorts relative to their group leader, and fires in the group leader's ship script at that time. It is given two parameters: the number of the escort, and the maximum number of escorts the group leader might have (which is not necessarily the number of escorts it currently has, of course). Unlike most ship script handlers, which return void, this handler is required to return a Vector (or a value equivalent to a Vector) describing the relative position of the escort to the mothership.

coordinatesForEscortPosition = function(num,max)
{
   // Your code here
   return escort_position;
}

The escort position is relative to the mothership, and in the mothership's coordinate system. For example, to place an escort 500m to the right of the mothership, return new Vector(500, 0, 0);. You are responsible for ensuring that there is sufficient space between the escorts and the mothership, and between any pair of escorts, or they will spend most of their time trying to avoid collisions with each other. If you intend to use the same ship script on several ships of varying sizes, you may wish to include the mothership's collisionRadius in the calculations.

Placing escorts directly ahead of the mothership (e.g. new Vector(0, 0, 500);) or too close to the mothership will trigger collision warnings for the mothership, making it difficult to maintain level flight for any significant time.

entityDestroyed

The entityDestroyed handler fires immediately after the ship becomes invalid, regardless of the reason, except when the game restarts. This is the best place for all kind of 'clean-up' code, for example stopping Timers associated with the ship script. (Added with Oolite 1.75.1)

entityDestroyed = function()
{
     // Your code here
}

escortAccepted

The escortAccepted handler is called when a mother ship accepts this ship as an escort. The mothership simultaneously gets a shipAcceptedEscort event.

this.escortAccepted = function(mothership)
{
     // 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
}

escortRejected

This method was added in Oolite test release 1.79. The escortRejected handler is called when a mother ship rejects this ship as an escort.

this.escortRejected = function(mothership)
{
     // 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
}

scriptedAI

This method was added in Oolite test release 1.77.

The scriptedAI handler is called each frame while the ship's AI is in "performScriptedAI" or "performScriptedAttackAI" mode. It must return an object defining the ship's flight parameters. The delta parameter is the length of the current frame in seconds. More information on using this functionality

this.scriptedAI = function(delta)
{
  // Your code here
  return flightParameters;
}

shipAcceptedEscort

The shipAcceptedEscort handler is called when this ship accepts a new ship as an escort. The escort simultaneously gets a escortAccepted event.

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

shipLandedOnPlanet

The shipLandedOnPlanet handler is called for ships landing on a planet. It transfers the planet parameter. (Will be added with Oolite 1.77)

shipLandedOnPlanet = function(planet)
{
     // Your code here
}

shipRemoved

The shipRemoved handler is called for ships removed by script. It transfers the suppressDeathEvent parameter so the script knows if there will also follow a shipDied() event.

shipRemoved = function(suppressDeathEvent)
{
     // 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
}

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

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
}

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
}

stationDockingQueuesAreEmpty

This method was added in Oolite test release 1.79. The stationDockingQueuesAreEmpty handler is called when the last ship in the queues docks with the station (or gives up docking and leaves).

this.stationDockingQueuesAreEmpty = function()
{
     // 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.

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

stationReceivedDockingRequest

This method was added in Oolite test release 1.79. The stationReceivedDockingRequest handler is called when a ship requests docking clearance. The ship requesting is passed as a parameter. This is often necessary for carriers which will need to come to a stop before ships can dock with them.

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

willOpenDockingPortFor

This method was added in Oolite test release 1.77.

The willOpenDockingPortFor handler is called with a station script only, when a ship requests docking, in cases where a dock is set to generally disallow docking (i.e. allowsDocking is false). It returns a Boolean:

• if it returns false (or this function isn't defined), this dock will not be opened later for the requesting ship, and it should not try again.
• if it returns true, this dock will be opened later for the requesting ship, and it should try again later if it cannot find another suitable dock on this station.

The handler is passed the identity of the dock and the requesting ship

this.willOpenDockingPortFor = function(dock, ship)
{
     // Your code here
     return allow;
}

Docks Only

This method was added in Oolite test release 1.77.

acceptDockingRequestFrom

This method was added in Oolite test release 1.77.

The acceptDockingRequestFrom handler is called when a ship is looking for docking clearance from the station, and is considering this dock. To get as far as calling this handler, the dock must have allowsDocking true, and be large enough to physically fit the ship.

It returns a boolean: true to accept the request (which, depending on docking queue lengths will not necessarily mean that this dock is the one that the ship heads for), and false to reject the request. 'true' is assumed if this handler is not defined.

This handler may be called multiple times for the same ship if the ship is having difficulty finding a suitable docking queue.

this.acceptDockingRequestFrom = function(ship)
{
     // Your code here
     return allow;
}

acceptLaunchingRequestFrom

This method was added in Oolite test release 1.77.

The acceptLaunchingRequestFrom handler is called when a ship is looking for launching clearance from the station, and is considering this dock. To get as far as calling this handler, the dock must have allowsLaunching true, and be large enough to physically fit the ship (unless the ship is the player).

It returns a boolean: true to accept the request (which, depending on launching queue lengths will not necessarily mean that this dock is the one that the ship uses), and false to reject the request. 'true' is assumed if this handler is not defined.

this.acceptLaunchingRequestFrom = function(ship)
{
     // Your code here
     return allow;
}

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