UE5-Modular-Game-Framework/docs/blueprints/02-player/09_BPC_StaminaSystem.md

09 — Stamina System (BPC_StaminaSystem)

⚡ C++ Status: Stub — Source/PG_Framework/Public/Player/BPC_StaminaSystem.h provides the UCLASS shell, MaxStamina/CurrentStamina variables, and OnExhaustionStateChanged dispatcher. The C++ stub has NO gameplay logic. Create a BP child and build ALL logic: sprint drain, action costs, exhaustion state machine, regen delay + rate, CanAffordAction(Cost) query. See docs/developer/cpp-integration-guide.md.

---

Purpose

Manages the player's stamina pool — drain during sprinting, jumping, and special actions; regeneration during idle/walking. Prevents action spamming by enforcing minimum stamina thresholds. Drives exhaustion VFX and audio cues.

Dependencies

• Requires: GI_GameFramework (phase checks), FL_GameUtilities (tag queries)
• Required By: BPC_MovementStateSystem (stamina affects max speed), WBP_HUD (stamina bar), BPC_PlayerMetricsTracker (exhaustion tracking)
• Engine/Plugin Requirements: GameplayTags, Timers

Class Info

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

---

1. Enums

E_ExhaustionState

Value	Description
Normal = 0	Full stamina operation
Low = 1	Below LowThreshold, heavy breathing, slightly reduced regen delay
Exhausted = 2	Below ExhaustedThreshold, cannot sprint, slow regen

E_StaminaActionType

Value	Description
Sprint = 0	Continuous drain while sprinting
Jump = 1	One-time drain on jump
Climb = 2	Continuous drain while climbing
SpecialAttack = 3	One-time drain for strong melee
Dodge = 4	One-time drain for dodging
Environment = 5	Drain from external sources (cold, poison)

---

2. Structs

S_StaminaDrainRate

Field	Type	Description
ActionType	E_StaminaActionType	Which action this rate applies to
DrainPerSecond	Float	Stamina drained per second (continuous)
DrainFlat	Float	Stamina drained once per use (one-shot)
MinStamina	Float	Minimum stamina required to perform this action
CooldownAfterUse	Float	Seconds before this action can be used again

S_StaminaRegenSettings

Field	Type	Description
RegenRate	Float	Stamina recovered per second
RegenDelay	Float	Seconds after last drain before regen begins
ExhaustedRegenRate	Float	Slower recovery while exhausted
ExhaustedRegenDelay	Float	Longer delay while exhausted
RegenBlockedWhileMoving	Boolean	If true, regen pauses while moving above walk speed

---

3. Variables

Configuration (Instance Editable, Expose On Spawn)

Variable	Type	Default	Category	Description
MaxStamina	Float	100.0	Stamina Config	Maximum stamina pool
DefaultDrainRates	Array<S_StaminaDrainRate>	[]	Stamina Config	Base drain rates for each action type
RegenSettings	S_StaminaRegenSettings	(15.0, 2.0, 5.0, 4.0, true)	Stamina Config	Regeneration behaviour
LowThreshold	Float	0.30	Stamina Config	Fraction of MaxStamina for Low state
ExhaustedThreshold	Float	0.10	Stamina Config	Fraction of MaxStamina for Exhausted state
bCanExhaust	Boolean	true	Stamina Config	Allow exhaustion state

Internal (Private / Protected, No Expose)

Variable	Type	Default	Category	Description
CurrentStamina	Float	100.0	Stamina State	Current stamina pool
ExhaustionState	E_ExhaustionState	Normal	Stamina State	Current exhaustion tier
ActiveDrains	Map<E_StaminaActionType, bool>	{}	Stamina State	Which drains are currently active
RegenTimerHandle	FTimerHandle	-	Stamina State	Timer for regen ticks
DrainTimerHandle	FTimerHandle	-	Stamina State	Timer for continuous drain ticks
LastDrainTime	Float	0.0	Stamina State	World time of last stamina drain
bRegenBlocked	Boolean	false	Stamina State	True while external block is active
ActionCooldownTimers	Map<E_StaminaActionType, FTimerHandle>	{}	Stamina State	Per-action cooldown timers

Replicated (if multiplayer)

Variable	Type	Condition	Description
CurrentStamina	Float	RepNotify	Replicated with OnRep handler for UI updates
ExhaustionState	E_ExhaustionState	RepNotify	Replicated exhaustion tier

---

4. Functions

Public Functions

DrainStamina → Boolean (success)

• Description: Attempts to drain stamina for a specific action. Returns false if insufficient stamina or cooldown active.
• Parameters:

  Param	Type	Description
  ActionType	E_StaminaActionType	Which action is being performed
  OverrideAmount	Float	If > 0, use this instead of the DrainRate config value

• Blueprint Authority: Server (if MP), Any (single-player)
• Flow:
  1. If ActionCooldownTimers contains ActionType and timer active: return false
  2. Look up S_StaminaDrainRate for ActionType
  3. RequiredStamina = DrainRate.MinStamina
  4. If CurrentStamina < RequiredStamina: return false
  5. DrainAmount = OverrideAmount > 0 ? OverrideAmount : DrainRate.DrainFlat
  6. CurrentStamina = FMath::Max(0, CurrentStamina - DrainAmount)
  7. Start cooldown timer for DrainRate.CooldownAfterUse
  8. Update ExhaustionState
  9. Reset regen delay, stop regen if running
  10. Fire OnStaminaDrained
  11. If ActionType is continuous: add to ActiveDrains
  12. Fire OnStaminaChanged
  13. Return true

StartContinuousDrain → void

• Description: Begins draining stamina per second for a continuous action.
• Parameters:

  Param	Type	Description
  ActionType	E_StaminaActionType	Sprint, Climb, etc.

• Flow:
  1. Add ActionType to ActiveDrains = true
  2. If DrainTimerHandle not active: start timer with interval 0.1 seconds
  3. Timer callback: apply (DrainRate.DrainPerSecond * 0.1) to CurrentStamina each tick
  4. If CurrentStamina <= 0: stop continuous drain, fire OnExhausted

StopContinuousDrain → void

• Parameters:

  Param	Type	Description
  ActionType	E_StaminaActionType	Action to stop draining for

• Flow:
  1. Set ActiveDrains[ActionType] = false
  2. If no active drains remain: clear DrainTimerHandle
  3. Start regen delay timer

RestoreStamina → Float (actual restored)

• Description: Adds stamina up to MaxStamina.
• Parameters:

  Param	Type	Description
  Amount	Float	Stamina to restore
  Tags	GameplayTagContainer	Context tags (e.g. Potion, Rest)

• Flow:
  1. Previous = CurrentStamina
  2. CurrentStamina = FMath::Min(MaxStamina, CurrentStamina + Amount)
  3. Update ExhaustionState
  4. Fire OnStaminaRestored
  5. Fire OnStaminaChanged
  6. Return CurrentStamina - Previous

GetStaminaNormalised → Float [0.0 - 1.0]

• Flow: Return CurrentStamina / MaxStamina

CanAffordAction → Boolean

• Parameters:

  Param	Type	Description
  ActionType	E_StaminaActionType	Action to check

• Flow:
  1. Look up MinStamina for this ActionType
  2. Return CurrentStamina >= MinStamina AND no active cooldown

SetMaxStamina → void

• Parameters:

  Param	Type	Description
  NewMax	Float	New maximum value
  bMaintainRatio	Boolean	Scale current stamina to maintain ratio

• Flow:
  1. If bMaintainRatio: CurrentStamina = (CurrentStamina / MaxStamina) * NewMax
  2. Else: CurrentStamina = FMath::Min(CurrentStamina, NewMax)
  3. MaxStamina = NewMax
  4. Update ExhaustionState
  5. Fire OnStaminaChanged

BlockRegen → void

• Parameters:

  Param	Type	Description
  Duration	Float	Seconds to block regen

• Flow:
  1. Set bRegenBlocked = true
  2. Start timer for Duration
  3. On timer end: bRegenBlocked = false

Protected / Private Functions

UpdateExhaustionState → void

• Flow:
  1. Normalised = CurrentStamina / MaxStamina
  2. OldState = ExhaustionState
  3. If Normalised <= ExhaustedThreshold: NewState = Exhausted
  4. Else if Normalised <= LowThreshold: NewState = Low
  5. Else: NewState = Normal
  6. If NewState != OldState:
     • ExhaustionState = NewState
     • Fire OnExhaustionStateChanged
     • If NewState == Exhausted: fire OnExhausted

RegenTick → void

• Flow:
  1. If bRegenBlocked: return
  2. Rate = ExhaustionState == Exhausted ? RegenSettings.ExhaustedRegenRate : RegenSettings.RegenRate
  3. CurrentStamina = FMath::Min(MaxStamina, CurrentStamina + Rate * 0.1)
  4. Fire OnStaminaChanged
  5. If CurrentStamina >= MaxStamina: stop regen timer, fire OnStaminaFullyRestored

OnMovementStateChanged (listener) → void

• Flow:
  1. Get movement mode from character
  2. If RegenSettings.RegenBlockedWhileMoving and movement speed > walk:
     • Pause regen timer
  3. Else: resume regen timer if conditions met

---

5. Event Dispatchers

Dispatcher	Parameters	Bind Access	Description
OnStaminaChanged	float OldStamina, float NewStamina, float Delta	Public	Fired on any stamina change
OnStaminaDrained	E_StaminaActionType ActionType, float Amount	Public	Fired when stamina is consumed
OnStaminaRestored	float Amount, GameplayTagContainer Tags	Public	Fired when stamina is gained
OnStaminaFullyRestored	none	Public	Fired when stamina reaches MaxStamina
OnExhaustionStateChanged	E_ExhaustionState OldState, E_ExhaustionState NewState	Public	Fired on any exhaustion tier change
OnExhausted	none	Public	Fired when entering Exhausted state
OnActionCooldownStarted	E_StaminaActionType ActionType, float Cooldown	Public	Fired when a per-action cooldown begins
OnActionCooldownEnded	E_StaminaActionType ActionType	Public	Fired when a per-action cooldown expires

---

6. Overridden Events / Custom Events

Event: BeginPlay

• Description: Initialises stamina, starts regen if enabled, binds to movement state changes.
• Flow:
  1. CurrentStamina = MaxStamina
  2. Start regen timer with initial delay = 0
  3. Find BPC_MovementStateSystem on owner, bind to its OnMovementStateChanged dispatcher
  4. Initialise ExhaustionState = Normal

Event: OnComponentDestroyed

• Description: Clean up all timers.
• Flow:
  1. Clear RegenTimerHandle, DrainTimerHandle
  2. Clear all ActionCooldownTimers

---

7. Blueprint Graph Logic Flow

flowchart TD
    A[DrainStamina called] --> B{CanAffordAction?}
    B -->|No| C[Return false]
    B -->|Yes| D[Apply drain amount]
    D --> E[Update CurrentStamina]
    E --> F{ExhaustedThreshold crossed?}
    F -->|Yes| G[Set Exhausted state]
    F -->|No| H{LowThreshold crossed?}
    H -->|Yes| I[Set Low state]
    H -->|No| J[Keep Normal state]
    G --> K[Fire OnExhausted]
    K --> L[Stop continuous drains]
    I --> M[Fire OnExhaustionStateChanged]
    J --> M
    L --> M
    M --> N[Start regen delay]
    N --> O[Fire OnStaminaChanged]
    O --> P[Return true]
    D --> Q{Continuous action?}
    Q -->|Yes| R[Start DrainTimer loop]
    Q -->|No| S[Start action cooldown]
    R --> O
    S --> O

---

8. Communication Matrix

Who Talks	How	What Is Sent
BPC_StaminaSystem	Dispatcher	OnStaminaChanged -> WBP_HUD (stamina bar update)
BPC_StaminaSystem	Dispatcher	OnExhausted -> BPC_PlayerController (player feedback), BPC_AdaptiveEnvironment
BPC_StaminaSystem	Dispatcher	OnExhaustionStateChanged -> ABP_GASP (breathing animation)
External (PC_PlayerController)	Direct	Calls DrainStamina(Sprint) / StartContinuousDrain on input
BPC_StaminaSystem	Dispatcher	OnStaminaFullyRestored -> WBP_HUD (hide bar)
BPC_StaminaSystem	Listener	Binds to BPC_MovementStateSystem.OnMovementStateChanged for regen blocking

---

9. Validation / Testing Checklist

• DrainStamina deducts correct amount and returns false when stamina is insufficient
• Continuous drain stops when stamina reaches 0
• Regen does not start until RegenDelay has passed
• Exhausted state correctly uses ExhaustedRegenRate and ExhaustedRegenDelay
• Exhaustion state transitions are one-way downward until full rest
• Per-action cooldowns prevent spamming dodge/jump
• BlockRegen pauses all regen for its duration
• RegenBlockedWhileMoving pauses regen at high speed, resumes when walking
• Edge case: MaxStamina change with bMaintainRatio=true preserves percentage
• Edge case: Multiple simultaneous continuous drains stack correctly
• Edge case: DrainStamina called during active cooldown returns false without state change
• All timers cleaned up on component destroy

---

10. Reuse Notes

• Can be placed on AI characters with simplified config (e.g. only Sprint drain, no Exhaustion).
• For enemy stamina, consider removing the exhaustion mechanic and using only drain/restore.
• The drain rate map supports runtime modification for buffs/debuffs (e.g. Adrenaline reduces sprint cost).
• UI widgets should bind to OnStaminaChanged for smooth bar animation, not tick polling.
• For multiplayer: Server authorises all DrainStamina calls; client predicts and corrects on repnotify.

---

11. Multiplayer Networking (Expanded)

Server RPCs

RPC	Direction	Description
Server_DrainStamina	Client→Server	Client requests stamina drain for action. Server validates MinStamina, applies.
Server_StartContinuousDrain	Client→Server	Client starts sprinting. Server begins drain timer.
Server_StopContinuousDrain	Client→Server	Client stops sprinting. Server stops drain, begins regen.
Server_RestoreStamina	Client→Server	Client uses stamina item. Server validates item, applies restore.

Authority Gates

Function DrainStamina(ActionType)
  If HasAuthority:
    → Check cooldown, MinStamina
    → Apply drain, update exhaustion, fire dispatchers
  Else:
    → Client predicts stamina bar decrease for responsiveness
    → Server_ RPC called; server corrects via OnRep if wrong

Function SetMaxStamina(NewMax, bMaintainRatio)
  If NOT HasAuthority → Return
  → Apply change, fire dispatchers, auto-replicates

Client Prediction

• Stamina bar: Client predicts decrease on sprint/jump. Server corrects via OnRep_CurrentStamina.
• Exhaustion: ExhaustionState replicated. Client plays breathing audio locally.
• Cooldowns: Server-authoritative. Client shows cooldown timer after server confirms action.
• Exhaustion state can drive conditional audio: heavy breathing, heart-beat, fatigue voice lines.

---

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