Oolite JavaScript Reference: Ship script event handlers - Revision history

Cholmondely: /* distressMessageReceived */ Added note from Vanilla game code

2025-07-15T09:25:30Z

‎distressMessageReceived: Added note from Vanilla game code

Cholmondely: /* shipAIFrustrated */ Added note on "Frustration"

2024-07-24T12:27:44Z

‎shipAIFrustrated: Added note on "Frustration"

Phkb: Updating BB links

2024-02-29T02:19:19Z

Updating BB links

Timer: /* equipmentRemoved */

2023-03-02T09:00:42Z

‎equipmentRemoved

Massively Locked: /* willOpenDockingPortFor */ replaced "function"

2022-10-29T16:20:35Z

‎willOpenDockingPortFor: replaced "function"

Massively Locked: /* acceptLaunchingRequestFrom */ uniform boolean format, fixed link

2022-10-28T01:00:22Z

‎acceptLaunchingRequestFrom: uniform boolean format, fixed link

Massively Locked: /* acceptDockingRequestFrom */ uniform boolean format

2022-10-28T00:54:01Z

‎acceptDockingRequestFrom: uniform boolean format

Massively Locked: /* willOpenDockingPortFor */ uniform boolean format

2022-10-28T00:49:05Z

‎willOpenDockingPortFor: uniform boolean format

Massively Locked: /* shipCloseContact */ uniform boolean format

2022-10-28T00:43:19Z

‎shipCloseContact: uniform boolean format

Massively Locked: fix link

2022-09-30T00:17:55Z

fix link

@@ Line 437: / Line 437: @@
 {{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. Distress messages can only be "sent" to ships which have an "ACCEPT_DISTRESS_CALL" reaction in their AI.
   this.distressMessageReceived = function(aggressor: ship, sender: ship)

@@ Line 483: / Line 483: @@
        // Your code here
+  }
 ==== <code>shipBountyChanged</code> ====

@@ Line 845: / Line 845: @@
 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 [http://www.aegidian.org/bb/viewtopic.php?t=3296 on the forum].
+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]]
@@ Line 851: / Line 851: @@
 ----
 == Links ==
-*[http://www.aegidian.org/bb/viewtopic.php?f=4&t=3865 distant effects of a ship's mass or energy?] - analysis of '''collisions''' at vast distance back in 2007.
+*[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]]

@@ Line 459: / Line 459: @@
 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.equipmentAdded = function(equipmentKey)
+  this.equipmentRemoved = function(equipmentKey)
+  {
         // Your code here

@@ Line 800: / Line 800: @@
 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 <code>false</code> (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 <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 <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

@@ Line 831: / Line 831: @@
 {{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#allowsDocking|allowsLaunching]] true, and be large enough to physically fit the ship (unless the ship is the player).
+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), and false to reject the request. 'true' is assumed if this handler is not defined.
+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)
@@ Line 840: / Line 840: @@
        return allow;
+  }
 === Missing Events ===

@@ Line 816: / Line 816: @@
 {{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, and be large enough to physically fit the ship.
+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), and false to reject the request. 'true' is assumed if this handler is not defined.
+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.

@@ Line 511: / Line 511: @@
 ==== <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)

@@ 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]].
-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 AI|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''.
+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 ===