add blueprints

docs/blueprints/08-weapons/76_BPC_MeleeSystem.md

@@ -0,0 +1,134 @@
+# BPC_MeleeSystem — Melee Weapon Component
+
+## Blueprint Spec — UE 5.5–5.7
+
+---
+
+### Parent Class
+`ActorComponent`
+
+### Dependencies
+- [`BPC_DamageReceptionSystem`](BPC_DamageReceptionSystem.md)
+- [`BPC_CombatFeedbackComponent`](54_BPC_CombatFeedbackComponent.md)
+- [`I_Damageable`](../01-core/03_I_InterfaceLibrary.md)
+- [`DA_WeaponData`](../14-data-assets/)
+- Owner Character Animation Blueprint
+
+### Purpose
+Melee weapon specialization. Handles swing detection, hitbox overlap checking during windup / active frames, and combo chain sequencing. Supports light attacks, heavy attacks, charge attacks, and block/parry.
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `ComboSection` | FName | Active montage section for combo |
+| `ComboStep` | Int | Current combo step index |
+| `bCanCombo` | Bool | True during window after hit or end of swing |
+| `ComboWindowDuration` | Float | Seconds to chain next attack |
+| `SwingMontage` | UAnimMontage | Full melee animation set |
+| `HitDetectionCollision` | UCapsuleComponent | Overlap collision for hit detection |
+| `bHitRegistered` | Bool | Prevents multi-hit on same swing |
+| `HitActors` | Array<AActor> | Already hit this swing |
+| `SwingPhase` | ESwingPhase | Windup / Active / Recovery / Idle |
+| `ChargeDuration` | Float | Hold time for charged heavy attack |
+| `bIsBlocking` | Bool | Currently blocking stance |
+| `ParryWindow` | Float | Active parry frames in seconds |
+| `bParryActive` | Bool | Within parry active window |
+| `StaggerDuration` | Float | Hit reaction stun (self or target) |
+
+### Enums
+
+| Enum | Values | Description |
+|------|--------|-------------|
+| `ESwingPhase` | Idle, WindUp, Active, Recovery, ParryWindow | Attack animation phase |
+| `EAttackType` | LightAttack, HeavyAttack, ChargeAttack, SprintAttack, ParryRiposte | Swing variant |
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `StartSwing` | AttackType: EAttackType | — | Play montage section, set SwingPhase |
+| `OnSwingWindup` | — | — | Begin hit detection |
+| `OnSwingActive` | — | — | Enable HitDetectionCollision overlap |
+| `OnSwingHit` | HitResult: FHitResult | — | Single hit registration |
+| `OnSwingRecovery` | — | — | Disable hit collision, check combo window |
+| `OnSwingComplete` | — | — | Return to Idle |
+| `StartBlock` | — | — | Play blocking animation |
+| `EndBlock` | — | — | Release block stance |
+| `ParryCheck` | IncomingAttack | Bool | If parry window active → counter |
+| `GetComboStep` | — | Int | Return current combo index |
+| `ResetCombo` | — | — | Clear combo step counter |
+
+### Blueprint Flow
+
+```
+[Combo Chain Logic]
+  LightAttackInput →
+    If SwingPhase == Idle:
+        ComboStep = 0
+        StartSwing(LightAttack)
+    ElseIf SwingPhase == Active || SwingPhase == Recovery:
+        If bCanCombo && ComboStep < MaxComboLength:
+            ComboStep++
+            StartSwing(LightAttack) — next section of montage
+
+[OnSwingActive — called by Animation Notify]
+  └─► HitDetectionCollision.SetCollisionEnabled(QueryOnly)
+  └─► On overlap → OnSwingHit
+
+[OnSwingHit]
+  └─► If HitActor already in HitActors → return
+  └─► Add HitActor to HitActors
+  └─► If HitActor implements I_Damageable:
+         BPC_DamageReceptionSystem.ApplyMeleeDamage(
+             Damage = WeaponData.Damage * AttackTypeMultiplier,
+             HitActor,
+             HitLocation,
+             ImpulseDirection
+         )
+  └─► BPC_CombatFeedbackComponent.PlayHitFX(HitResult)
+  └─► ApplyStagger(HitActor)
+
+[OnSwingRecovery — called by Animation Notify]
+  └─► HitDetectionCollision.SetCollisionEnabled(NoCollision)
+  └─► HitActors.Empty
+  └─► Set bCanCombo = true
+  └─► Start timer for ComboWindowDuration
+  └─► If no combo input received → OnSwingComplete
+
+[OnSwingComplete]
+  └─► SwingPhase = Idle
+  └─► bCanCombo = false
+  └─► ComboStep = 0
+
+[StartBlock]
+  └─► bIsBlocking = true
+  └─► Play block montage loop section
+  └─► Owner movement speed reduced
+
+[ParryCheck]
+  └─► If bParryActive && incoming swing phase == Active:
+         Play parry riposte animation
+         Stagger incoming attacker
+         Return true
+  └─► Return false
+```
+
+### Communications With
+
+| Target | Method | Why |
+|--------|--------|-----|
+| [`BPC_DamageReceptionSystem`](BPC_DamageReceptionSystem.md) | Get Component | Apply melee damage and stagger |
+| [`BPC_CombatFeedbackComponent`](54_BPC_CombatFeedbackComponent.md) | Get Component | Swing whoosh, hit impact, block sparks |
+| Owner Animation Blueprint | Direct | Query SwingPhase for animation state |
+| Owner Character Movement | Direct | Reduce speed during block |
+| Owner Character Input | Direct | Light / Heavy / Block input mapping |
+| [`I_Damageable`](../01-core/03_I_InterfaceLibrary.md) | Interface | Damage application on hit actors |
+
+### Reuse Notes
+- Uses animation notifies for phase transitions (Notify_Windup, Notify_Active, Notify_Recovery, Notify_CanCombo, Notify_ParryWindow).
+- Combo system uses montage section names "Combo_1", "Combo_2", etc.
+- Hit collision is a simple box or capsule that exists only during Active phase.
+- Block reduces incoming damage via DamageReception; parry reflects stagger.
+- Renamed from `BP_MeleeWeapon` to `BPC_MeleeSystem` per Master naming convention.
+- Cross-references updated: `BPC_DamageHandlerComponent` → `BPC_DamageReceptionSystem`.