animation: synced multi-entity clips — character + weapon animation pairs

[shadow-kernel]

Context

A reload is really TWO animations: the character's hands move (skeleton A) and the weapon's slide/magazine moves (skeleton B or rigid sub-parts) — they must run frame-locked as one. Nothing links two entities' animation playback today; scripts would have to call PlayAnimation on both and pray the timings match through pauses, crossfades and frame drops. This is the literal 'merge entities in one animation' requirement.

Goal

Synced playback groups: start a named clip pair (or N-tuple) across multiple entities with a single call; one master clock drives all members (same normalized time), pause/speed/crossfade apply to the group; animation events from any member fire normally.

Acceptance Criteria

• Animation.PlaySynced([(entityA, "reload_char"), (entityB, "reload_weapon")], speed, crossfade) from VortexBehaviour
• Members share normalized time — verified drift-free over a 60 s loop and across an intentional frame-rate spike
• Group pause/resume/speed change affects all members atomically
• Works when the weapon is socket-attached to the character (socket + own animation compose: bone follows hand, slide animates locally)
• Animation events fire from both members (e.g. shell_eject on the weapon clip, grab_mag on the character clip)
• Mixamo-imported character clip + custom weapon clip pairing demonstrated in the template

Technical Notes

Implement as a group time driver in AnimationService (single clock, N animators sample it) rather than per-frame time copying. Attached-entity update order from the socket issue already guarantees hand-then-weapon evaluation.

Dependencies

• animation: bone socket system — entities attach to skeleton bones and follow animation exactly
• animation: animation events — keyframe callbacks to scripts (footsteps!)