Multiple Docks

This page documents features planned for Oolite 1.77. These may change before release

Stations in 1.77 may have multiple dock subentities defined in their subentities list. When a ship requests to launch from or dock at the station, the following rules are applied to decide on the dock.

Launching rules

Any dock with allowLaunching false will be excluded from consideration, as will any dock too small to fit the launching ship. If the dock subentity has a ship script defining the acceptLaunchingRequestFrom handler, and this handler returns false, also exclude that dock.

Then:

• if there are docks with a docking queue of size zero, assign this ship to the dock with the smallest launching queue (tiebreak in favour of the dock defined first in the subentities list). This allows a ship with multiple docks to rapidly launch several ships at once.
• if there are no docks with a docking queue of size zero, assign this ship to the dock with the smallest docking queue, regardless of the size of its launching queue. Since docking takes much longer than launching, this ensures that all ships requested for launch at the same time will launch from the same dock, which is most likely to be the first dock to become free.

If there are no suitable docks, cancel the launch and report an error to the log except for the player's ship, which will be launched from whatever the last defined dock is.

Ships will be launched from the dock in first-in, first-out order.

If ships are waiting to be launched and allowsLaunching is set to false, the launch will be silently cancelled.

Docking rules

When docking clearance is requested, the first step - assuming the ship is not a fugitive player, and the station is not moving or rotating incompatibly with docking, is dock selection.

Dock selection

Any dock with allowDocking false will be excluded from consideration, as will any dock too small to fit the launching ship. If the dock subentity has a ship script defining the acceptDockingRequestFrom handler, and this handler returns false, also exclude that dock. Temporarily also exclude docks with pending launches.

If the player has docking clearance for manual docking, also exclude that dock from consideration for further assignment.

This can have four results:

• at least one suitable dock is found. The one with the shortest docking queue will be chosen.
• no suitable docks are found, but this condition is believed to be temporary (e.g. they have currently launching ships, or the player has manual docking clearance). The ship will be told to TRY_AGAIN_LATER.
• no suitable docks are found, and this condition is permanent (e.g. the docks are all too small for the ship, or their acceptDockingRequestFrom handler returned false). The ship will be told DOCKING_REFUSED.
• no suitable docks are found, and this condition is probably permanent - allowDocking was false for at least one dock. In this case the station handler willOpenDockingPortFor can be called for the docks. If it exists and returns true, the ship will be told TRY_AGAIN_LATER rather than DOCKING_REFUSED. (Note: this handler may be called even if another dock in the consideration will accept the ship anyway). It is then the responsibility of the station script to open the docking port (which might involve clearing objects out of the way) and setting allowDocking to true once it is complete.

If a suitable dock is found, the ship will be added to its docking queue, and proceed through the rest of the docking process.

NPCs (and player on autopilot)

NPCs will proceed through the normal docking manoeuvres with respect to the chosen dock, approximately in the order they were added to its docking queue. This is the same as for a normal dock.

If ships are waiting to be docked and allowsDocking is set to false, the ships will be told to abort the docking. They may then request docking at a different port.

Player on manual docking

The player will be informed which dock to dock with, if there are more than one, in the clearance message, which will include the dock's displayName property. If the dock_label entry is set in the subentity definition, this will override the shipdata-set display_name.

While the player is docking, no new launches and docking requests will be accepted for this dock, but they will have to wait as usual for the request to complete. Clearance timeouts work the same as before.

If the player attempts to manually dock with a dock which has allowPlayerDocking false, they will bounce off it, taking damage in the process. At low speeds this will not usually be fatal: nevertheless if such docks exist they should be clearly indicated to the player.

Tips for efficient operation

• Stations with multiple docks should consider designating at least one dock as launch-only. Since launching is much faster than docking, it is rarely necessary to designate more than that for good traffic control, but it may be good for effect to be able to launch a ship and all its escorts at once.
• If the player might wish to dock with the station, make sure all the docks have a unique label, and that the player can tell by looking which dock corresponds to which label (e.g. by painting big numbers next to them)
• Docking and launching optimally needs a 4km long cone ahead of the docking port to be clear of objects. It is therefore useful if the docks are arranged such that these cones do not overlap. (Sets of launch-only docks may be placed closer together without interfering with each other)
• Docks on a rotating station will only be used for docking if they are on and aligned with the Z axis. Launching docks are not subject to this restriction.

Stations with no dock subentities

Stations with no dock subentities will be given an invisible and undamageable dock subentity of appropriate size, which will be added to the end of their subentity list. Generally you should explicitly specify dock subentities.