animation: bone-masked layers — upper-body override/additive (weapon hold + walk)

[shadow-kernel]

Context

A character must aim a pistol while walking: legs play walk, upper body plays aim_pistol. The animation system plays exactly one clip per entity today (PlayAnimation/CrossFade) — layered animations with bone masks are listed as a verified gap. Without this, every locomotion × weapon combination needs its own full-body clip (combinatorial explosion: 4 weapons × 5 movement states = 20 authored clips instead of 9).

Goal

Layered evaluation in AnimationService: a base layer (full body) plus override layers restricted to a bone mask (e.g. spine-up), each with its own clip, time and weight — composited into one palette before the existing GPU upload. Additive mode optional in v1; override mode is the priority.

Acceptance Criteria

• Bone mask asset/definition: set of bones (with 'include children' flag), e.g. UpperBody = Spine1+
• Animator supports base layer + ≥1 override layer with clip, speed, weight and mask
• Layer weight blendable at runtime (raise/lower weapon smoothly) from scripts: animator.PlayLayered(clip, layer, mask, weight)
• Walk (legs) + aim (torso/arms) composite correctly on the template character with no foot sliding introduced by the layer split
• Animation events fire per layer (fire event from the aim layer while walking)
• CrossFade works per layer; palette build cost stays within budget (measure: 100 layered characters vs baseline)

Technical Notes

Composite in local space per bone before hierarchy multiplication (blend local TRS by mask weight), not on world palettes. Keep the single-clip fast path untouched when no layers are active.

Dependencies

• None strictly; pairs with 'animation: synced multi-entity clips — character + weapon animation pairs'