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.

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

This method was added in Oolite test release 1.74.2.

The shipAttackedOther handler is called when this ship 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
}

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

This method was added in Oolite test release 1.74.

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

This method was added in Oolite test release 1.74.

The shipCloakDeactivated handler is called whenever the script's target ship deactivates its cloaking device. No parameters are required for this handler.

 this.shipCloakDeactivated = 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

This method was added in Oolite test release 1.71.

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.

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

shipFiredMissile

This method was added in Oolite test release 1.74.

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
}

shipKilledOther

This method was added in Oolite test release 1.75.

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.

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

shipReleasedEquipment

The shipReleasedEquipment handler is called when a ship launches a mine (a pylon-mounted equipment item whose key ends with "_MINE"). mine contains the launched mine entity.

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

shipTargetAcquired

This method was added in Oolite test release 1.74.

The shipTargetAcquired handler is called whenever a new target is selected.

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

shipTargetCloaked

The shipTargetCloaked handler is called when the target cloakes.

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

shipTargetLost

This method was added in Oolite test release 1.74.

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

This method was added in Oolite test release 1.75.

The shipTakingDamage handler is called when a ship sustains damage.
It transfers the amount of damage, who caused the damage and a string indicating the type of damage:

• "scrape damage" (collisions with other entities, who will be other entity involved)
• "heat damage" (see Shipdata.plist#heat_insulation for more information about this, who will be nil in this case)
• "energy damage" (default / catch-all including weapons damage and missile detonations, who will be nil if the entity causing the damage is cloaked, and if the damage is caused by a missile then who will be the entity that launched the missile, if it is damage from a direct laser or from a sub-entity weapon, who will be the ship or station mounting the weapon, etc.)
• "cascade weapon" (caught in Quirium Cascade Mine effect, who will be the entity that launched the weapon)
• "hit a planet"
• "hit a sun"
• "removed" (corresponds to the Ship.remove() method, regardless of the suppressDeathEvent parameter)

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 - not this ship - dumps a cargo pod.

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

commsMessageReceived

This method was added in Oolite test release 1.75.

The commsMessageReceived handler is sent when receiving a message from other ships.

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

distressMessageReceived

This method was added in Oolite test release 1.75.

The distressMessageReceived handler is sent when receiving a distress message from other ships.

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.equipmentRemoved = 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
}

Frustration itself was added to the Vanilla game code on or before 23rd January 2006. It appears quite a lot in the ShipEntity.m & ShipEntityAI.m files in the Vanilla game code. There seems to be no documentation about it (lost in the Great Deletion?).

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
}

shipDumpedCargo

This method was added in Oolite test release 1.83.

The shipDumpedCargo handler is sent when this ship dumps a cargo pod.

this.shipDumpedCargo = function(cargo: ship)
{
     // 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

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

This method was added in Oolite test release 1.75.1.

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.

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

This method was added in Oolite test release 1.77.

The shipLandedOnPlanet handler is called for ships landing on a planet. It transfers the planet parameter.

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.shipWasDumped = 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 stationAcceptedDockingRequest 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.stationAcceptedDockingRequest = 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 handler 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) or 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) or 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

---

Links

• distant effects of a ship's mass or energy? - analysis of collisions at vast distance back in 2007.