AI-Docking Instructions for Oolite ships.
See Docking for details (and relevant links) of how to actually manage to do it!
The AI of the docking ship
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.
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
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
Now I need to get my head around Quaternions again, still trying to figure out how to match station rotation during auto-dock... That reminds me of this anecdote in an interview (Acorn User, September 1995) with Clive Gringras, one of the creators of ArcElite: Sorting the men from the boys Our discussions with David Braben and Ian Bell sometimes ended up with Ian or David saying that a particular aspect of the game was quite tricky. Docking computers was a case in point; Ian said they should "sort the men from the boys". He was right. The first hurdle with docking, as any Commander knows, is getting lined-up with the letterbox (opening slot) of the space station. This was achieved by marking a point out in front of the letterbox with an invisible buoy. However, lining up with the letterbox is the least of a Commander's worries; it's the "boxing" or matching the rotation of the letterbox that really flummoxes. We decided to imagine that there was one "arrow" or vector sticking out of the right wing of the ship and one out of the left side of the space station. As the station rotated, the two vectors described various positions of the hands of a clock. When the vectors pointed in the same direction, it was safe to dock without scraping the craft. Therefore we coded the flight program to minimise at all times the angle between the two vectors. Because the flight program actually manipulated the Cobra, the added bonus was that - if present - yaw boosters were utilised, and the player could still use the Cobra in case of trouble. Needless to say, the next communication from Commander Bell began, "Hello men..."! Gimbal Locke (2012)