Docking Instructions

AI-Docking Instructions for Oolite ships. See the Pilot's Reference Manual for not-AI based docking or check out the docking computer.

The AI of the docking ship

Stage 1

Oolite's AI command "requestDockingCoordinates", looks for the nearest station and guides the ship to its docking port. If no station in the system exist it returns: NO_STATION_FOUND The command "recallDockingInstructions" uses the previously found station and retransmit the last instructions. Both commands are alike but the first time requestDockingCoordinates must be used. Whenever a station exists it always sends 7 parameters to the ship

1: Station ID
2: Coordinates
3: Speed
4: Desired range
5: AI message
6: commsMessage
7: rotation speed

From this only 2, 3, 4 and 5 are important for AI handling. The commsMessage is only seen if the docking ship is the player and rotation speed is automatically set in the last part of the approach.

Stage 2


In this stage no coordinates are given. The ship first checks if he is stationary himself and than if the ships are in the right distance from the station (between 1000 and 12500 meters).

If another ship is in launching status or another temporary condition preventing docking is in effect it returns: TRY_AGAIN_LATER

If the ship is too large for the docking port, or another permanent condition preventing docking is in effect it returns: DOCKING_REFUSED

If the station or carrier is moving to fast or is turning to fast with a non-rotating station it returns: HOLD_POSITION

If the ship is already to close to give accurate coordinates (<1000 meter) it returns: BACK_OFF

If the ship is still to far away to give accurate coordinates (>12500 meter) it returns: APPROACH

Stage 3

On reaching stage 3 the ship is added to the docking list. From this point on valid approach coordinates in front of the dockingport are calculated and it returns: APPROACH_COORDINATES. With the coordinates it also sets the approach speed and the desired range. Different ships get assigned positions around the station on at least 500 meters from each-other. One by one the ships are now guided to points more closely to the docking port by giving new approach parameters. In the last phase also a rotation is given on rotating stations. The AI must not set speed or range by himself. If he has to do so for some reason, he always can reset them to the advised values with: "recallDockingInstructions"

By issuing a "requestDockingCoordinates" the ship is added on the waitinglist for being handled by the station. If the ship for some reason aborts the docking it must issue a "abortDocking" command. This removes the ship from the waiting list. If it is not done the carrier could wait indefinitely for the last ship.

The same is true when a ship is killed in the docking procedure. e.g. by smashing into the carrier. The ship stays on the dockinglist and the carrier stays put. The carrier will eventually notice this, but it may take a while. This can be prevented by putting a "abortDocking" command into the death_actions (or shipDied event) of the ships that are on the carrier. This way it is always sure he is removed from the list. And if he was not on a list the command does nothing.

The AI of the station or carrier

Whenever a carrier receives a "requestDockingCoordinates" from a ship it goes for a standstill. This could take some time as carriers are usually heavy. In the meantime it issues a "DOCKING_REQUESTED" to his own AI. That should react to jump to a new state were the docking is handled. When the ship came to a standstill it can calculate docking coordinates and thus from this point on is starts sending coordinates tho the waiting ships. From here on it just works as a station. In this new state it should wait for the next two events: "DOCKING_COMPLETE" or "DOCKING_ABORTED". This event only happens when the last ship that is on the dockinglist has docked or has aborted. But the carrier needs not waiting till docking is ready. It can break of waiting by just giving a new moving command.

Return to OXP howto AI