UE5-Modular-Game-Framework/docs/game/playercharacter.md

Player Character — BP_HorrorPlayerCharacter

Game: Project Void | Asset: BP_HorrorPlayerCharacter | Parent: GASP-based Character Asset Path: Content/Game/Characters/BP_HorrorPlayerCharacter.uasset Build Phase: 4 | Demonstrates: All 02-player systems (08-15) + 03-interaction (16) + 04-inventory (26,28,30,31,34) + 08-weapons (70,71,72) + 16-state (130)

---

Purpose

The player's physical embodiment in the game world. A GASP-based first-person character with all framework components attached. This is the single most important game asset — nearly every framework system interacts with it.

---

Architecture Overview

BP_HorrorPlayerCharacter (Character with GASP Animation Blueprint)
├── Components (auto-attached on spawn)
│   ├── CapsuleComponent (inherited)
│   ├── CameraComponent (first-person, head socket)
│   ├── CharacterMovementComponent (GASP — read-only)
│   ├── SkeletalMeshComponent (GASP — read-only)
│   │
│   ├── [02-player] BPC_HealthSystem            # 08 — Health, damage, death
│   ├── [02-player] BPC_StaminaSystem           # 09 — Sprint, action drain
│   ├── [02-player] BPC_StressSystem            # 10 — Psychological stress
│   ├── [02-player] BPC_MovementStateSystem     # 11 — Walk/Sprint/Crouch
│   ├── [02-player] BPC_HidingSystem            # 12 — Hide in lockers/beds
│   ├── [02-player] BPC_EmbodimentSystem        # 13 — First-person body
│   ├── [02-player] BPC_CameraStateLayer        # 14 — FOV/offset layers
│   ├── [02-player] BPC_PlayerMetricsTracker    # 15 — Accuracy, style
│   │
│   ├── [03-interaction] BPC_InteractionDetector # 16 — Raycast interact
│   │
│   ├── [04-inventory] BPC_InventorySystem      # 31 — Inventory grid
│   ├── [04-inventory] BPC_EquipmentSlotSystem  # 30 — Weapon/tool slots
│   ├── [04-inventory] BPC_ActiveItemSystem     # 26 — Quick-slot cycling
│   ├── [04-inventory] BPC_ConsumableSystem     # 28 — Use medkits/etc
│   ├── [04-inventory] BPC_KeyItemSystem        # 34 — Key items
│   ├── [04-inventory] BPC_JournalSystem        # 33 — Objectives
│   ├── [04-inventory] BPC_CollectibleTracker   # 27 — Collectibles found
│   ├── [04-inventory] BPC_DocumentArchiveSystem# 29 — Read documents
│   ├── [04-inventory] BPC_ItemCombineSystem    # 32 — Combine items
│   │
│   ├── [08-weapons] BPC_AmmoComponent          # 70 — Ammo pool
│   ├── [08-weapons] BPC_RecoilSystem           # 77 — Weapon recoil
│   ├── [08-weapons] BPC_HitReactionSystem      # 75 — Hit flinch
│   ├── [08-weapons] BPC_DamageReceptionSystem  # 72 — Receive damage
│   ├── [08-weapons] BPC_CombatFeedbackComponent# 71 — Hit markers
│   │
│   ├── [16-state] BPC_StateManager             # 130 — Action gating
│   │
│   ├── [07-narrative] BPC_NarrativeStateSystem # 58 — Narrative flags
│   ├── [07-narrative] BPC_ObjectiveSystem      # 59 — Active quests
│   └── [07-narrative] BPC_EndingAccumulator    # 68 — Ending tracker
│
├── Interfaces Implemented
│   ├── I_Damageable (take damage)
│   ├── I_Interactable (can be interacted with by NPCs)
│   └── I_Persistable (save/load state)

---

Creation Steps

Step 1 — Create Blueprint

Content Browser → Game/Characters/
  Right-click → Blueprint Class
  Parent Class: Your GASP Character (or Character if GASP is added to ABP only)
  Name: BP_HorrorPlayerCharacter

Step 2 — Add All Components

In the Components panel, add each component from the list above. Order doesn't matter for Blueprint components — they auto-initialize on BeginPlay.

Tip: Create a Blueprint function InitializeAllComponents called from Event BeginPlay and verify every component is valid before proceeding.

Step 3 — Configure GASP Integration

[GASP Animation Blueprint Setup]
   │
   ├─ Assign GASP AnimBP to SkeletalMeshComponent → Anim Class
   │    └─ Default: ABP_GASP (read-only, do not modify)
   │
   ├─ [GASP Notifies] (extend via Animation Notify overrides, NOT by editing GASP)
   │    └─ Add AnimNotify slots to GASP montages in your ABP child:
   │         ├─ Notify_Footstep → BPC_MovementStateSystem.OnFootstep()
   │         ├─ Notify_EnterAction → BPC_StateManager.EnterAction(Tag)
   │         ├─ Notify_ExitAction → BPC_StateManager.ExitAction()
   │         ├─ Notify_DamageApplied → BPC_DamageReceptionSystem.ReceiveDamage()
   │         └─ (etc — see animation-catalog.md for all 14 notifies)
   │
   └─ [Motion Matching Database]
        └─ Assign your motion matching pose search database
           (GASP handles locomotion blend — you provide the poses)

Step 4 — Wire Event BeginPlay

Event BeginPlay
   │
   ├─ Parent: Event BeginPlay (essential for GASP init)
   │
   ├─ [Validate All Components]
   │    ├─ For each BPC_ component:
   │    │    ├─ GetComponentByClass → IsValid? → Log
   │    │    └─ If invalid: FL_GameUtilities.LogError("Missing component: X")
   │    │
   │    └─ REQUIRED components (game cannot function without):
   │         ├─ BPC_HealthSystem → if missing, ERROR + disable input
   │         ├─ BPC_InventorySystem → if missing, ERROR
   │         ├─ BPC_StateManager → if missing, ERROR
   │         └─ BPC_InteractionDetector → if missing, ERROR
   │
   ├─ [Initialize Health]
   │    ├─ BPC_HealthSystem.SetMaxHealth(100.0)
   │    └─ BPC_HealthSystem.SetCurrentHealth(100.0)
   │
   ├─ [Initialize Stamina]
   │    ├─ BPC_StaminaSystem.SetMaxStamina(100.0)
   │    └─ BPC_StaminaSystem.SetCurrentStamina(100.0)
   │
   ├─ [Initialize Stress]
   │    ├─ BPC_StressSystem.SetCurrentStress(0.0)
   │    └─ BPC_StressSystem.SetStressDecayRate(1.0)  // per second in safe areas
   │
   ├─ [Initialize Movement]
   │    ├─ BPC_MovementStateSystem.SetMovementMode(Walking)
   │    └─ BPC_MovementStateSystem.SetPosture(Standing)
   │
   ├─ [Initialize Camera]
   │    ├─ BPC_CameraStateLayer.SetDefaultFOV(90.0)
   │    └─ BPC_EmbodimentSystem.SetVisibilityMode(FirstPerson)
   │
   ├─ [Initialize Inventory]
   │    ├─ BPC_InventorySystem.Initialize(GridWidth=6, GridHeight=4, MaxWeight=50.0)
   │    └─ BPC_EquipmentSlotSystem.Initialize()
   │         └─ Create slots: PrimaryWeapon, Tool, Armor (3 equipment slots)
   │
   ├─ [Initialize State Manager]
   │    ├─ BPC_StateManager.SetupGatingRules(DA_StateGatingTable)
   │    └─ BPC_StateManager.SetInitialState(Standing)
   │
   ├─ [Bind System Interconnections]
   │    │
   │    ├─ BPC_HealthSystem.OnHealthChanged → BPC_StateManager.UpdateVitalSignals
   │    ├─ BPC_HealthSystem.OnDeath → BPC_DeathHandlingSystem.HandleDeath
   │    ├─ BPC_StressSystem.OnStressTierChanged → BPC_CameraStateLayer.SetStressBlur
   │    ├─ BPC_StressSystem.OnStressTierChanged → SS_AudioManager.SetFloatParameter("Stress", value)
   │    ├─ BPC_StaminaSystem.OnStaminaDepleted → BPC_StateManager.ForcePushState(Exhausted)
   │    ├─ BPC_MovementStateSystem.OnModeChanged → BPC_StateManager.UpdateMovementState
   │    ├─ BPC_MovementStateSystem.OnFootstep → SS_AudioManager.PlayFootstep(SurfaceTag)
   │    ├─ BPC_HidingSystem.OnHideStateChanged → BPC_StateManager.SetOverlayState
   │    ├─ BPC_HidingSystem.OnHideStateChanged → SS_EnhancedInputManager.PushContext(Hiding)
   │    └─ (etc — any cross-system event binding)
   │
   └─ [Ready]
        └─ Broadcast OnPlayerReady
             └─ Other systems wait for this before querying player state

Step 5 — Wire Input Handling

[Event Graph — Input]

IA_Move (Axis2D) → CharacterMovementComponent.AddMovementInput
IA_Look  (Axis2D) → AddControllerYawInput + AddControllerPitchInput
   │
   ├─ [State Gating Check]
   │    └─ BPC_StateManager.IsActionPermitted(Move) ?
   │         ├─ True → process input
   │         └─ False → ignore input (blocked by state: cutscene, death, etc.)
   │
IA_Interact (Pressed) → BPC_InteractionDetector.Interact()
   └─ Also check: BPC_StateManager.IsActionPermitted(Interact)

IA_Sprint (Pressed) → BPC_StaminaSystem.StartSprint()
   └─ BPC_StateManager.IsActionPermitted(Sprint)? AND Stamina > 0?

IA_Sprint (Released) → BPC_StaminaSystem.StopSprint()

IA_Crouch (Pressed) → BPC_MovementStateSystem.ToggleCrouch()
   └─ BPC_StateManager.IsActionPermitted(Crouch)?

IA_Fire (Pressed) → BPC_ActiveItemSystem.UseEquippedItem()
   ├─ Routes to BP_Pistol_Held.UseItem() or BP_Shotgun_Held.UseItem()
   └─ BPC_StateManager.IsActionPermitted(Fire)?

IA_Fire (Released) → (cease fire for auto weapons)

IA_Aim (Pressed) → BPC_CameraStateLayer.SetLayer(Aiming)
   └─ FOV zooms to 55, slight camera offset forward

IA_Aim (Released) → BPC_CameraStateLayer.RemoveLayer(Aiming)
   └─ FOV returns to 90

IA_Reload (Pressed) → BPC_ActiveItemSystem.ReloadEquippedItem()
   └─ Routes to BP_Pistol_Held.Reload() or BP_Shotgun_Held.Reload()

IA_UseItem (Pressed) → BPC_ConsumableSystem.UseQuickSlotItem()
   └─ Uses whatever is in the quick-use slot (medkit, syringe, etc.)

IA_Flashlight (Pressed) → Toggle flashlight (if equipped in Tool slot)
   └─ Calls I_Toggleable.Toggle on BP_Flashlight_Held

IA_Jump (Pressed) → Character.Jump()
   └─ Also: BPC_ContextualTraversalSystem.TryVaultOrMantle()

IA_OpenWatch (Pressed) → SS_EnhancedInputManager.PushContext(WristwatchUI)
   ├─ SS_UIManager.ShowMenu(InventoryMenu)
   └─ Camera pans down to wristwatch

IA_PauseMenu (Pressed) → PC_HorrorController.OpenPauseMenu()

IA_QuickHeal (Pressed) → BPC_ConsumableSystem.QuickUse(MedKit)
   └─ Uses first available medkit in inventory

IA_QuickSlot1-8 → BPC_ActiveItemSystem.SetQuickSlot(SlotIndex)

Step 6 — Wire Component Communication

Each BPC_ component should communicate via Event Dispatchers, not direct references to other components. This keeps components decoupled.

Core Dispatcher Bindings (in Event BeginPlay):

[Damage Pipeline]
BPC_DamageReceptionSystem.OnDamageReceived
   ├─ → BPC_HealthSystem.ApplyDamage(Damage)
   ├─ → BPC_HitReactionSystem.PlayHitReaction(DamageInfo)
   ├─ → BPC_CombatFeedbackComponent.ShowHitMarker(DamageInfo)
   ├─ → WBP_ScreenEffectController.ShowDamageVignette()
   └─ → BPC_PlayerMetricsTracker.RecordDamageTaken(Damage)

[Health to State]
BPC_HealthSystem.OnHealthChanged(NewHealth, MaxHealth)
   ├─ → BPC_StateManager.UpdateVitalSignals()
   ├─ → WBP_DiegeticHUDFrame.UpdateHealthBar()
   └─ → SS_AudioManager.SetFloatParameter("HealthPercent", ratio)

[Health to Death]
BPC_HealthSystem.OnDeath(DeathCause, Killer)
   ├─ → BPC_DeathHandlingSystem.HandleDeath()
   └─ → BPC_StateManager.ForcePushState(Death)

[Stress System]
BPC_StressSystem.OnStressTierChanged(OldTier, NewTier)
   ├─ → PS_HorrorPlayerState.SetSanityTier(NewTier * 25)  // convert tier to 0-100
   ├─ → BPC_CameraStateLayer.SetStressBlur(NewTier)
   │    ├─ Calm → no blur
   │    ├─ Uneasy → slight peripheral blur
   │    ├─ Disturbed → moderate blur + vignette
   │    ├─ Breaking → heavy blur + tunnel vision
   │    └─ Catatonic → near-black screen
   ├─ → BPC_MemoryDriftSystem.SetIntensity(NewTier)
   │    └─ Triggers visual/audio hallucinations
   ├─ → SS_AudioManager.SetFloatParameter("StressTier", NewTier)
   └─ → BPC_StateManager.UpdateVitalSignals()

[Stamina System]
BPC_StaminaSystem.OnStaminaChanged(Current, Max)
   ├─ → WBP_DiegeticHUDFrame.UpdateStaminaBar()
   └─ → (If depleted) BPC_StateManager.ForcePushState(Exhausted)
        └─ Blocks Sprint action for 3 seconds

[Hiding System]
BPC_HidingSystem.OnEnterHiding(HidingSpot)
   ├─ → BPC_StateManager.SetOverlayState(Hiding)
   ├─ → SS_EnhancedInputManager.PushContext(Hiding)
   ├─ → BPC_CameraStateLayer.SetLayer(HidePeek)
   ├─ → BPC_StressSystem.StartStressDecay()  // stress decays while hidden
   └─ → WBP_DiegeticHUDFrame.ShowBreathHoldMeter()

BPC_HidingSystem.OnExitHiding()
   ├─ → BPC_StateManager.ClearOverlayState(Hiding)
   ├─ → SS_EnhancedInputManager.PopContext(Hiding)
   ├─ → BPC_CameraStateLayer.RemoveLayer(HidePeek)
   └─ → WBP_DiegeticHUDFrame.HideBreathHoldMeter()

[Inventory Events]
BPC_InventorySystem.OnItemAdded(ItemData, SlotIndex)
   ├─ → WBP_InventoryMenu.UpdateSlot(SlotIndex)
   ├─ → BPC_CollectibleTracker.CheckItem(ItemData) → if collectible, track it
   ├─ → WBP_NotificationToast.Show("Picked up: " + DisplayName)
   └─ → (If weapon) BPC_EquipmentSlotSystem.AutoEquipIfSlotEmpty(ItemData)

BPC_InventorySystem.OnItemRemoved(ItemData, SlotIndex)
   ├─ → WBP_InventoryMenu.ClearSlot(SlotIndex)
   └─ → (If equipped) BPC_EquipmentSlotSystem.UnequipSlot()

[Equipment Events]
BPC_EquipmentSlotSystem.OnItemEquipped(SlotTag, ItemData)
   ├─ → BPC_StateManager.SetEquipmentState(SlotTag, ItemData)
   ├─ → Spawn BP_*_Held actor (pistol, shotgun, flashlight)
   │    └─ Attach to hand socket on SkeletalMeshComponent
   └─ → BPC_ActiveItemSystem.SetCurrentItem(SlotTag, HeldActor)

[State Manager Events]
BPC_StateManager.OnStateChanged(OldState, NewState)
   ├─ → BPC_MovementStateSystem.SetStateRestrictions(NewState)
   │    └─ Death → no movement; Cutscene → no movement; etc.
   ├─ → WBP_HUDController.UpdateHUDActive(newState)
   │    └─ Hide HUD during cutscene/death; show during gameplay
   └─ → SS_EnhancedInputManager.SetContextVisibility(NewState)
        └─ Disable gameplay contexts during UI/Cutscene states

BPC_StateManager.OnActionDenied(ActionTag, BlockReason)
   └─ → WBP_InteractionPromptDisplay.ShowBlocked(ActionTag, BlockReason)
        └─ "Cannot fire — you are hiding"
        └─ "Cannot interact — cutscene playing"

---

Health, Stamina, Stress — The Core Survival Triad

These three systems work together to create the horror survival experience:

                        ┌──────────────────────┐
                        │   HEALTH (100 max)    │
                        │   ├─ Damage reduces   │
                        │   ├─ Medkit restores   │
                        │   └─ 0 HP = DEATH     │
                        └──────────┬───────────┘
                                   │ low health
                                   ▼
┌──────────────────────┐    ┌──────────────────────┐
│  STAMINA (100 max)    │    │  STRESS (0-100)      │
│  ├─ Sprint: -10/sec   │    │  ├─ Darkness: +2/sec │
│  ├─ Vault: -15/use    │    │  ├─ Enemy near: +5/s │
│  ├─ Combat: -5/action │    │  ├─ Void: +8/sec     │
│  └─ Regen: +5/sec     │    │  └─ Decay: -1/sec    │
│      (only when still)│    │      (safe areas)    │
└──────────┬───────────┘    └──────────┬───────────┘
           │ depleted                  │ high stress (75+)
           ▼                           ▼
    ┌──────────────┐          ┌──────────────────┐
    │  EXHAUSTED   │          │  HALLUCINATIONS  │
    │  ├─ Can't run│          │  ├─ False enemies │
    │  ├─ Walk slow│          │  ├─ Sounds/lights │
    │  └─ 3s cooldown│        │  └─ Screen distort│
    └──────────────┘          └──────────────────┘

---

Key Variables (Class Defaults)

Variable	Type	Default	Purpose
MaxHealth	Float	100.0	Set via BPC_HealthSystem in BeginPlay
MaxStamina	Float	100.0	Set via BPC_StaminaSystem
MaxStress	Float	100.0	Set via BPC_StressSystem
WalkSpeed	Float	300.0	GASP default
SprintSpeed	Float	600.0	GASP default
CrouchSpeed	Float	150.0	GASP default
InteractionRange	Float	300.0	How far the player can interact
bCanSprint	Boolean	true	Disabled when exhausted or state-blocked
bIsFirstPerson	Boolean	true	Horror game — no third-person toggle
DefaultFOV	Float	90.0	Normal gameplay FOV
AimFOV	Float	55.0	When aiming down sights
HidePeekFOV	Float	70.0	When peeking from hiding

---

Blueprint Wiring Checklist

Components

• Add BPC_HealthSystem (08)
• Add BPC_StaminaSystem (09)
• Add BPC_StressSystem (10)
• Add BPC_MovementStateSystem (11)
• Add BPC_HidingSystem (12)
• Add BPC_EmbodimentSystem (13)
• Add BPC_CameraStateLayer (14)
• Add BPC_PlayerMetricsTracker (15)
• Add BPC_InteractionDetector (16)
• Add BPC_InventorySystem (31)
• Add BPC_EquipmentSlotSystem (30)
• Add BPC_ActiveItemSystem (26)
• Add BPC_ConsumableSystem (28)
• Add BPC_KeyItemSystem (34)
• Add BPC_JournalSystem (33)
• Add BPC_CollectibleTracker (27)
• Add BPC_DocumentArchiveSystem (29)
• Add BPC_ItemCombineSystem (32)
• Add BPC_AmmoComponent (70)
• Add BPC_RecoilSystem (77)
• Add BPC_HitReactionSystem (75)
• Add BPC_DamageReceptionSystem (72)
• Add BPC_CombatFeedbackComponent (71)
• Add BPC_StateManager (130)
• Add BPC_NarrativeStateSystem (58)
• Add BPC_ObjectiveSystem (59)
• Add BPC_EndingAccumulator (68)

Event BeginPlay

• Call parent BeginPlay
• Validate all critical components → log errors if missing
• Initialize Health, Stamina, Stress to max values
• Initialize Inventory (6×4 grid, 50 weight)
• Initialize Equipment Slots (PrimaryWeapon, Tool, Armor)
• Initialize State Manager with DA_StateGatingTable
• Bind all inter-component dispatchers (Health→Death, Stress→Blur, etc.)

Input

• Bind IA_Move, IA_Look (always active unless state-blocked)
• Bind IA_Interact (state-gated)
• Bind IA_Sprint (stamina-gated + state-gated)
• Bind IA_Crouch (state-gated)
• Bind IA_Fire (state-gated + equipment-gated)
• Bind IA_Aim (equipment-gated)
• Bind IA_Reload (state-gated)
• Bind IA_UseItem (state-gated)
• Bind IA_Flashlight (state-gated)
• Bind IA_Jump (state-gated)
• Bind IA_OpenWatch (state-gated → pushes wristwatch context)
• Bind IA_PauseMenu
• Bind IA_QuickHeal
• Bind IA_QuickSlot1-8
• Every input check: BPC_StateManager.IsActionPermitted before processing

---

Notes for Expansion

• GASP customization: Never edit GASP AnimBP directly. Create a child AnimBP and override/insert notifies. Add your own locomotion states (limping, crawling) as new GASP states.
• Component order: Add components in dependency order if they have BeginPlay initialization dependencies. Health before DeathHandling; Inventory before Equipment.
• Multiplayer: All health/stamina/stress mutations must be server-authoritative. Use HasAuthority() gates. Replicate with RepNotify.
• Performance: If FPS drops, consider lazy-initializing non-critical components (CollectibleTracker, DocumentArchive, PlayerMetricsTracker).
• Mod support: Keep all default values in a DA_PlayerConfig Data Asset (health, stamina, speed, FOV) so modders can override without touching BP.

---

BP_HorrorPlayerCharacter — The player pawn for Project Void. See GAMEINDEX.md for full game structure. See INDEX.md for all framework component specs.