# 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`.