Docking animation stages get confused when doing multiple in-sequence docks

[MjnMixael]

Overview:

In BtA2 we setup a fueling arm system for the Zephyrus, all fully animated. When a ship docks, using the various docking stage triggers, the arms rotate out and extend to simulate a refueling arm. It all works really nicely the first time. However, we have a series of ships that dock one after the other and sometimes this seems to cause the docking animation triggers to get confused. We'll see the arms retract rather than extend during docking and/or extend during undocking rather than retract.

Steps to reproduce:

In the attached version of BtA2's second mission you can see the bug in action by launching it as part of the public BtA2 modpack. Start the mission and follow/watch the Zephyrus. Multiple ships will dock to it throughout the mission but only the first set gets the full suite of docking arm animations. For BtA2's initial release we removed the multiple docks but we'd love to get them added back in. (Side note, the objectives during this section of the mission are optional. You can start the mission, follow the Zephyrus until it parks and just sit there and watch it without consequences.)

Relevant details:

bta-anim.tbm has the animation data for the Zephyrus fuel lines on line 635. It may or may not be relevant that we used modular POFs to merge the Zeph-Refuel-System.pof with the MediaVP's Zephyrus.pof. That also adds the dockpoints used here. The table data for that is in bta-pof.tbm on line 135.

bta2_m1_02_docking_enabled.zip

Clean test mission
ZephyDockingAnimationTest.zip

@BMagnu I'm tagging you here because you wrote all the new animation code as well as the modular POFs so it's a safe bet this might end up on your plate.

[MjnMixael]

Clean test mission attached that presents the two requested test cases

1: Multiple ships docking in-sequence to only one dock.
2: Multiple ships docking in-sequence to multiple docks.

[BMagnu]

I wasn't able to immediately repro this on my end.
But I have a theory on what may cause this issue:

This issue may be machine-performance dependent.
Basically, the docking animations are triggered from the AI.
If a ship commands to undock, then the undock animations are triggered.
If a ship commands to dock, then the dock animations are triggered.
If this happens in the right order, no issue.
If, however, both the start of the dock and the undock happen in the same frame, it's possible that the dock command will happen first (dependent on the order of the ship in the ship used list), and the undock command then overriding the animation sequence (since from the animation system's perspective, a ship tried to dock and immediately undocked again, as it doesn't know about the source where this came from).

This means that the issue may also depend on the monitor.
Like, if the events are 10ms spaced, then a 144HZ monitor will never see the issue (if FSO is keeping up), but if you have a 60Hz monitor and VSync or something is on, it'll happen occasionally.

A quick test to confirm this would be to find an affected system, and sufficiently space the undock and dock ai orders (100ms or something). If that fixes it, we've found the culprit.

In the long term, this likely requires a significant overhaul to how the AI handles docking.
Right now, docking is done by the ship docking, including handling the state of the dockee.
However, the dockee should really manage the state, canonically knowing what ship is docking / undocking / doing whatever, and, only once per frame, update its visuals and effects accordingly.