add architecture

docs/architecture/animation-catalog.md

@@ -0,0 +1,282 @@
+# Animation Requirements Catalog — Modular Game Framework
+
+**For: Animator / Technical Animator | UE 5.5–5.7 | GASP-Based**
+
+This catalog lists every animation asset needed across all 135 blueprint systems, organized by system category, with trigger, type, body region, and GASP integration notes.
+
+---
+
+## How to Use This Catalog
+
+1. **Montages** = Root motion or in-place split into sections with notifies
+2. **BlendSpaces** = Parameter-driven blending (speed, direction, strafe angle)
+3. **PoseAssets** = Single-frame poses for IK targets or overlay blending
+4. **IK Rigs** = Procedural arm/leg positioning
+
+**GASP Integration Rule:** All full-body locomotion animations route through [`ABP_GASP`](../CONTEXT.md:9). Systems notify GASP via dispatchers; GASP reads state variables and selects the correct animation.
+
+---
+
+## 1. Locomotion System (GASP Core — Extended, Not Replaced)
+
+| Trigger | Asset Type | Body | Notes |
+|---------|-----------|------|-------|
+| `Idle` → `Walking` → `Jogging` → `Sprinting` | **BlendSpace** | Full | GASP core locomotion blend. Speed + direction + strafe angle as params. Extended by framework: extra sprint variant for exhaustion, injured walk variant |
+| `Crouching` + moving | **BlendSpace** | Full | Crouch locomotion. Speed as param. Separate from standing blendspace |
+| `Prone` / `Crawling` | **BlendSpace** or **Montage** | Full | Prone crawl. Slow. Forward only initially, with strafe variants |
+| `Jump Start` / `Jump Loop` / `Jump Land` | **Montage** (3 sections) | Full | Jump with velocity-based land (soft/hard). Motion matching picks jump type |
+| `Fall Loop` | **BlendSpace** | Full | Falling animation based on vertical velocity |
+| `Land Soft` / `Land Hard` / `Land Roll` | **Montage** | Full | Velocity threshold determines land type. `OnLanded` dispatcher drives selection |
+| `Turn In Place` (90°, 180°) | **Montage** | Full | Root motion turn. Triggered by GASP when exceeding rotation threshold |
+| `Start Walk` / `Stop Walk` | **BlendSpace** (inertialization) | Full | GASP handles via motion matching — no separate asset needed |
+
+---
+
+## 2. Player Vital States
+
+| System | Trigger | Asset Type | Body | Notes |
+|--------|---------|-----------|------|-------|
+| `BPC_HealthSystem` (08) | `OnDeath` | **Montage** (4 sections) | Full | `E_DeathAnimationStage`: PreDeath (stagger), DeathAnim (fall), PostDeath (dark), RespawnTransition (fade-up). Directional death variants (front/back/left/right) |
+| `BPC_HealthSystem` (08) | `OnDamageTaken` (minor) | **Montage** (upper overlay) | Upper | Flinch reaction, brief |
+| `BPC_StaminaSystem` (09) | `OnExhaustionStateChanged` → Exhausted | **Montage** (loop) | Upper | Heavy breathing + hunched posture. `ABP_GASP` reads `bExhausted` |
+| `BPC_StaminaSystem` (09) | Exhausted → Sprint attempt | **Montage** | Full | Failed sprint start — stumble |
+| `BPC_StressSystem` (10) | `OnStressTierChanged` → Panicked | **PoseAsset** | Full | Shaky hands, rapid breathing chest rise. Blend weight scales with stress |
+| `BPC_StressSystem` (10) | `OnStressTierChanged` → Catatonic | **Montage** | Full | Freeze in place, stumble, collapse |
+| `BPC_StressSystem` (10) | `OnHallucinationTriggered` | **Montage** (upper) | Upper | Flinch at hallucination, head whip |
+
+---
+
+## 3. Hiding & Stealth
+
+| System | Trigger | Asset Type | Body | Notes |
+|--------|---------|-----------|------|-------|
+| `BPC_HidingSystem` (12) | `EnterHideSpot` (Locker) | **Montage** | Full | Open locker, step in, close door. Notify: `OnAnimationHideEnterComplete` |
+| `BPC_HidingSystem` (12) | `EnterHideSpot` (BehindCover) | **Montage** | Full | Crouch behind cover, settle |
+| `BPC_HidingSystem` (12) | `EnterHideSpot` (Under) | **Montage** | Full | Crawl under bed/table |
+| `BPC_HidingSystem` (12) | `EnterHideSpot` (InShadow) | **Montage** | Full | Step into shadow, blend with darkness |
+| `BPC_HidingSystem` (12) | `EnterHideSpot` (TallGrass) | **BlendSpace** (crouch) | Full | Crouch-walk through vegetation (locomotion, not one-shot) |
+| `BPC_HidingSystem` (12) | `ExitHideSpot` (all types) | **Montage** | Full | Reverse of enter. `bForceExit` skips animation |
+| `BPC_HidingSystem` (12) | `ExitHideSpot` (forced — enemy discovered) | **Montage** | Full | Burst out stumbling |
+| `BPC_HidingSystem` (12) | `StartPeek` (Left/Right/Over) | **PoseAsset** (blend) | Upper | Lean/peek pose. Not full-body — camera shifts |
+| `BPC_HidingSystem` (12) | `HoldBreath Start` / `HoldBreath End` | **Montage** (upper) | Upper | Hand over mouth, exhale |
+
+---
+
+## 4. Interaction & World Manipulation
+
+| System | Trigger | Asset Type | Body | Notes |
+|--------|---------|-----------|------|-------|
+| `BP_DoorActor` (19) | `Open` / `Close` | **Timeline** (world) | — | Door mesh rotation — not a character anim |
+| `BP_ItemPickup` (25) | `BeingPickedUp` | **Montage** | Arms | Reach down, grab item, pocket. Notify: `OnPickupAnimationComplete` |
+| `BP_ItemPickup` (25) | `Idle Bob` / `Rotate` | **Timeline** (world) | — | Item floating bobbing/rotating — not character |
+| `BPC_ContextualTraversalSystem` (21) | `Vault` | **Montage** (root motion) | Full | Hands on obstacle, vault over. Motion Warping to obstacle edge |
+| `BPC_ContextualTraversalSystem` (21) | `Mantle` | **Montage** (root motion) | Full | Grab ledge, pull up, step over. Motion Warping to ledge top |
+| `BPC_ContextualTraversalSystem` (21) | `Slide` | **Montage** (root motion) | Full | Slide under low obstacle |
+| `BPC_ContextualTraversalSystem` (21) | `Squeeze` | **Montage** (root motion) | Full | Side-step through narrow gap |
+| `BPC_ContextualTraversalSystem` (21) | `LedgeGrab` / `LedgeHang` | **Montage** (loop) + **PoseAsset** | Full | Hanging from ledge. Motion Warping to ledge edge |
+| `BPC_PhysicsDragSystem` (22) | `GrabObject` | **PoseAsset** (IK) | Arms | Hand IK target to grab socket |
+| `BPC_PhysicsDragSystem` (22) | `DragObject` (moving) | **BlendSpace** (upper overlay) | Upper | Walking while dragging. IK hand stays locked |
+| `BPC_UsableWorldObjectSystem` (23) | `UseLever` / `UsePanel` / `UseValve` | **Montage** (upper) | Upper | Hand reaches to interaction point. IK to target socket |
+
+---
+
+## 5. Weapon & Combat — General
+
+| System | Trigger | Asset Type | Body | Notes |
+|--------|---------|-----------|------|-------|
+| `BP_WeaponBase` (69) | `Equip` (from holster) | **Montage** | Upper | Draw weapon animation. `E_EquipAnimationType.Equip` |
+| `BP_WeaponBase` (69) | `Holster` (to holster) | **Montage** | Upper | Holster animation. `E_EquipAnimationType.Holster` |
+| `BP_WeaponBase` (69) | `Unequip` (drop/switch) | **Montage** | Upper | Reverse of equip |
+| `BPC_EquipmentSlotSystem` (30) | `InstantEquip` | None | — | No animation — weapon appears instantly |
+
+---
+
+## 6. Firearm Combat
+
+| System | Trigger | Asset Type | Body | Notes |
+|--------|---------|-----------|------|-------|
+| `BPC_FirearmSystem` (74) | `Fire` (Pistol) | **Montage** (single) | Upper | Recoil + slide cycle. Notify: `OnAmmoConsumed` |
+| `BPC_FirearmSystem` (74) | `Fire` (Shotgun) | **Montage** | Upper | Pump action. Heavier recoil |
+| `BPC_FirearmSystem` (74) | `Fire` (Rifle Auto) | **Montage** (loop) | Upper | Automatic fire loop until trigger released |
+| `BPC_ReloadSystem` (78) | `TacticalReload` (ammo > 0) | **Montage** | Upper | Mag out, mag in. Notify: `OnMagOut`, `OnMagIn`, `OnReloadComplete` |
+| `BPC_ReloadSystem` (78) | `EmptyReload` (ammo = 0) | **Montage** | Upper | Mag out, mag in, bolt cycle. Longer. Same notifies |
+| `BPC_ReloadSystem` (78) | `ReloadInterrupt` | **Blend** | Upper | Blend back to idle from any reload notify point |
+| `BPC_FirearmSystem` (74) | `ChamberCheck` | **Montage** (upper) | Upper | Quick chamber check animation |
+| `BPC_RecoilSystem` (77) | `Recoil` (per shot) | **Procedural** (spring arm) | — | Camera recoil + hand animation via spring arm offset. Not a montage |
+
+---
+
+## 7. Melee Combat
+
+| System | Trigger | Asset Type | Body | Notes |
+|--------|---------|-----------|------|-------|
+| `BPC_MeleeSystem` (76) | `LightAttack` (Combo 1/2/3) | **Montage** | Upper | 3-hit combo. Sections: Combo_1, Combo_2, Combo_3. Notify: `Notify_Windup`, `Notify_Active`, `Notify_Recovery`, `Notify_CanCombo` |
+| `BPC_MeleeSystem` (76) | `HeavyAttack` | **Montage** | Upper | Slow windup, high damage. `E_AttackType.HeavyAttack` |
+| `BPC_MeleeSystem` (76) | `ChargeAttack` | **Montage** | Upper | Hold to charge, release to strike. Charge duration tracked |
+| `BPC_MeleeSystem` (76) | `SprintAttack` | **Montage** | Upper | Running melee attack |
+| `BPC_MeleeSystem` (76) | `Block Start` / `Block Loop` / `Block End` | **Montage** (loop) | Upper | Block stance loop. Owner movement speed reduced |
+| `BPC_MeleeSystem` (76) | `Parry` | **Montage** | Upper | Quick parry deflection. Active window via `Notify_ParryWindow` |
+| `BPC_MeleeSystem` (76) | `ParryRiposte` | **Montage** | Upper | Counter-attack after successful parry |
+| `BPC_ShieldDefenseSystem` (79) | `ShieldRaise` / `ShieldLower` | **Montage** | Upper | Raise/lower shield |
+| `BPC_ShieldDefenseSystem` (79) | `Block Impact` (shield hit) | **Montage** (additive) | Upper | Additive shake on shield hit |
+
+---
+
+## 8. Hit Reactions & Damage
+
+| System | Trigger | Asset Type | Body | Notes |
+|--------|---------|-----------|------|-------|
+| `BPC_HitReactionSystem` (75) | `OnDamageTaken` (Light) | **Montage** (additive) | Full | Flinch. Directional: front/back/left/right |
+| `BPC_HitReactionSystem` (75) | `OnDamageTaken` (Heavy) | **Montage** | Full | Stagger backward. Directional |
+| `BPC_HitReactionSystem` (75) | `OnDamageTaken` (Knockdown) | **Montage** | Full | Fall to ground |
+| `BPC_HitReactionSystem` (75) | `GetUp` (from knockdown) | **Montage** | Full | Stand up from ground |
+| `BPC_HitReactionSystem` (75) | `Stagger Loop` | **PoseAsset** (loop) | Full | Dazed swaying while standing |
+| `BPC_DamageReceptionSystem` (72) | `Death` (instant, no death loop) | **Montage** | Full | Ragdoll-triggered death |
+
+---
+
+## 9. Death & Respawn
+
+| System | Trigger | Asset Type | Body | Notes |
+|--------|---------|-----------|------|-------|
+| `BPC_DeathHandlingSystem` (39) | `DeathAnim` (standard) | **Montage** | Full | See HealthSystem death — same asset, called via `E_DeathAnimationStage.DeathAnim` |
+| `BPC_DeathHandlingSystem` (39) | `PreDeath` (camera lock) | **PoseAsset** (freeze) | Full | Freeze frame-like pose on killing blow |
+| `BPC_DeathHandlingSystem` (39) | `RespawnTransition` | **PostProcess** (fade) | — | Screen fade-up — no skeletal anim |
+| `BPC_AltDeathSpaceSystem` (38) | `EnterAltDeathSpace` | **Montage** | Full | Being pulled into void/portal |
+| `BPC_AltDeathSpaceSystem` (38) | `Void Walk` | **BlendSpace** | Full | Walking in alt death space — slow, floating feel |
+| `BPC_AltDeathSpaceSystem` (38) | `ExitAltDeathSpace` | **Montage** | Full | Emerging from void/portal back to world |
+| `BPC_AltDeathSpaceSystem` (38) | `Void Idle` | **PoseAsset** | Full | Floating idle in void |
+
+---
+
+## 10. Narrative & Dialogue
+
+| System | Trigger | Asset Type | Body | Notes |
+|--------|---------|-----------|------|-------|
+| `BPC_DialoguePlaybackSystem` (60) | `OnLineStarted` | None | — | VO audio only. Lip-sync handled by audio waveform, not animation |
+| `BPC_DialoguePlaybackSystem` (60) | `Dialogue Idle` | **PoseAsset** (upper) | Upper | Subtle hand gestures, head nods during dialogue. Blend by line intensity |
+| `BPC_CutsceneBridge` (64) | Cutscene animation | **Level Sequence** | Full | All cutscene animation authored in Sequencer, not as montages |
+| `BPC_CutsceneBridge` (64) | `Transition` (Fade/HardCut/Letterbox) | **PostProcess** (UWidget) | — | Black bars, fade overlay — UI animation |
+| `BPC_NarrativeStateSystem` (58) | `OnMilestoneReached` (major) | None | — | May trigger cutscene or audio stinger |
+
+---
+
+## 11. AI Enemy
+
+| System | Trigger | Asset Type | Body | Notes |
+|--------|---------|-----------|------|-------|
+| `BP_EnemyBase` (80) | `Patrol Walk` | **BlendSpace** | Full | Slow patrol locomotion. Speed + direction params |
+| `BP_EnemyBase` (80) | `Search Walk` | **BlendSpace** | Full | Faster search locomotion |
+| `BP_EnemyBase` (80) | `Combat Strafe` | **BlendSpace** | Full | Strafing combat locomotion. Direction angle param |
+| `BP_EnemyBase` (80) | `Flee Sprint` | **BlendSpace** | Full | Sprinting away |
+| `BP_EnemyBase` (80) | `Attack` (melee) | **Montage** | Upper | Enemy-specific attack montage |
+| `BP_EnemyBase` (80) | `Attack` (ranged) | **Montage** | Upper | Enemy-specific ranged attack |
+| `BP_EnemyBase` (80) | `Hit Reaction` (light/heavy) | **Montage** | Full | Enemy hit reactions — same as player but different skeleton |
+| `BP_EnemyBase` (80) | `Death` | **Montage** → **Ragdoll** | Full | Death animation blending to ragdoll |
+| `BPC_AlertSystem` (82) | `Suspicious` (head turn) | **Montage** (additive) | Upper | Head snap toward sound. Body turn |
+| `BPC_AlertSystem` (82) | `Alerted` (weapon raise) | **Montage** | Full | Raise weapon, enter combat stance |
+| `BPC_AlertSystem` (82) | `Combat → Search` (weapon lower) | **Montage** | Full | Lower weapon, start searching |
+| `BPC_BehaviourVariantSelector` (88) | Variant-specific attacks | **Montage** | Upper | Chooses from multiple variant attack sets |
+| `BPC_FearSystem` (90) | `Fearful` (enemy) | **PoseAsset** | Full | Cowering, whimpering pose |
+
+---
+
+## 12. Embodiment & IK
+
+| System | Trigger | Asset Type | Body | Notes |
+|--------|---------|-----------|------|-------|
+| `BPC_EmbodimentSystem` (13) | `CheckWallProximity` | **IK Rig** (arms) | Arms | Arm IK offset when near walls. Notifies `ABP_Arms` |
+| `BPC_EmbodimentSystem` (13) | `SetVisibilityMode` (ArmsOnly/FullBody/Hidden) | Mesh visibility toggle | — | Not an animation — mesh component visibility |
+| `BPC_EmbodimentSystem` (13) | `OnOverlayChanged` (blood/water/dirt) | Material parameter | — | Overlay material swap on body mesh |
+| `BPC_ConsumableSystem` (28) | `UseConsumable` (bandage, syringe) | **Montage** | Upper | Use item animation. IK hand to item |
+
+---
+
+## 13. Atmosphere & Environment (Non-Character)
+
+| System | Trigger | Asset Type | Notes |
+|--------|---------|-----------|-------|
+| `BPC_LightEventController` (96) | `OnLightEvent` | **Timeline** (light intensity/color) | Light flicker, dim, color shift via timeline |
+| `BPC_AudioAtmosphereController` (95) | `OnAtmosphereChanged` | Audio fade (not anim) | Sound only |
+| `BPC_MemoryDriftSystem` (97) | Memory distortion active | **PostProcess** | Screen distortion — not skeletal |
+| `BPC_ScareEventSystem` (101) | `OnScareTriggered` | **Camera Shake** | Camera whip/shake |
+
+---
+
+## 14. UI Widget Animations (Non-Skeletal)
+
+| System | Trigger | Animation Type |
+|--------|---------|---------------|
+| All `WBP_` widgets | Open/Close/Show/Hide | `UWidgetAnimation` (fade, slide, pulse, scale) |
+| `WBP_ScreenEffectController` (56) | Damage vignette, stress vignette | `UWidgetAnimation` (pulse, fade, color shift) |
+| `WBP_NotificationToast` (53) | Show/Hide | `UWidgetAnimation` (slide in, auto-dismiss) |
+| `WBP_InteractionPromptDisplay` (48) | Show/Hide | `UWidgetAnimation` (fade in/out) |
+
+---
+
+## Summary — Asset Count by Type
+
+| Asset Type | Count (Approx) | Systems Served |
+|-----------|----------------|----------------|
+| **BlendSpaces** (locomotion) | 8–12 | Movement, AI, Hiding |
+| **Montages** (action/reaction) | 40–55 | Weapons, Melee, Hiding, Death, Traversal, HitReaction, Enemy |
+| **PoseAssets** | 8–12 | Stress, Peek, Embodiment, Idle |
+| **IK Rigs** | 2–4 | Embodiment, Physics Drag |
+| **Timelines** (non-skeletal) | 8–12 | Doors, Pickups, Lights, UI |
+| **Procedural** (recoil, camera) | 2–4 | Recoil, Camera Shake |
+| **Level Sequences** (cutscenes) | Per-content | Cutscene Bridge |
+
+**Grand Total: ~70–100 skeletal animation assets + per-cutscene Level Sequences**
+
+---
+
+## GASP Animation Notify Contract
+
+The following animation notifies must be present in montages for the framework to function:
+
+| Notify Name | Used By | Purpose |
+|-------------|---------|---------|
+| `Notify_Windup` | `BPC_MeleeSystem` | Begin melee hit detection window |
+| `Notify_Active` | `BPC_MeleeSystem` | Enable hit collision overlap |
+| `Notify_Recovery` | `BPC_MeleeSystem` | Disable hit collision, start combo window |
+| `Notify_CanCombo` | `BPC_MeleeSystem` | Window during which next combo input is accepted |
+| `Notify_ParryWindow` | `BPC_MeleeSystem` | Parry-active frames |
+| `Notify_OnAnimationHideEnterComplete` | `BPC_HidingSystem` | Hide spot enter animation finished |
+| `Notify_OnAnimationHideExitComplete` | `BPC_HidingSystem` | Hide spot exit animation finished |
+| `Notify_OnMagOut` | `BPC_ReloadSystem` | Magazine removed from weapon |
+| `Notify_OnMagIn` | `BPC_ReloadSystem` | Magazine inserted into weapon |
+| `Notify_OnReloadComplete` | `BPC_ReloadSystem` | Reload finished, ammo refilled |
+| `Notify_OnPickupAnimationComplete` | `BP_ItemPickup` | Pickup animation finished, item collected |
+| `Notify_OnAmmoConsumed` | `BPC_FirearmSystem` | Ammo consumed during fire animation |
+| `Notify_TraversalEnd` | `BPC_ContextualTraversalSystem` | Traversal animation complete, return to locomotion |
+
+---
+
+## Priority Order for Animation Production
+
+1. **GASP Locomotion Base** (Idle, Walk, Jog, Sprint, Crouch, Jump, Land, Turn) — required for any movement
+2. **Hiding Enter/Exit** (Locker, BehindCover, Under) — core stealth mechanic
+3. **Traversal** (Vault, Mantle, Slide, Squeeze, LedgeGrab) — level navigation
+4. **Weapon Equip/Holster** (Pistol, Shotgun, Rifle, Melee, Shield) — combat foundation
+5. **Weapon Fire/Reload/Melee** — combat moment-to-moment
+6. **Hit Reactions** (Light/Heavy/Knockdown per direction) — combat feedback
+7. **Death & Respawn** — game loop completion
+8. **Interaction** (Pickup, Lever, Valve, Panel) — world interaction
+9. **Stress/Fear/Exhaustion Poses** — atmosphere and tension
+10. **AI Locomotion + Combat** — enemy behaviors
+11. **Alt Death Space** — optional deep feature
+
+---
+
+*Animation Catalog v1.0 — Aligned with Modular Game Framework Blueprint Specs. Handoff-ready for Animator.*
+## 16. New States — Sitting, Injured, Heart Rate (Breathing)
+
+| System | Trigger | Asset Type | Body | Notes |
+|--------|---------|-----------|------|-------|
+| `BPC_StateManager` (NEW) | `Sitting` (entered via world interaction point) | **Montage** | Full | Sit down transition. Loop pose for idle sitting. Camera limited to head freelook |
+| `BPC_StateManager` (NEW) | `StandUp` (from Sitting) | **Montage** | Full | Stand up transition |
+| `BPC_StateManager` (NEW) | `Injured` (health ≤ 30%) | **BlendSpace** (locomotion overlay) | Full | Limping walk animation. Reduced speed. One arm favoring (visible on overlay) |
+| `BPC_StateManager` (NEW) | `Injured` idle | **PoseAsset** | Full | Injured idle stance — favoring one side, shallow breathing |
+| `BPC_StateManager` (NEW) | Heart rate breathing | **Blend** (additive on torso) | Upper | Breathing amplitude increases with `ABP_GASP.HeartRate` parameter. 60 BPM = shallow, 150+ BPM = heavy chest heaving |
+| `BPC_StateManager` (NEW) | Heart rate — Erratic | **Blend** (additive, random variation) | Upper | Irregular breathing rhythm when `E_PlayerVitalSignals.Erratic`. Random amplitude jumps |
+| `BPC_StateManager` (NEW) | `E_OverlayState.Injured` | **PoseAsset** (upper) | Upper | Injured arm lowered, favoring — applied via overlay system to GASP |