UE5-Modular-Game-Framework/docs/blueprints/02-player/08_BPC_HealthSystem.md

08 — Health System (BPC_HealthSystem)

⚡ C++ Status: Stub — Source/PG_Framework/Public/Player/BPC_HealthSystem.h provides the UCLASS shell, MaxHealth/CurrentHealth variables, OnHealthChanged and OnDeath event dispatchers. The C++ stub has NO gameplay logic — it exists so other C++ classes (BPC_StateManager, BPC_DamageReceptionSystem) can forward-reference it. Create a BP child and build ALL logic from this spec: TakeDamage(), Heal(), OnDeath() transition, damage resistance modifiers, health regen tick, I_Damageable interface. See docs/developer/cpp-integration-guide.md for setup steps.

---

Purpose

Manages the player's health pool, damage application with type-based resistance, health regeneration, death state, and critical-health events. Serves as the central survivability component on the player character.

Dependencies

• Requires: FL_GameUtilities (for safe interface casts), I_Damageable (interface on the owner), GI_GameFramework (for GamePhase queries)
• Required By: BPC_StressSystem (health below threshold triggers fear events), BPC_PlayerMetricsTracker (death tracking), WBP_HUD (health bar), AI_EnemyController (player health as awareness trigger), BPC_InteractionDetector (low-health checks)
• Engine/Plugin Requirements: GameplayTags, DeveloperSettings

Class Info

Property	Value
Parent Class	ActorComponent
Class Type	Blueprint Component
Asset Path	Content/Framework/Player/BPC_HealthSystem
Implements Interfaces	I_Damageable

---

1. Enums

E_DamageType

Value	Description
Physical = 0	Bullets, blunt force, falls
Arcane = 1	Magic, curse, psychic damage
Fire = 2	Burning, environmental heat
Poison = 3	Toxins, venom, chemical
Fear = 4	Psychological damage (stress overflow)
Environmental = 5	Traps, crushing, drowning
True = 6	Bypasses all resistances, no reduction

E_DeathState

Value	Description
Alive = 0	Normal gameplay
Dying = 1	Downed state, waiting for recovery or final death
Dead = 2	Character is dead, no further actions possible
PermaDeath = 3	Save-scrubbing locked, forced reload

---

2. Structs

S_DamageEvent

Field	Type	Description
BaseAmount	Float	Raw damage before resistance
DamageType	E_DamageType	Category of damage
Instigator	Actor	Who caused the damage
HitLocation	Vector	World location of impact
DamageTags	GameplayTagContainer	Additional contextual tags
bIsCriticalHit	Boolean	True if this is a headshot / weak-point hit
SourceDescription	Text	Human-readable source (for log / UI)

S_DamageResistance

Field	Type	Description
DamageType	E_DamageType	Type this resistance applies to
Multiplier	Float	1.0 = normal, 0.5 = half damage, 2.0 = double
bIsStackable	Boolean	Can this resistance stack with others?

---

3. Variables

Configuration (Instance Editable, Expose On Spawn)

Variable	Type	Default	Category	Description
MaxHealth	Float	100.0	Health Config	Maximum hit points
bRegenEnabled	Boolean	true	Health Config	Allow passive health regeneration
RegenDelay	Float	3.0	Health Config	Seconds after last damage before regen starts
RegenRate	Float	2.0	Health Config	HP recovered per second during regen
RegenDelayUntil	Float	0.0	Health Config	World time when regen can resume
CriticalHealthPercent	Float	0.25	Health Config	Below this fraction of MaxHealth, fire critical event
DefaultResistances	Array<S_DamageResistance>	[]	Health Config	Base damage resistances for this character
bEnableFriendlyFire	Boolean	false	Health Config	Can the player damage themselves?

Internal (Private / Protected, No Expose)

Variable	Type	Default	Category	Description
CurrentHealth	Float	100.0	Health State	Current HP, clamped [0..MaxHealth]
DeathState	E_DeathState	Alive	Health State	Current death state
ActiveDamageOverTime	Map<FName, FTimerHandle>	{}	Health State	Active DoT timers keyed by source name
InvincibilityTimer	FTimerHandle	-	Health State	Timer handle for temporary invincibility
RegenTimerHandle	FTimerHandle	-	Health State	Timer handle for regen tick
bIsInvincible	Boolean	false	Health State	True during invincibility window
LastDamageInstigator	Actor	None	Health State	Most recent damage source (for kill credit)
LastDamageTime	Float	0.0	Health State	World time of last damage taken

Replicated (if multiplayer)

Variable	Type	Condition	Description
CurrentHealth	Float	RepNotify	Replicated with OnRep handler for UI updates
DeathState	E_DeathState	RepNotify	Replicated death state

---

4. Functions

Public Functions

ApplyDamage → S_DamageResult (custom struct)

• Description: Applies damage to the health pool after resistance calculation. Returns effective damage and any side effects.
• Parameters:

  Param	Type	Description
  DamageEvent	S_DamageEvent	The damage event to process

• Blueprint Authority: Server (if MP), Any (single-player)
• Flow:
  1. Early-out if DeathState is Dead or bIsInvincible
  2. Calculate effective damage from BaseAmount * type resistances
  3. If damage > 0: reset RegenDelay timer, update CurrentHealth
  4. Fire OnDamageTaken dispatcher
  5. If CurrentHealth <= 0: call HandleDeath
  6. If CurrentHealth <= CriticalHealthPercent: fire OnHealthCritical
  7. Return damage result struct

ApplyHealing → Float (effective healing)

• Description: Adds health up to MaxHealth. Returns the amount actually healed.
• Parameters:

  Param	Type	Description
  HealAmount	Float	Raw healing value
  HealTags	GameplayTagContainer	Contextual tags

• Blueprint Authority: Server (if MP), Any (single-player)
• Flow:
  1. Early-out if DeathState is Dead
  2. Clamp: CurrentHealth = FMath::Min(MaxHealth, CurrentHealth + HealAmount)
  3. Fire OnHealthChanged
  4. Return actual heal amount

GetHealthNormalised → Float [0.0 - 1.0]

• Description: Returns NormalisedCurrentHealth for UI widgets.
• Flow: Return CurrentHealth / MaxHealth

SetMaxHealth → void

• Description: Changes MaxHealth and optionally heals to match new ratio or clamps current.
• Parameters:

  Param	Type	Description
  NewMax	Float	New maximum health value
  bMaintainRatio	Boolean	If true, scale CurrentHealth to same ratio

• Flow:
  1. Clamp NewMax to >= 1.0
  2. If bMaintainRatio: CurrentHealth = (CurrentHealth / MaxHealth) * NewMax
  3. Else: CurrentHealth = FMath::Min(CurrentHealth, NewMax)
  4. Set MaxHealth = NewMax
  5. Fire OnHealthChanged

KillInstant → void

• Description: Bypasses all resistances, immediately sets health to 0 and triggers death.
• Parameters:

  Param	Type	Description
  Instigator	Actor	Who caused the kill
  DeathReason	FText	Reason displayed on death screen

• Blueprint Authority: Server (if MP), Any (single-player)
• Flow:
  1. Set CurrentHealth = 0
  2. Set DeathState = Dying
  3. Fire OnHealthChanged with CurrentHealth = 0
  4. Call HandleDeath with bInstant = true

ApplyDamageOverTime → void

• Description: Applies periodic damage with tick interval and total duration.
• Parameters:

  Param	Type	Description
  DamagePerTick	Float	Damage applied each interval
  TickInterval	Float	Seconds between ticks
  TotalDuration	Float	Total seconds the DoT lasts
  DamageType	E_DamageType	Type of each damage tick
  SourceName	FName	Unique name to prevent stacking same DoT
  Instigator	Actor	Who applied the DoT

• Flow:
  1. If SourceName already exists in ActiveDamageOverTime, clear existing timer
  2. Create a Timer by Event with loop = TickInterval
  3. On each tick: build S_DamageEvent, call ApplyDamage
  4. After TotalDuration: clear timer, remove from ActiveDamageOverTime

IsAlive → Boolean

• Flow: Return DeathState == Alive

AddResistance → void

• Parameters:

  Param	Type	Description
  NewResistance	S_DamageResistance	Resistance to add or update

• Flow: If resistance for this DamageType exists, update Multiplier; if not, add to array.

RemoveResistance → void

• Parameters:

  Param	Type	Description
  DamageType	E_DamageType	Type to remove

• Flow: Remove all entries matching this DamageType from resistance array.

Protected / Private Functions

HandleDeath → void

• Description: Internal death processing. Sets state, fires dispatchers, notifies GameMode.
• Parameters:

  Param	Type	Description
  bInstant	Boolean	If true, skip dying state go straight to dead

• Flow:
  1. Set DeathState = (bInstant ? Dead : Dying)
  2. Clear all timers (regen, DoT, invincibility)
  3. Fire OnDeath with DeathState
  4. Call I_Damageable::OnOwnerDied on owner if interface exists
  5. Get GM_CoreGameMode via GetWorld()->GetAuthGameMode()
  6. Call GM_CoreGameMode::HandlePlayerDead(LastDamageInstigator)

RegenTick → void

• Description: Timer callback — applies one tick of regeneration.
• Flow:
  1. If CurrentHealth >= MaxHealth: stop regen timer, return
  2. CurrentHealth = FMath::Min(MaxHealth, CurrentHealth + RegenRate * TickInterval)
  3. Fire OnHealthChanged
  4. If CurrentHealth >= MaxHealth: stop regen timer

---

5. Event Dispatchers

Dispatcher	Parameters	Bind Access	Description
OnHealthChanged	float OldHealth, float NewHealth, float Delta	Public	Fired when health changes by any amount
OnDamageTaken	S_DamageEvent DamageEvent, float EffectiveDamage	Public	Fired each time damage is applied
OnHealingReceived	float HealAmount, GameplayTagContainer HealTags	Public	Fired each time healing is applied
OnHealthCritical	float CurrentHealth, float MaxHealth	Public	Fired when health drops below critical threshold
OnDeath	E_DeathState DeathState, Actor Instigator	Public	Fired when character dies or enters dying state
OnDeathStateChanged	E_DeathState OldState, E_DeathState NewState	Public	Fired on any death state transition
OnInvincibilityChanged	bool bIsInvincible	Public	Fired when invincibility state toggles

---

6. Overridden Events / Custom Events

Event: BeginPlay

• Description: Initializes health, loads saved health if persisting, starts regen timer if enabled.
• Flow:
  1. Set CurrentHealth = MaxHealth
  2. Check if owner implements I_Persistable
  3. If yes, try to load saved health value
  4. If bRegenEnabled: start regen timer with initial delay = 0
  5. Bind to any relevant GamePhase change dispatchers

Event: OnComponentDestroyed

• Description: Clean up all active timers.
• Flow:
  1. Clear all TimerHandles (Invincibility, Regen, all DoT timers)
  2. Clear ActiveDamageOverTime map

Custom Event: ApplyTemporaryInvincibility

• Parameters: float Duration
• Description: Grants brief invincibility, often used after respawn or dodge.
• Flow:
  1. Set bIsInvincible = true
  2. Fire OnInvincibilityChanged(true)
  3. Start timer for Duration
  4. On timer end: set bIsInvincible = false, fire OnInvincibilityChanged(false)

---

7. Blueprint Graph Logic Flow

flowchart TD
    A[ApplyDamage called] --> B{DeathState == Dead?}
    B -->|Yes| C[Return 0 damage]
    B -->|No| D{bIsInvincible?}
    D -->|Yes| C
    D -->|No| E[Calculate resistance multiplier]
    E --> F[EffectiveDamage = Base * Multiplier]
    F --> G[CurrentHealth -= EffectiveDamage]
    G --> H[Reset RegenDelay timer]
    H --> I[Fire OnDamageTaken]
    I --> J{CurrentHealth <= 0?}
    J -->|Yes| K[HandleDeath]
    J -->|No| L{CurrentHealth <= CriticalThreshold?}
    L -->|Yes| M[Fire OnHealthCritical]
    L -->|No| N[Fire OnHealthChanged]
    K --> O[Fire OnDeath dispatcher]
    K --> P[Notify GameMode: HandlePlayerDead]
    K --> Q[Clear all timers]
    M --> N

---

8. Communication Matrix

Who Talks	How	What Is Sent
BPC_HealthSystem	Dispatcher	OnHealthChanged -> WBP_HUD, BPC_StressSystem
BPC_HealthSystem	Dispatcher	OnDeath -> GM_CoreGameMode, SS_SaveSystem, BPC_PlayerMetricsTracker
BPC_HealthSystem	Dispatcher	OnDamageTaken -> BPC_StressSystem, BPC_AdaptiveEnvironment
BPC_HealthSystem	Interface	I_Damageable.Execute_ApplyDamage route
BPC_HealthSystem	Interface	I_Persistable for save/load of CurrentHealth
External (Weapons, Traps)	Interface	I_Damageable -> ApplyDamage
BPC_HealthSystem	Direct	GM_CoreGameMode.HandlePlayerDead on death
BPC_HealthSystem	Subsystem	GI_GameFramework.GetGamePhase for phase-restricted actions

---

9. Validation / Testing Checklist

• ApplyDamage with all E_DamageType values produces correct resistance-modified damage
• Health never drops below 0 or exceeds MaxHealth
• Regeneration does not start while RegenDelay timer is active
• Regeneration stops when health reaches MaxHealth
• Death sets DeathState properly and fires OnDeath exactly once
• Temporary invincibility blocks all damage for its duration
• Damage-over-time correctly applies ticks and cleans up timer on death
• Critical health event fires only when crossing below threshold from above
• Edge case: ApplyHealing on a dead character returns 0 with no dispatchers
• Edge case: ApplyDamage with negative BaseAmount is treated as 0
• Edge case: Multiple simultaneous DoT sources with same SourceName do not stack
• All dispatchers are cleaned up on component destroy

---

10. Reuse Notes

• This component can be used on AI characters and enemy pawns by exposing the same configuration variables.
• For enemies, consider disabling regen (bRegenEnabled = false) unless a specific healing mechanic exists.
• The resistance system supports temporary buffs via AddResistance / RemoveResistance at runtime.
• If implementing a downed / bleeding state, extend E_DeathState with custom values and add a recovery timer check in HandleDeath.
• Damage numbers displayed as floating text should bind to OnDamageTaken.
• For multiplayer: all ApplyDamage logic runs on Server; clients receive repnotified CurrentHealth and fire local cosmetic dispatchers only.

---

11. Multiplayer Networking (Expanded)

Replicated Variables (Existing + New)

Variable	Type	Condition	Description
CurrentHealth	Float	Replicated Using OnRep_CurrentHealth	Clients sync via OnRep → dispatcher
DeathState	E_DeathState	Replicated Using OnRep_DeathState	Death state synced; OnRep triggers death effects
bIsInvincible	Boolean	Replicated	Invincibility visible to other players
MaxHealth	Float	Replicated	Synced for UI percentage calculations

Server RPCs

RPC	Direction	Description
Server_ApplyDamage	Client→Server	Client reports taking damage. Server validates source, range, damage type.
Server_ApplyHealing	Client→Server	Client requests healing. Server validates heal source, applies.
Server_KillInstant	Client→Server	Only accepted from authoritative sources (GM, traps). Client calls are rejected.

Authority Gates

Function ApplyDamage(DamageEvent)
  Switch HasAuthority
    Authority:
      → Calculate resistance, apply damage, fire dispatchers
    Remote:
      → Return (clients never modify health directly)
      → Server_ApplyDamage is called by damage source (weapon/trap), not victim

Function ApplyHealing(HealAmount)
  Switch HasAuthority
    Authority:
      → Apply healing, fire dispatchers
    Remote:
      → Return
      → Consumable use calls Server_UseConsumable → server calls ApplyHealing

Client Prediction

• Health bar: Client predicts damage flash on hit; server-corrected value arrives via OnRep_CurrentHealth.
• Death: No prediction. OnRep_DeathState triggers all death effects (screen fade, ragdoll).
• Healing: Client shows green flash immediately + predicted health; server corrects within one RTT.
• Invincibility: Visual effect (shield shimmer) is local cosmetic; state is replicated.

OnRep Handlers

OnRep_CurrentHealth()
  → Broadcast OnHealthChanged(OldHealth, CurrentHealth, Delta)
  → UI updates identically to single-player path

OnRep_DeathState()
  → Broadcast OnDeathStateChanged(OldState, NewState)
  → If Dead: play death animation, screen effects, notify GM

Anti-Cheat

• Server validates all Server_ApplyDamage calls: check instigator range, weapon fire rate, damage type validity.
• Server never trusts DamageEvent.BaseAmount from client — always recalculates from weapon data.
• Server_KillInstant is only callable from server-authoritative systems (traps, death zones, GM).

---

Blueprint Spec: Health System. Conforms to TEMPLATE.md v1.0 — part of the UE5 Modular Game Framework.