BPC_DeathHandlingSystem — Actor Component (Death Orchestrator)

File: Content/Framework/Save/BPC_DeathHandlingSystem

Purpose: The single authority for the player death flow. Determines the death outcome (standard respawn, game over, or alt death space), manages the death animation/camera sequence, coordinates corpse persistence, tracks run history, and triggers respawn. Sits on the Player Controller alongside four sub-systems that each handle one death-related concern.

Depends On: SS_SaveManager, BP_Checkpoint, BPC_HealthSystem, GM_CoreGameMode, BPC_AltDeathSpaceSystem, BPC_PersistentCorpseSystem, BPC_PlayerRespawnSystem, BPC_RunHistoryTracker Used By: Player Controller (spawned by GM_CoreGameMode)

Enums

// E_DeathOutcome — Determined by game rules + player state at death moment
E_DeathOutcome
{
  StandardRespawn,   // Normal death at a checkpoint — full respawn
  GameOver,          // No respawn possible — screen shows game over / main menu
  AltDeathSpace      // Player enters the limbo / between-world death space
}

// E_DeathAnimationStage — Controls the death anim sequence timeline
E_DeathAnimationStage
{
  PreDeath,          // Brief pause before death anim (player can see the killer)
  DeathAnim,         // Death animation playing (screen fade, camera pull back)
  PostDeath,         // Screen fully dark, system state being evaluated
  RespawnTransition  // Fade-up to respawn location
}

Structs

// S_DeathContext — Captured at the moment of death for all sub-systems
S_DeathContext
{
  DeathLocation:      Vector       // World location where health hit 0
  KillerTag:          GameplayTag  // What caused the death (DamageType.Tag)
  bIsInHidingSpot:    Bool         // Was the player hiding when killed?
  bWasFearCritical:   Bool         // Was stress/fear at critical level?
  DeathTimestamp:     FDateTime    // UTC timestamp
  DeathCount:         Integer      // Running total (from BPC_PlayerMetricsTracker)
  CurrentCheckpoint:  GameplayTag  // Most recent checkpoint at death
  bHasAltDeathSpace:  Bool         // Can this death use alt death space?
}

// S_DeathOutcomeRules — Configurable rules for determining death outcome
S_DeathOutcomeRules
{
  bEnableAltDeathSpace:      Bool    // Master toggle for alt death space feature
  MaxStandardDeaths:         Integer // After X standard deaths, force GameOver
  MaxAltDeathSpaceEntrances: Integer // After Y alt space entrances, force GameOver
  AltDeathSpaceCheckpoint:   GameplayTag  // Which checkpoint to respawn to after alt space
  bGameOverOnBossDeath:      Bool    // Boss kills always trigger game over
  bGameOverInNarrativeClimax:Bool    // Death at narrative climax = game over
}

Core Component Variables (BPC_DeathHandlingSystem)

Name	Type	Description
`DeathContext`	`S_DeathContext`	Captured at death moment; used by all sub-systems
`OutcomeRules`	`S_DeathOutcomeRules`	Configurable rules for outcome determination
`CurrentOutcome`	`E_DeathOutcome`	The determined death outcome
`AnimStage`	`E_DeathAnimationStage`	Current stage of the death animation sequence
`bIsDying`	Bool	True from death trigger until full respawn
`bIsRespawning`	Bool	True during the respawn process
`ActiveAltDeathSpaceSystem`	BPC_AltDeathSpaceSystem	Reference to sub-system component (must be on same actor)
`ActiveCorpseSystem`	BPC_PersistentCorpseSystem	Reference to sub-system component
`ActiveRespawnSystem`	BPC_PlayerRespawnSystem	Reference to sub-system component
`ActiveRunHistory`	BPC_RunHistoryTracker	Reference to sub-system component

Core Functions (BPC_DeathHandlingSystem)

Name	Inputs	Outputs	Description
`OnPlayerDeath`	KillerTag: GameplayTag, DamageAmount: Float	—	Entry point — called by BPC_HealthSystem when HP reaches 0
`DetermineDeathOutcome`	Context: S_DeathContext	E_DeathOutcome	Evaluates rules to decide StandardRespawn / GameOver / AltDeathSpace
`ExecuteDeathSequence`	Outcome: E_DeathOutcome	—	Drives the full death animation timeline
`ExecuteStandardRespawn`	Context: S_DeathContext	—	Saves death state, runs respawn via BPC_PlayerRespawnSystem
`ExecuteGameOver`	Context: S_DeathContext	—	Saves run history, triggers game over UI, disables input
`ExecuteAltDeathSequence`	Context: S_DeathContext	—	Spawns corpse, enters alt death space via BPC_AltDeathSpaceSystem
`AbortDeathSequence`	—	—	Cancels death flow (for debug / dev cheats)

Blueprint Flow Diagram

flowchart TD
    A[BPC_HealthSystem: HP = 0] --> B[Capture S_DeathContext]
    B --> C[Broadcast OnPlayerDeath]
    C --> D[BPC_DeathHandlingSystem.OnPlayerDeath]
    D --> E[DetermineDeathOutcome]
    
    E --> F{Outcome?}
    
    F -->|StandardRespawn| G[DeathAnimStage = DeathAnim]
    G --> H[Spawn corpse via BPC_PersistentCorpseSystem]
    H --> I[SS_SaveManager.SaveDeathState]
    I --> J[DeathAnimStage = PostDeath]
    J --> K[Delay RespawnDelay seconds]
    K --> L[BPC_PlayerRespawnSystem.RespawnPlayer]
    L --> M[DeathAnimStage = RespawnTransition]
    M --> N[Fade in at checkpoint location]
    N --> O[ApplyRespawnState]
    O --> P[DeathAnimStage = null]
    P --> Q[Broadcast OnRespawnCompleted]
    
    F -->|AltDeathSpace| R[DeathAnimStage = DeathAnim]
    R --> S[Spawn corpse via BPC_PersistentCorpseSystem]
    S --> T[SS_SaveManager.SaveDeathState]
    T --> U[BPC_AltDeathSpaceSystem.EnterAltDeathSpace]
    U --> V[Set exit portal to current checkpoint]
    V --> W[DeathAnimStage = null]
    W --> X[Player wanders alt space]
    X --> Y{Exit condition met?}
    Y -->|Optional: find exit portal| Z[BPC_AltDeathSpaceSystem.ExitAltDeathSpace]
    Y -->|Timer expired| AA[BPC_AltDeathSpaceSystem.ExitAltDeathSpace]
    Z --> AB[Respawn at exit portal transform]
    AA --> AB
    AB --> AC[ApplyRespawnState]
    AC --> AD[Broadcast OnRespawnCompleted]
    
    F -->|GameOver| AE[DeathAnimStage = PostDeath]
    AE --> AF[BPC_RunHistoryTracker.EndRun]
    AF --> AG[Disable player input]
    AG --> AH[Show Game Over screen]
    AH --> AI[Offer: Load / Main Menu / Quit]

Communication Matrix

Target System	Method	Why
`BPC_HealthSystem`	Dispatcher bind (HP reached 0)	Receives death trigger
`SS_SaveManager`	Direct call `SaveDeathState` / `LoadDeathState`	Saves/loads death state for continuity
`BP_Checkpoint`	Direct call `GetRespawnTransform`	Gets respawn location
`BP_Checkpoint`	Direct call `OnPlayerDeath` / `OnPlayerRespawn`	Notifies checkpoint system of death cycle
`GM_CoreGameMode`	Dispatcher `OnPlayerDeath` / `OnRespawnCompleted`	Game mode tracks death flow for game phase
`GS_CoreGameState`	Direct set `CurrentGamePhase` = GameOver	Game state reflects game over condition
`PC_PlayerController`	SetIgnoreMoveInput / SetIgnoreLookInput	Disable input during death sequence
`WBP_GameOverScreen`	Dispatcher via GM or direct	Show game over UI
`WBP_DeathScreen`	Dispatcher `OnPlayerDeath`	Show death animation overlay
`WBP_RunSummary`	Function `GetRunSummary`	Display death recap on game over
`BPC_PlayerMetricsTracker`	Read `DeathCount`	Include in death context
`I_Persistable` corpse actors	Register/unregister with `SS_SaveManager`	Corpse persistence

Reuse Notes

All five sub-systems (DeathHandling, AltDeathSpace, Corpse, Respawn, RunHistory) sit on the same actor — the Player Controller
The death outcome determination (S_DeathOutcomeRules) can be swapped per-level or per-chapter via DA_LevelConfig
Corpse persistence across saves requires the corpse actor to implement I_Persistable
Alt death space levels are loaded via UGameplayStatics::LoadStreamLevel and must be in the persistent level's Streaming Levels list
Run history is session-only and NOT serialised — it resets on game restart
AbortDeathSequence is useful for debug cheats: GodMode or RespawnNow console commands
For multiplayer, the server must be the authority: all death trigger logic should run on the server via HasAuthority()

8.5 KiB Raw Blame History