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)
Contents
- 1 Docking
- 2 Witchspace Jumps
- 3 Enter/Exit Aegis
- 4 Combat
- 4.1 alertConditionChanged
- 4.2 escortAttack
- 4.3 playerTargetedMissile
- 4.4 shipAttackedWithMissile
- 4.5 shipBeingAttacked
- 4.6 shipBeingAttackedByCloaked
- 4.7 shipCloakActivated
- 4.8 shipCloakDeactivated
- 4.9 shipDestroyedTarget
- 4.10 shipDied
- 4.11 shipEnergyBecameFull
- 4.12 shipEnergyIsLow
- 4.13 shipFiredMissile
- 4.14 shipLostTarget
- 4.15 shipTargetAcquired
- 4.16 shipTargetCloaked
- 5 NPC only
- 6 Stations only
- 7 Not Yet Implemented
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 the player’s alert status (player.alertCondition
) changes. Only the player and stations have an alert condition.
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.
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.
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 }
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 }
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 player bails out. This will be followed by a shipWillDockWithStation()
/shipDockedWithStation()
pair after a few seconds.
this.shipLaunchedEscapePod = function(escapepod) { // 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 }
Not Yet Implemented
All initially planned events will as of v1.74 have a corresponding event handler.
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