animation: bone socket system — entities attach to skeleton bones and follow animation exactly

[shadow-kernel]

Context

The skeletal animation system is complete for rendering (bone/clip import, GPU skinning with palettes in a persistently-mapped GPU buffer, AnimationService managed evaluation, Keyframe Editor) — but bone transforms are consumed ONLY by the skinning shader. There is no way to make a separate entity (weapon, flashlight, hat, lantern) follow a bone. This is the root feature of the whole weapon package: 'merge' an entity into an animation.

Goal

A BoneSocket mechanism: an attached child entity's world transform is driven every frame by (animated bone world matrix × local socket offset). Since AnimationService already evaluates palettes CPU-side, the bone world transforms exist — expose them and apply to attached entities after animation evaluation, before rendering/culling.

Acceptance Criteria

• Attachment component: target skeletal entity + bone name + local position/rotation/scale offset
• Attached entity follows the bone with zero visible lag through any clip (update order: animation → sockets → transforms → render/culling)
• Works for hierarchies: attached entity's own children follow too
• Works in editor play mode, standalone player and shipped .vpak builds (RuntimeDirty moving-entity trap explicitly verified)
• Serialized in scenes and prefabs (character prefab + weapon prefab stays wired after restart)
• Attached entities participate correctly in culling (bounds follow the socket) and collision (colliders move with it)
• Multiple sockets per skeleton (left hand, right hand, head, back) simultaneously

Technical Notes

Evaluate socket transforms exactly once per frame from the same pose the palette upload used — do not re-sample clips a second time (drift). Missing bone name = warning + identity fallback, never a crash. Bone transforms should be queryable (GetBoneWorldTransform) — the muzzle-position raycast in the weapon sample depends on it.

Dependencies

• None (foundation of this epic)