# BPC_DamageReceptionSystem — Damage Reception System

> **⚡ C++ Status: Full Implementation** — `Source/PG_Framework/Public/Weapons/BPC_DamageReceptionSystem.h` provides the complete damage pipeline: raw damage → resistance → armor → shield → health → hit reaction. **Attach directly to player/enemy pawns** (Add Component → `BPC_DamageReceptionSystem`). Call `ApplyDamage(RawDamage, Causer, DamageType, HitLocation, HitDirection)`. Set `StaggerThreshold`/`KnockdownThreshold` in Details panel. Do NOT create a BP child. See `docs/developer/cpp-integration-guide.md`.
>
> ---

## Blueprint Spec — UE 5.5–5.7

---

### Parent Class
`ActorComponent`

### Dependencies
- [`I_Damageable`](../01-core/03_I_InterfaceLibrary.md) — Interface on damage targets
- [`BP_WeaponBase`](49_BP_WeaponBase.md) — Owner weapon (optional)
- [`BPC_HealthSystem`](../02-player/08_BPC_HealthSystem.md) — Damage recipient
- [`BPC_CombatFeedbackComponent`](54_BPC_CombatFeedbackComponent.md) — Damage FX forwarding
- [`DA_WeaponData`](../14-data-assets/) — Damage/penetration values
- `Engine.DamageType` — UE5 damage type system

### Purpose
Centralized damage calculation and application service. Decouples weapon fire logic from damage math. Handles damage types, armor penetration, critical hit rolls, damage falloff over distance, and damage event logging. Can be attached to weapons, projectiles, or trap actors.

### Variables

| Name | Type | Description |
|------|------|-------------|
| `DamageMultiplier` | Float | Per-instance modifier (e.g. weak spot) |
| `bUseDamageFalloff` | Bool | Enable distance-based damage reduction |
| `FalloffStartDistance` | Float | Distance before falloff begins (cm) |
| `FalloffEndDistance` | Float | Distance where damage reaches minimum |
| `MinDamageFactor` | Float | 0.0–1.0, minimum damage at max range |
| `DamageType` | TSubclassOf<UDamageType> | UE5 damage type class |
| `LastDamageDealt` | float | Most recent damage output (debug/logging) |
| `LastHitActor` | AActor | Most recent recipient |
| `bShowDamageNumbers` | Bool | Debug toggle |
| `CritChanceOverride` | Float | If > 0, overrides weapon default |
| `CritMultiplierOverride` | Float | If > 0, overrides weapon default |

### Structs

| Struct | Fields | Description |
|--------|--------|-------------|
| `FDamageResult` | DamageDealt: Float, bWasCrit: Bool, bWasBlocked: Bool, DamageTypeTag: FGameplayTag, HitLocation: FVector, HitNormal: FVector | Damage calculation output |
| `FDamageRequest` | BaseDamage: Float, Instigator: AActor, DamageCauser: AActor, HitInfo: FHitResult, DamageType: TSubclassOf<UDamageType>, bIsMelee: Bool | Incoming damage data |

### Functions

| Name | Inputs | Outputs | Description |
|------|--------|---------|-------------|
| `ProcessDamageRequest` | Request: FDamageRequest | FDamageResult | Main calculation entry |
| `ApplyDamageToActor` | Target: AActor, Request: FDamageRequest | Bool | Apply via interface or engine ApplyDamage |
| `CalculateDamageFalloff` | BaseDamage: Float, Distance: Float | Float | Linear interpolation between start/end |
| `RollForCriticalHit` | CritChance: Float | Bool | Random roll against chance |
| `CalculateArmorPenetration` | BaseDamage: Float, ArmorValue: Float | Float | Armor reduction math |
| `ApplyWeakSpotMultiplier` | Damage: Float, WeakSpotTag: FGameplayTag | Float | From character weak spot config |
| `OnDamageApplied` | Result: FDamageResult | — | Broadcast event |
| `GetDistanceToTarget` | Target: AActor | Float | Distance from weapon muzzle to hit |
| `LogDamageEvent` | Result: FDamageResult | — | For analytics / combat log |
| `SetDamageMultiplier` | Multiplier: Float | — | Runtime override (e.g. buff) |

### Event Dispatchers

| Name | Parameters | Fired When |
|------|-----------|-----------|
| `OnDamageDealt` | Target: AActor, Damage: Float, IsCrit: Bool, DamageTypeTag: FGameplayTag | Damage applied successfully |
| `OnDamageBlocked` | Target: AActor, BlockedDamage: Float | Damage reduced by armor / block |
| `OnCriticalHit` | Target: AActor, Damage: Float | Critical hit confirmed |
| `OnWeakSpotHit` | Target: AActor, WeakSpotTag: FGameplayTag | Weak spot damage |
| `OnKillConfirmed` | Target: AActor | Target health <= 0 |

### Blueprint Flow

```
[ProcessDamageRequest]
  └─► CurrentDamage = Request.BaseDamage
  └─► If bUseDamageFalloff:
         Distance = GetDistanceToTarget(Request.Instigator)
         CurrentDamage = CalculateDamageFalloff(CurrentDamage, Distance)
  └─► If Request.bIsMelee:
         CurrentDamage *= DamageMultiplier
  └─► // Crit roll
         bCrit = RollForCriticalHit(CritChanceOverride > 0 ? CritChanceOverride : WeaponData.CritChance)
         If bCrit: CurrentDamage *= CritMultiplierOverride > 0 ? CritMultiplierOverride : WeaponData.CritMultiplier
  └─► // Armor penetration (if target has armor system)
         If target has component:
             ArmorValue = target.GetArmorValue()
             CurrentDamage = CalculateArmorPenetration(CurrentDamage, ArmorValue)
         Else: Armor reduction not applied
  └─► // Weak spot
         If hit bone is weak spot:
             CurrentDamage = ApplyWeakSpotMultiplier(CurrentDamage, WeakSpotTag)
  └─► Populate FDamageResult
  └─► ApplyDamageToActor(Request.Instigator, Result)
  └─► OnDamageApplied(Result)
  └─► If target health <= 0: OnKillConfirmed(target)
  └─► Return Result
```

```
[ApplyDamageToActor]
  └─► If target implements I_Damageable:
         target.I_Damageable.ApplyDamage(Result)
  └─► Else:
         target.TakeDamage(Result.DamageDealt, DamageEvent, ...)
  └─► Return true if successfully applied
```

### Communications With

| Target | Method | Why |
|--------|--------|-----|
| [`I_Damageable`](../01-core/03_I_InterfaceLibrary.md) | Interface call | Primary damage path |
| [`BPC_HealthSystem`](../02-player/08_BPC_HealthSystem.md) | Get on Target | Direct health modify |
| [`BPC_CombatFeedbackComponent`](54_BPC_CombatFeedbackComponent.md) | Get from Weapon Owner | Damage numbers, hit confirmation |
| [`DA_WeaponData`](../14-data-assets/) | Direct read | Base damage, crit, falloff params |
| Analytics / Stats Tracker | Dispatcher | Damage tracking for stats |
| HUD | Dispatcher (via GM) | Damage numbers and death feed |

### Reuse Notes
- Pure calculation component — no visual or audio feedback
- Damage falloff is linear between start and end distance
- Armor penetration formula: `FinalDamage = Damage * (100 / (100 + ArmorValue))` (standard UE style)
- Weak spots are identified by bone name or gameplay tag on the target actor
- Dispatchers allow UI and feedback to react without coupling
- Renamed from `BPC_DamageHandlerComponent` to `BPC_DamageReceptionSystem` per Master naming convention.