animation: [EPIC] Entity attachment & weapon animation package — bone sockets, viewmodel, recoil, muzzle VFX

[shadow-kernel]

Vision

A character must be able to HOLD things — and the things must feel real. Today an entity cannot be attached to an animated bone at all: AnimationService evaluates clips and uploads GPU skinning palettes (52-byte vertex, root SRV t5), but no system maps a child entity onto a bone's world transform per frame. That blocks the most fundamental game pattern there is: a character holding a flashlight, a pistol with recoil, muzzle flash, smoke and ejected shells — all moving 100% in sync with the hand through every animation.

This epic delivers the full pipeline: bone sockets (engine), attachment API (scripts), socket authoring UI (editor), bone-masked animation layers (hold weapon while walking), synced dual-entity clips (character reload + weapon reload as one), first-person viewmodel rendering (no wall clipping, own FOV), camera shake/kick primitives, and a complete weapon sample in the Horror Starter template wiring it all together with Physics.Raycast, animation events, audio containers and the light-flicker API. Muzzle smoke gets a billboard-lite version now and the full GPU-particle upgrade in v3.3.

Scope

• animation: bone socket system — entities attach to skeleton bones and follow animation exactly
• scripting: runtime attachment API — Attach/Detach/GetBoneTransform
• editor: socket authoring — bone picker, offset gizmo, live preview
• animation: bone-masked layers — upper-body override/additive (weapon hold + walk)
• animation: synced multi-entity clips — character + weapon animation pairs
• rendering: first-person viewmodel layer — separate FOV, no geometry clipping
• scripting: camera shake + procedural kick/sway primitives
• templates: weapon sample — pistol with recoil, muzzle flash, shells, ammo/reload (project scripts)
• rendering: weapon VFX full package (v3.3 — particle smoke, tracers, shell physics)

Success Criteria

• A skinned character walks while aiming a pistol; the pistol never detaches or lags a single frame — in editor play mode AND the shipped .vpak game (RuntimeDirty verified).
• Firing: recoil kick + muzzle flash + light pulse + smoke + shell + bang + hit-scan — all triggered from ONE animation event, all in project scripts.
• First-person arms/weapon never clip through walls and render with their own FOV.

The full task list will be linked here after the child issues are created.

Task List

• animation: bone socket system — entities attach to skeleton bones and follow animation exactly #170
• scripting: runtime attachment API — Attach/Detach/GetBoneTransform #171
• editor: socket authoring — bone picker, offset gizmo, live preview #172
• animation: bone-masked layers — upper-body override/additive (weapon hold + walk) #173
• animation: synced multi-entity clips — character + weapon animation pairs #174
• rendering: first-person viewmodel layer — separate FOV, no geometry clipping #175
• scripting: camera shake + procedural kick/sway primitives #176
• templates: weapon sample — pistol with recoil, muzzle flash, shells, ammo/reload (project scripts) #177
• rendering: weapon VFX full package — particle smoke, muzzle particles, tracers, shell physics #178