UE5-Modular-Game-Framework/docs/blueprints/08-weapons/72_BPC_DamageReceptionSystem.md

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 — Interface on damage targets
• BP_WeaponBase — Owner weapon (optional)
• BPC_HealthSystem — Damage recipient
• BPC_CombatFeedbackComponent — Damage FX forwarding
• DA_WeaponData — 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	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, 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	Interface call	Primary damage path
BPC_HealthSystem	Get on Target	Direct health modify
BPC_CombatFeedbackComponent	Get from Weapon Owner	Damage numbers, hit confirmation
DA_WeaponData	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.