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.
In Oolite 1.79 onwards, each ship has two scripts: the "ship script" as in previous versions (ship.script
) and an AI script (ship.AIScript
) which manages Javascript-based AI. The former is intended for constant events related to the ship itself, and the latter is intended for event handling which varies based on what the ship is currently doing. Both scripts receive all events which do not expect a return value. Events expecting a return value are sent to the ship script only.
Contents
- 1 Docking
- 2 Witchspace Jumps
- 3 Enter/Exit Aegis
- 4 Combat
- 4.1 cascadeWeaponDetected
- 4.2 defenseTargetDestroyed
- 4.3 escortAttack
- 4.4 helpRequestReceived
- 4.5 shipAttackedOther
- 4.6 shipAttackedWithMissile
- 4.7 shipAttackerDistracted
- 4.8 shipBeingAttacked
- 4.9 shipBeingAttackedByCloaked
- 4.10 shipBeingAttackedUnsuccessfully
- 4.11 shipCloakActivated
- 4.12 shipCloakDeactivated
- 4.13 shipTargetDestroyed
- 4.14 shipDied
- 4.15 shipEnergyBecameFull
- 4.16 shipEnergyIsLow
- 4.17 shipHitByECM
- 4.18 shipFiredMissile
- 4.19 shipKilledOther
- 4.20 shipTargetAcquired
- 4.21 shipTargetCloaked
- 4.22 shipTargetLost
- 4.23 shipTakingDamage
- 5 Miscellaneous
- 5.1 cargoDumpedNearby
- 5.2 commsMessageReceived
- 5.3 distressMessageReceived
- 5.4 equipmentAdded
- 5.5 equipmentRemoved
- 5.6 shipAchievedDesiredRange
- 5.7 shipAIFrustrated
- 5.8 shipBountyChanged
- 5.9 shipCloseContact
- 5.10 shipCollided
- 5.11 shipNowFacingDestination
- 5.12 shipReachedEndPoint
- 5.13 shipReachedNavPoint
- 5.14 shipScoopedOther
- 5.15 shipLaunchedEscapePod
- 6 NPC only
- 6.1 aiAwoken
- 6.2 aiStarted
- 6.3 coordinatesForEscortPosition
- 6.4 entityDestroyed
- 6.5 escortAccepted
- 6.6 escortDock
- 6.7 escortRejected
- 6.8 offenceCommittedNearby
- 6.9 scriptedAI
- 6.10 shipAcceptedEscort
- 6.11 shipLandedOnPlanet
- 6.12 shipRemoved
- 6.13 shipSpawned
- 6.14 spawnedAsEscort
- 6.15 shipWasDumped
- 6.16 shipWasScooped
- 7 Stations only
- 8 Docks Only
- 9 Missing Events
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 }
shipAttackerDistracted
The shipAttackerDistracted
handler is called when the ship's current attacker is distracted by another ship. whom
contains the ship which is doing the distracting.
this.shipAttackerDistracted = function(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 }
equipmentAdded
This method was added in Oolite test release 1.81.
The equipmentAdded
handler is called whenever a ship gains an item of equipment. This includes "gaining" of EQ_SOMETHING_DAMAGED
when an EQ_SOMETHING
is damaged. This event will fire regardless of the reason for the equipment being added to the ship.
this.equipmentAdded = function(equipmentKey) { // Your code here }
equipmentRemoved
This method was added in Oolite test release 1.81.
The equipmentRemoved
handler is called whenever a ship loses an item of equipment. This includes "losing" of EQ_SOMETHING_DAMAGED
when an EQ_SOMETHING
is repaired This event will fire regardless of the reason for the equipment being removed from the ship.
this.equipmentAdded = function(equipmentKey) { // 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 }
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
aiAwoken
This method was added in Oolite test release 1.79.
This is sent to the ship periodically when ship.AIScriptWakeTime
passes. One of the actions of this handler should be to cause a new wake time to be set. It is received by both the ship script and the AI script but usually only of interest to the latter.
aiStarted
This method was added in Oolite test release 1.79. This is sent to the ship when a new Javascript-based AI is loaded. The AI Script should then use it to do initialisation. The ship script can usually ignore it.
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. Note that this is not called for subentities - if subentities need specific set up running, this must be called from the main ship's handler.
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 }
shipWasDumped
The shipWasDumped
handler is sent to the cargopod when a ship jettisons it. The dumping ship is transferred as the argument.
this.shipWasScooped = function(dumper) { // 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
.
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 }
stationAcceptedDockingRequest
This method was added in Oolite test release 1.81.
The stationReceivedDockingRequest
handler is called when a ship has requested docking clearance and has been allocated a dock. Due to the way in which docking clearance works, this is likely to be called several times for the same ship as it moves through the docking sequence.
this.stationReceivedDockingRequest = function(whom) { // Your code here }
stationReceivedDockingRequest
This method was added in Oolite test release 1.81.
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. Due to the way in which docking clearance works, this is likely to be called several times for the same ship as it moves through the docking sequence.
this.stationReceivedDockingRequest = function(whom) { // Your code here }
(note: a handler by this name was present in 1.79 and 1.80, but was called at the wrong time and should not be used. Set a minimum version of 1.81 if you use this event handler)
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