UE5-Modular-Game-Framework/docs/game/state-gating-examples.md

State Gating Examples — Game-Specific State Rules

Game: Project Void | Build Phase: 14 (Data Asset configuration) Framework Systems: 130_BPC_StateManager, 131_DA_StateGatingTable

---

Purpose

Defines game-specific state gating rules added to DA_StateGatingTable (131). These rules determine what actions are permitted in each game state. Designers can modify these without touching any Blueprint code.

---

How State Gating Works (Quick Refresher)

Any system that wants to perform an action:

   Actor → BPC_StateManager.IsActionPermitted(ActionTag)
   │
   ├─ StateManager checks DA_StateGatingTable for rule matching ActionTag
   ├─ Rule specifies which states BLOCK this action
   ├─ If current state matches blocked state:
   │    └─ Return { bPermitted = false, BlockReason = "Cannot [Action] — [Reason]" }
   └─ If current state doesn't match:
        └─ Return { bPermitted = true }

Result struct: S_ActionPermissionResult
   ├─ bPermitted: Boolean
   ├─ BlockReason: FText (shown to player via InteractionPromptDisplay)
   └─ BlockingState: GameplayTag (for debug/logging)

---

Framework Default Rules (from DA_StateGatingTable, 37 rules)

These come from the framework and apply to all games:

Action	Blocked By
Move	Death, Cutscene, Loading, Exhausted
Look	Cutscene, Loading
Interact	Death, Cutscene, Loading, Hiding, Reloading
Fire	Death, Cutscene, Loading, Hiding, Reloading, Exhausted, Sprinting
Reload	Death, Cutscene, Loading, Hiding, Exhausted
Sprint	Death, Cutscene, Loading, Crouching, Exhausted
Crouch	Death, Cutscene, Loading, Sprinting
Jump	Death, Cutscene, Loading, Crouching
Equip	Death, Cutscene, Loading, Hiding, Reloading
UseItem	Death, Cutscene, Loading, Hiding
Hide	Death, Cutscene, Loading, Sprinting, Exhausted, InCombat
Pause	Death, Cutscene, Loading, AltDeathSpace
...	(30+ more rules — see 131_DA_StateGatingTable.md)

---

Game-Specific Rules (Project Void)

These are added on top of the framework defaults. They represent horror-game-specific restrictions.

1. Combat Rules

Action Tag	Blocked By	Block Reason	Notes
Fire	State.InVoidSpace	"Your weapon has no power here."	Weapons don't work in void space
Fire	State.Catatonic	"Your hands shake too much to aim."	Stress 100 = can't shoot
Reload	State.InVoidSpace	"Ammunition is meaningless in the void."	Void space blocks reload
Melee	State.InVoidSpace	"You swing at shadows."	Melee also useless in void

2. Void Space Rules

Action Tag	Blocked By	Block Reason	Notes
Interact	State.VoidShiftActive	"Reality is unstable. Nothing responds correctly."	During void shift events, interaction is unreliable (50% chance success)
Move	State.VoidParalyzed	"The void holds you still."	Scripted moments where player is frozen
Pause	State.AltDeathSpace	"There is no escape from the void."	No pause menu in void space
OpenInventory	State.AltDeathSpace	"Your belongings feel distant here."	No inventory in void space
UseItem	State.AltDeathSpace	"Items from your world have no effect."	Can't use consumables in void space

3. Horror-Specific Rules

Action Tag	Blocked By	Block Reason	Notes
Sprint	State.Exhausted	"You're too exhausted to run."	After stamina depleted for 3+ seconds
Sprint	State.Catatonic	"Your body won't obey."	Stress 100 = no sprint
Interact	State.InCombat	"Too dangerous! Find cover first."	Can't search drawers while enemy is attacking
Hide	State.InCombat	"Hide quickly before they see you!"	Transition period of 2s after combat starts, then allowed
Hide	State.Catatonic	"You can't think clearly enough to hide."	Stress 100 = can't hide
Flashlight	State.Exhausted	"Your arm is too weak to hold the light."	Exhausted state dims flashlight to 25% instead of blocking
OpenWatch	State.Hiding	—	ALLOWED (override framework block) — can check inventory while hiding

4. Narrative/Dialogue Rules

Action Tag	Blocked By	Block Reason	Notes
All (wildcard)	State.InDialogueChoice	"Make your choice."	ALL actions blocked during dialogue choice
Move	State.InDialogueChoice	"You stand before the entity, frozen."	Can't walk away mid-choice
Equip	State.InCutscene	—	Framework default already blocks
Pause	State.InEndingSequence	"This moment cannot be paused."	Ending cutscene blocks pause

5. Death State Rules

Action Tag	Blocked By	Block Reason	Notes
All (wildcard)	State.Dead	"You are dead."	ALL actions blocked
Pause	State.Dead	"Press Continue to respawn."	Pause menu blocked on death screen (death screen is the menu)
Look	State.Dead	—	ALLOWED (override) — camera still follows ragdoll briefly

---

DA_StateGatingTable Game-Specific Configuration

How to Add These Rules in UE5

1. Open DA_StateGatingTable (Content/Framework/State/)
2. Duplicate it → DA_StateGatingTable_Horror (Content/Game/DataAssets/)
3. The framework DA_StateGatingTable has 37 base rules. The game-specific table inherits them.
4. Add new entries for game-specific rules.

Rule: NEVER modify DA_StateGatingTable in Framework/. Use your game copy.

Rule Entry Structure

S_StateGatingRule (struct):
  ├─ ActionTag: GameplayTag              (e.g., Framework.Action.Fire)
  ├─ BlockedStateTags: Array<GameplayTag> (e.g., State.InVoidSpace)
  ├─ BlockReason: FText                  (shown to player)
  ├─ Priority: Int32                     (higher = overrides lower priority rules)
  └─ bOverrideFramework: Boolean         (true = replaces framework rule for this action)

Example Entry: Block Fire in Void Space

ActionTag:     Framework.Action.Fire
BlockedStates: [State.InVoidSpace, State.AltDeathSpace]
BlockReason:   "Your weapon has no power here."
Priority:      100
OverrideFramework: false (ADD to framework blocks, not REPLACE)

Example Entry: ALLOW Interact During Hiding (Override)

ActionTag:     Framework.Action.OpenWatch
BlockedStates: []  (empty = no blocks = ALWAYS permitted)
BlockReason:   ""
Priority:      200 (HIGHER than framework default)
OverrideFramework: true (REPLACE framework rule — framework blocks OpenWatch during Hiding)

---

Runtime State Management (BPC_StateManager Integration)

Force Push States (Scripted Moments)

States that are force-pushed by game systems:

  BPC_CutsceneBridge → ForcePushState(InCutscene)
    └─ Blocks: All actions except SkipCutscene
    
  BPC_DeathHandlingSystem → ForcePushState(Dead)
    └─ Blocks: All actions
    
  BPC_VoidShiftSystem → ForcePushState(VoidShiftActive)
    └─ Blocks: Fire, Reload, Melee, Interact(50%)
    
  BPC_DialogueChoiceSystem → ForcePushState(InDialogueChoice)
    └─ Blocks: All actions except dialogue input
    
  BPC_StressSystem (at Catatonic) → ForcePushState(Catatonic)
    └─ Blocks: Fire, Sprint, Hide

Overlay States (Simultaneous)

States that layer on top of base state:

  BPC_HidingSystem → SetOverlayState(Hiding)
    └─ Blocks: Fire, Reload, Sprint, Jump
    └─ Allows: Look, Interact (exit hide), Crouch
    
  BPC_EquipmentSlotSystem → SetOverlayState(Aiming)
    └─ Blocks: Sprint, Jump
    └─ Allows: Fire (with ADS bonus), Reload, Crouch
    
  BPC_StaminaSystem → SetOverlayState(Exhausted)
    └─ Blocks: Sprint, Jump
    └─ Allows: Move (walk only), Interact, Fire

Vital Signals (BPC_StateManager tracks)

BPC_StateManager.UpdateVitalSignals() is called every 0.5s:

  E_PlayerVitalSignals:
    ├─ Normal    → Health > 50 AND Stress < 50 AND Stamina > 30
    ├─ Wounded   → Health < 50
    ├─ Stressed  → Stress > 50
    ├─ Exhausted → Stamina < 20
    └─ Critical  → Health < 25 OR Stress > 90

Systems read vital signals to modify behavior:
  ├─ WBP_DiegeticHUDFrame → changes health bar color per signal
  ├─ SS_AudioManager → modifies heartbeat audio parameter
  ├─ BPC_CameraStateLayer → adjusts FOV and blur per signal
  └─ BPC_MemoryDriftSystem → increases hallucination intensity

---

GASP Liaison (Movement ↔ State)

Movement State → Action State Mapping

BPC_MovementStateSystem reports movement mode to BPC_StateManager:

  MovingMode.Walking   → State.Walking
  MovingMode.Sprinting → State.Sprinting
  MovingMode.Crouching → State.Crouching
  MovingMode.Falling   → State.Falling (no jump/equip actions)
  MovingMode.Swimming  → State.Swimming (if water areas added)
  MovingMode.Ladder    → State.Climbing (no fire/equip actions)

BPC_StateManager enforces:
  ├─ Can't Sprint → if State.Is(Exhausted) OR State.Is(Catatonic)
  ├─ Can't Crouch → if State.Is(Sprinting)
  └─ Can't Jump   → if State.Is(Crouching) OR State.Is(Exhausted)

---

Debugging State Gating

In WBP_DebugMenu → State Viewer tab:

Display:
  ├─ Current Action State: "Walking"
  ├─ Current Overlay States: ["Hiding"]
  ├─ Vital Signal: "Wounded"
  ├─ Force Stack Depth: 2
  │    ├─ [0] InCutscene (pushed by BPC_CutsceneBridge)
  │    └─ [1] Dead (pushed by BPC_DeathHandlingSystem)
  │
  ├─ Action Test:
  │    ├─ [Fire]        → BLOCKED: "Cannot Fire — you are in Hiding"
  │    ├─ [Interact]    → BLOCKED: "Cannot Interact — cutscene playing"
  │    └─ [Look]        → PERMITTED
  │
  └─ Gating Table Source: DA_StateGatingTable_Horror (Game/DataAssets/)

---

Blueprint Wiring Checklist

• Duplicate DA_StateGatingTable → DA_StateGatingTable_Horror in Game/DataAssets/
• Add all 15+ game-specific gating rules
• Configure BP_HorrorPlayerCharacter → BPC_StateManager → set GatingTable = DA_StateGatingTable_Horror
• Wire all force-push states (cutscene, death, void shift, dialogue choice, catatonic)
• Wire all overlay states (hiding, aiming, exhausted)
• Wire GASP liaison: MovementState → BPC_StateManager movement update
• Test every blocked action shows correct BlockReason in HUD
• Verify WBP_InteractionPromptDisplay reads OnActionDenied dispatcher

---

Notes for Expansion

• New states can be added by creating a new GameplayTag in DT_Tags_State.csv
• Designers can add gating rules to DA_StateGatingTable_Horror without touching any Blueprint
• Priority system allows game rules to override framework rules cleanly
• Consider adding "semi-permitted" actions: permitted but with penalty (e.g., flashlight dims when exhausted)
• Add per-state camera layers: each state automatically configures FOV, offset, blur
• Multiplayer: state gating is server-authoritative; client requests are validated server-side

---

State Gating Examples for Project Void. See GAMEINDEX.md for full game structure. See bpc-statemanager.md for full State Manager architecture. See 130_BPC_StateManager.md for State Manager spec.