Difference between revisions of "Oolite JavaScript Reference: Ship script event handlers"
(→defenseTargetDestroyed) |
Cholmondely (talk | contribs) (→shipAIFrustrated: Added note on "Frustration") |
||
(17 intermediate revisions by 5 users not shown) | |||
Line 7: | Line 7: | ||
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 [[Oolite JavaScript Reference: World script event handlers|world script event]]. | 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 [[Oolite JavaScript Reference: World script event handlers|world script event]]. | ||
− | In Oolite 1.79 onwards, each ship has two scripts: the "ship script" as in previous versions (<code>ship.script</code>) and an AI script (<code>ship.AIScript</code>) which manages [[Oolite Javascript | + | In Oolite 1.79 onwards, each ship has two scripts: the "ship script" as in previous versions (<code>ship.script</code>) and an AI script (<code>ship.AIScript</code>) which manages [[Oolite Javascript Reference: PriorityAI Documentation|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 === | === Docking === | ||
Line 53: | Line 53: | ||
==== <code>stationWithdrewDockingClearance</code> ==== | ==== <code>stationWithdrewDockingClearance</code> ==== | ||
− | {{oolite-method-added|1.79}} | + | {{oolite-method-added|1.79}} |
+ | |||
The <code>stationWithdrewDockingClearance</code> handler is received when the station the ship is trying to dock with unexpectedly withdraws clearance (e.g. if <code>station.abortAllDockings</code> is called). | The <code>stationWithdrewDockingClearance</code> handler is received when the station the ship is trying to dock with unexpectedly withdraws clearance (e.g. if <code>station.abortAllDockings</code> is called). | ||
Line 92: | Line 93: | ||
==== <code>shipWitchspaceBlocked</code> ==== | ==== <code>shipWitchspaceBlocked</code> ==== | ||
− | {{oolite-method-added|1.79}} | + | {{oolite-method-added|1.79}} |
+ | |||
The <code>shipWitchspaceBlocked</code> 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 | The <code>shipWitchspaceBlocked</code> 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 | ||
Line 208: | Line 210: | ||
==== <code>shipAttackedOther</code> ==== | ==== <code>shipAttackedOther</code> ==== | ||
− | The <code>shipAttackedOther</code> handler is called when this ship hits another with a laser shot. <code>other</code> is the identity of the ship being hit | + | {{oolite-method-added|1.74.2}} |
+ | |||
+ | The <code>shipAttackedOther</code> handler is called when this ship hits another with a laser shot. <code>other</code> is the identity of the ship being hit. | ||
this.shipAttackedOther = function(other) | this.shipAttackedOther = function(other) | ||
Line 262: | Line 266: | ||
==== <code>shipCloakActivated</code> ==== | ==== <code>shipCloakActivated</code> ==== | ||
+ | {{oolite-method-added|1.74}} | ||
− | The <code>shipCloakActivated</code> handler is called whenever the script's target ship activates its cloaking device. No parameters are required for this handler | + | The <code>shipCloakActivated</code> handler is called whenever the script's target ship activates its cloaking device. No parameters are required for this handler. |
this.shipCloakActivated = function() | this.shipCloakActivated = function() | ||
Line 271: | Line 276: | ||
==== <code>shipCloakDeactivated</code> ==== | ==== <code>shipCloakDeactivated</code> ==== | ||
+ | {{oolite-method-added|1.74}} | ||
− | The <code>shipCloakDeactivated</code> handler is called whenever the script's target ship deactivates its cloaking device. No parameters are required for this handler | + | The <code>shipCloakDeactivated</code> handler is called whenever the script's target ship deactivates its cloaking device. No parameters are required for this handler. |
− | this. | + | this.shipCloakDeactivated = function() |
{ | { | ||
// Your code here | // Your code here | ||
Line 318: | Line 324: | ||
==== <code>shipHitByECM</code> ==== | ==== <code>shipHitByECM</code> ==== | ||
+ | {{oolite-method-added|1.71}} | ||
− | The <code>shipHitByECM</code> handler is called when a ship receives a ECM pulse. <code>pulsesRemaining</code> 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. | + | The <code>shipHitByECM</code> handler is called when a ship receives a ECM pulse. <code>pulsesRemaining</code> 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) | this.shipHitByECM = function(pulsesRemaining) | ||
Line 327: | Line 334: | ||
==== <code>shipFiredMissile</code> ==== | ==== <code>shipFiredMissile</code> ==== | ||
+ | {{oolite-method-added|1.74}} | ||
− | The <code>shipFiredMissile</code> handler is called when a missile is fired. <code>missile</code> contains the missile entity and <code>target</code> the identity of the target. The handler is send to the ship that launched the missile. | + | The <code>shipFiredMissile</code> handler is called when a missile is fired. <code>missile</code> contains the missile entity and <code>target</code> the identity of the target. The handler is send to the ship that launched the missile. |
this.shipFiredMissile = function(missile, target) | this.shipFiredMissile = function(missile, target) | ||
Line 336: | Line 344: | ||
==== <code>shipKilledOther</code> ==== | ==== <code>shipKilledOther</code> ==== | ||
+ | {{oolite-method-added|1.75}} | ||
− | The <code>shipKilledOther</code> handler is called when a ship kills an other ship. <code>whom</code> the identity of the ship that was killed. <code>damageType</code> is the type of damage. | + | The <code>shipKilledOther</code> handler is called when a ship kills an other ship. <code>whom</code> the identity of the ship that was killed. <code>damageType</code> is the type of damage. |
this.shipKilledOther = function(whom,damageType) | this.shipKilledOther = function(whom,damageType) | ||
Line 354: | Line 363: | ||
==== <code>shipTargetAcquired</code> ==== | ==== <code>shipTargetAcquired</code> ==== | ||
+ | {{oolite-method-added|1.74}} | ||
− | The <code>shipTargetAcquired</code> handler is called whenever a new target is selected. | + | The <code>shipTargetAcquired</code> handler is called whenever a new target is selected. |
this.shipTargetAcquired = function(target) | this.shipTargetAcquired = function(target) | ||
Line 372: | Line 382: | ||
==== <code>shipTargetLost</code> ==== | ==== <code>shipTargetLost</code> ==== | ||
+ | {{oolite-method-added|1.74}} | ||
The <code>shipTargetLost</code> handler is called when the target gets lost. <code>target</code> contains the lost target entity.<br>(Handler introduced in 1.74 as replacement with consistent name for the old handler: 'shipLostTarget'.) | The <code>shipTargetLost</code> handler is called when the target gets lost. <code>target</code> contains the lost target entity.<br>(Handler introduced in 1.74 as replacement with consistent name for the old handler: 'shipLostTarget'.) | ||
Line 381: | Line 392: | ||
==== <code>shipTakingDamage</code> ==== | ==== <code>shipTakingDamage</code> ==== | ||
+ | {{oolite-method-added|1.75}} | ||
− | The <code>shipTakingDamage</code> handler is called when a ship sustains damage. | + | The <code>shipTakingDamage</code> handler is called when a ship sustains damage.<br> |
− | It transfers the <code>amount</code> of damage, <code>who</code> caused the damage and the <code>type</code> of damage. | + | It transfers the <code>amount</code> of damage, <code>who</code> caused the damage and a string indicating the <code>type</code> of damage: |
+ | |||
+ | * "scrape damage" (collisions with other entities, <code>who</code> will be other entity involved) | ||
+ | * "heat damage" (see [[Shipdata.plist#heat_insulation]] for more information about this, <code>who</code> will be nil in this case) | ||
+ | * "energy damage" (default / catch-all including weapons damage and missile detonations, <code>who</code> will be nil if the entity causing the damage is cloaked, and if the damage is caused by a missile then <code>who</code> will be the entity that launched the missile, if it is damage from a direct laser or from a sub-entity weapon, <code>who</code> will be the ship or station mounting the weapon, etc.) | ||
+ | * "cascade weapon" (caught in Quirium Cascade Mine effect, <code>who</code> will be the entity that launched the weapon) | ||
+ | * "hit a planet" | ||
+ | * "hit a sun" | ||
+ | * "removed" (corresponds to the <code>Ship.remove()</code> method, regardless of the suppressDeathEvent parameter) | ||
For the player ship, only damage not absorbed by the shields will appear in <code>amount</code>, but the handler will be called anyway with zero as the amount if the shields absorb all the damage. | For the player ship, only damage not absorbed by the shields will appear in <code>amount</code>, but the handler will be called anyway with zero as the amount if the shields absorb all the damage. | ||
Line 396: | Line 416: | ||
==== <code>cargoDumpedNearby</code> ==== | ==== <code>cargoDumpedNearby</code> ==== | ||
{{oolite-method-added|1.79}} | {{oolite-method-added|1.79}} | ||
+ | |||
The <code>cargoDumpedNearby</code> handler is sent when a nearby ship - not this ship - dumps a cargo pod. | The <code>cargoDumpedNearby</code> handler is sent when a nearby ship - not this ship - dumps a cargo pod. | ||
Line 404: | Line 425: | ||
==== <code>commsMessageReceived</code> ==== | ==== <code>commsMessageReceived</code> ==== | ||
+ | {{oolite-method-added|1.75}} | ||
− | The <code>commsMessageReceived</code> handler is sent when receiving a message from other ships. | + | The <code>commsMessageReceived</code> handler is sent when receiving a message from other ships. |
this.commsMessageReceived = function(message: string, sender: ship) | this.commsMessageReceived = function(message: string, sender: ship) | ||
Line 413: | Line 435: | ||
==== <code>distressMessageReceived</code> ==== | ==== <code>distressMessageReceived</code> ==== | ||
+ | {{oolite-method-added|1.75}} | ||
− | The <code>distressMessageReceived</code> handler is sent when receiving a distress message from other ships. | + | The <code>distressMessageReceived</code> handler is sent when receiving a distress message from other ships. |
this.distressMessageReceived = function(aggressor: ship, sender: ship) | this.distressMessageReceived = function(aggressor: ship, sender: ship) | ||
Line 423: | Line 446: | ||
==== <code>equipmentAdded</code> ==== | ==== <code>equipmentAdded</code> ==== | ||
{{Oolite-method-added|1.81}} | {{Oolite-method-added|1.81}} | ||
+ | |||
The <code>equipmentAdded</code> handler is called whenever a ship gains an item of equipment. This includes "gaining" of <code>EQ_SOMETHING_DAMAGED</code> when an <code>EQ_SOMETHING</code> is damaged. This event will fire regardless of the reason for the equipment being added to the ship. | The <code>equipmentAdded</code> handler is called whenever a ship gains an item of equipment. This includes "gaining" of <code>EQ_SOMETHING_DAMAGED</code> when an <code>EQ_SOMETHING</code> is damaged. This event will fire regardless of the reason for the equipment being added to the ship. | ||
Line 432: | Line 456: | ||
==== <code>equipmentRemoved</code> ==== | ==== <code>equipmentRemoved</code> ==== | ||
{{Oolite-method-added|1.81}} | {{Oolite-method-added|1.81}} | ||
+ | |||
The <code>equipmentRemoved</code> handler is called whenever a ship loses an item of equipment. This includes "losing" of <code>EQ_SOMETHING_DAMAGED</code> when an <code>EQ_SOMETHING</code> is repaired This event will fire regardless of the reason for the equipment being removed from the ship. | The <code>equipmentRemoved</code> handler is called whenever a ship loses an item of equipment. This includes "losing" of <code>EQ_SOMETHING_DAMAGED</code> when an <code>EQ_SOMETHING</code> is repaired This event will fire regardless of the reason for the equipment being removed from the ship. | ||
− | this. | + | this.equipmentRemoved = function(equipmentKey) |
{ | { | ||
// Your code here | // Your code here | ||
Line 441: | Line 466: | ||
==== <code>shipAchievedDesiredRange</code> ==== | ==== <code>shipAchievedDesiredRange</code> ==== | ||
{{Oolite-method-added|1.79}} | {{Oolite-method-added|1.79}} | ||
+ | |||
The <code>shipAchievedDesiredRange</code> handler is called when the ship reaches the desired range from its destination during certain flight behaviours. | The <code>shipAchievedDesiredRange</code> handler is called when the ship reaches the desired range from its destination during certain flight behaviours. | ||
Line 450: | Line 476: | ||
==== <code>shipAIFrustrated</code> ==== | ==== <code>shipAIFrustrated</code> ==== | ||
{{Oolite-method-added|1.79}} | {{Oolite-method-added|1.79}} | ||
+ | |||
The <code>shipAIFrustrated</code> handler is called when the ship's low-level behaviour is unable to achieve the desired result (e.g. a <code>performFlee</code> request is not getting further from the target). A short string describing the context of the frustration is passed as a parameter. | The <code>shipAIFrustrated</code> handler is called when the ship's low-level behaviour is unable to achieve the desired result (e.g. a <code>performFlee</code> request is not getting further from the target). A short string describing the context of the frustration is passed as a parameter. | ||
Line 456: | Line 483: | ||
// Your code here | // 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]]?). | ||
==== <code>shipBountyChanged</code> ==== | ==== <code>shipBountyChanged</code> ==== | ||
Line 484: | Line 513: | ||
==== <code>shipCloseContact</code> ==== | ==== <code>shipCloseContact</code> ==== | ||
− | The <code>shipCloseContact</code> handler is sent when approaching otherShip and when "track_contacts" in shipData is true. | + | The <code>shipCloseContact</code> handler is sent when approaching otherShip and when "track_contacts" in shipData is <code>true</code>. |
this.shipCloseContact = function(otherShip) | this.shipCloseContact = function(otherShip) | ||
Line 512: | Line 541: | ||
==== <code>shipNowFacingDestination</code> ==== | ==== <code>shipNowFacingDestination</code> ==== | ||
{{Oolite-method-added|1.79}} | {{Oolite-method-added|1.79}} | ||
+ | |||
The <code>shipNowFacingDestination</code> handler is called when the ship is facing its destination during certain flight behaviours. | The <code>shipNowFacingDestination</code> handler is called when the ship is facing its destination during certain flight behaviours. | ||
Line 561: | Line 591: | ||
==== <code>aiAwoken</code> ==== | ==== <code>aiAwoken</code> ==== | ||
{{oolite-method-added|1.79}} | {{oolite-method-added|1.79}} | ||
+ | |||
This is sent to the ship periodically when <code>ship.AIScriptWakeTime</code> 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. | This is sent to the ship periodically when <code>ship.AIScriptWakeTime</code> 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. | ||
==== <code>aiStarted</code> ==== | ==== <code>aiStarted</code> ==== | ||
{{oolite-method-added|1.79}} | {{oolite-method-added|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. | 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. | ||
Line 582: | Line 614: | ||
==== <code>entityDestroyed</code> ==== | ==== <code>entityDestroyed</code> ==== | ||
+ | {{oolite-method-added|1.75.1}} | ||
− | The <code>entityDestroyed</code> 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 [[Oolite_JavaScript_Reference:_Timer|Timers]] associated with the ship script. | + | The <code>entityDestroyed</code> 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 [[Oolite_JavaScript_Reference:_Timer|Timers]] associated with the ship script. |
entityDestroyed = function() | entityDestroyed = function() | ||
Line 612: | Line 645: | ||
==== <code>escortRejected</code> ==== | ==== <code>escortRejected</code> ==== | ||
{{oolite-method-added|1.79}} | {{oolite-method-added|1.79}} | ||
+ | |||
The <code>escortRejected</code> handler is called when a mother ship rejects this ship as an escort. | The <code>escortRejected</code> handler is called when a mother ship rejects this ship as an escort. | ||
Line 649: | Line 683: | ||
==== <code>shipLandedOnPlanet</code> ==== | ==== <code>shipLandedOnPlanet</code> ==== | ||
+ | {{oolite-method-added|1.77}} | ||
− | The <code>shipLandedOnPlanet</code> handler is called for ships landing on a planet. It transfers the <code>planet</code> parameter. | + | The <code>shipLandedOnPlanet</code> handler is called for ships landing on a planet. It transfers the <code>planet</code> parameter. |
shipLandedOnPlanet = function(planet) | shipLandedOnPlanet = function(planet) | ||
Line 724: | Line 759: | ||
==== <code>stationDockingQueuesAreEmpty</code> ==== | ==== <code>stationDockingQueuesAreEmpty</code> ==== | ||
{{oolite-method-added|1.79}} | {{oolite-method-added|1.79}} | ||
+ | |||
The <code>stationDockingQueuesAreEmpty</code> handler is called when the last ship in the queues docks with the station (or gives up docking and leaves). | The <code>stationDockingQueuesAreEmpty</code> handler is called when the last ship in the queues docks with the station (or gives up docking and leaves). | ||
Line 742: | Line 778: | ||
==== <code>stationAcceptedDockingRequest</code> ==== | ==== <code>stationAcceptedDockingRequest</code> ==== | ||
{{oolite-method-added|1.81}} | {{oolite-method-added|1.81}} | ||
− | |||
− | this. | + | The <code>stationAcceptedDockingRequest</code> 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 | // Your code here | ||
Line 751: | Line 788: | ||
==== <code>stationReceivedDockingRequest</code> ==== | ==== <code>stationReceivedDockingRequest</code> ==== | ||
{{oolite-method-added|1.81}} | {{oolite-method-added|1.81}} | ||
+ | |||
The <code>stationReceivedDockingRequest</code> 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. | The <code>stationReceivedDockingRequest</code> 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. | ||
Line 763: | Line 801: | ||
{{oolite-method-added|1.77}} | {{oolite-method-added|1.77}} | ||
− | The <code>willOpenDockingPortFor</code> 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. [[Oolite_JavaScript_Reference:_Dock#allowsDocking|allowsDocking]] is false). It returns a | + | The <code>willOpenDockingPortFor</code> 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. [[Oolite_JavaScript_Reference:_Dock#allowsDocking|allowsDocking]] is <code>false</code>). It returns a boolean: |
− | * if it returns false (or this | + | * if it returns <code>false</code> (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. | + | * if it returns <code>true</code>, 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 | The handler is passed the identity of the dock and the requesting ship | ||
Line 780: | Line 818: | ||
{{oolite-method-added|1.77}} | {{oolite-method-added|1.77}} | ||
− | The <code>acceptDockingRequestFrom</code> 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 [[Oolite_JavaScript_Reference:_Dock#allowsDocking|allowsDocking]] true | + | The <code>acceptDockingRequestFrom</code> 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 <code>[[Oolite_JavaScript_Reference:_Dock#allowsDocking|allowsDocking]] = true</code> 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) | + | It returns a boolean: <code>true</code> 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 <code>false</code> to reject the request. <code>true</code> 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 handler may be called multiple times for the same ship if the ship is having difficulty finding a suitable docking queue. | ||
Line 795: | Line 833: | ||
{{oolite-method-added|1.77}} | {{oolite-method-added|1.77}} | ||
− | The <code>acceptLaunchingRequestFrom</code> 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 [[Oolite_JavaScript_Reference:_Dock# | + | The <code>acceptLaunchingRequestFrom</code> 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 <code>[[Oolite_JavaScript_Reference:_Dock#allowsLaunching|allowsLaunching]] = true</code> 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) | + | It returns a boolean: <code>true</code> 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 <code>false</code> to reject the request. <code>true</code> is assumed if this handler is not defined. |
this.acceptLaunchingRequestFrom = function(ship) | this.acceptLaunchingRequestFrom = function(ship) | ||
Line 804: | Line 842: | ||
return allow; | return allow; | ||
} | } | ||
− | |||
− | |||
− | |||
− | |||
=== Missing Events === | === Missing Events === | ||
Line 813: | Line 847: | ||
All initially planned events have a corresponding event handler in v1.74. | 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 [ | + | If there are other events you would like to be able to respond to, please write a request [https://bb.oolite.space/viewtopic.php?t=3296 on the forum]. |
'''See also:''' [[Oolite JavaScript Reference: World script event handlers|world script event handlers]] | '''See also:''' [[Oolite JavaScript Reference: World script event handlers|world script event handlers]] | ||
+ | |||
+ | ---- | ||
+ | == Links == | ||
+ | *[https://bb.oolite.space/viewtopic.php?f=4&t=3865 distant effects of a ship's mass or energy?] - analysis of '''collisions''' at vast distance back in 2007. | ||
[[Category:Oolite JavaScript Reference]] | [[Category:Oolite JavaScript Reference]] |
Latest revision as of 13:27, 24 July 2024
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 shipReleasedEquipment
- 4.21 shipTargetAcquired
- 4.22 shipTargetCloaked
- 4.23 shipTargetLost
- 4.24 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 shipDumpedCargo
- 5.12 shipNowFacingDestination
- 5.13 shipReachedEndPoint
- 5.14 shipReachedNavPoint
- 5.15 shipScoopedOther
- 5.16 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
- 10 Links
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 thenwho
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 }
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.
- Updated JavaScript features in Oolite 1.79
- Updated JavaScript features in Oolite 1.77
- Updated JavaScript features in Oolite 1.74.2
- Updated JavaScript features in Oolite 1.74
- Updated JavaScript features in Oolite 1.71
- Updated JavaScript features in Oolite 1.75
- Updated JavaScript features in Oolite 1.81
- Updated JavaScript features in Oolite 1.83
- Updated JavaScript features in Oolite 1.75.1
- Oolite JavaScript Reference