# GM_CoreGameMode — Core GameMode

> **⚡ C++ Status: Full Implementation** — `Source/PG_Framework/Public/Core/GM_CoreGameMode.h` provides chapter transitions, death handling, ending triggers, and pause control. **Create a BP child** (Blueprint Class → All Classes → `GM_CoreGameMode`). In Class Defaults → **"Classes"** section (inherited from `AGameModeBase`): set `PlayerControllerClass`, `PlayerStateClass`, `GameStateClass`, and `DefaultPawnClass`. Do NOT redeclare these variables — they're inherited. See `docs/developer/cpp-integration-guide.md` for exact setup steps.
>
> ---

## Asset Details

| Field | Value |
|-------|-------|
| **Asset Type** | Blueprint Class |
| **Parent Class** | GameModeBase |
| **Folder** | Framework/Core/ |
| **UE Version** | 5.5–5.7 |
| **Prefix** | GM_ |
| **Icon** | GameMode icon |

---

## Purpose

Sets the rules of the game session: which pawn, controller, player state, HUD, and game state classes to use. Manages level-phase transitions, win/loss routing, and chapter transitions.

---

## Dependencies

| Dependency | Type | Why |
|------------|------|-----|
| [`GI_GameFramework`](01-core/04_GI_GameFramework.md) | Direct reference | Phase transition coordination |
| [`GS_CoreGameState`](01-core/06_GS_CoreGameState.md) | Owned/managed | Session state store |
| [`PC_CoreController`](../02-player/08_PC_CoreController.md) | Spawned | Default player controller |
| [`BPC_DeathHandlingSystem`](../08-saveload/23_BPC_DeathHandlingSystem.md) | Dispatcher (receives) | Receives death event |
| [`SS_SaveSystem`](../08-saveload/21_SS_SaveSystem.md) | Direct | Checkpoint load on respawn |
| [`BPC_NarrativeSystem`](../06-narrative/37_BPC_NarrativeSystem.md) | Interface | Chapter start/end hooks |

---

## Enums

No enums defined on this class directly. References [`E_GamePhase`](01-core/04_GI_GameFramework.md) from [`GI_GameFramework`](01-core/04_GI_GameFramework.md) and [`E_DeathCause`](../05-weapons/18_BPC_DeathCauseTracker.md) from death handling.

---

## Structs

None. All data is primitive or class references.

---

## Variables

| Name | Type | Description | Access |
|------|------|-------------|--------|
| `DefaultPawnClass` | Class Reference | GASP-based player pawn class | Public |
| `DefaultControllerClass` | Class Reference | [`PC_CoreController`](../02-player/08_PC_CoreController.md) | Public |
| `DefaultPlayerStateClass` | Class Reference | [`PS_CorePlayerState`](../02-player/09_PS_CorePlayerState.md) | Public |
| `DefaultGameStateClass` | Class Reference | [`GS_CoreGameState`](01-core/06_GS_CoreGameState.md) | Public |
| `DefaultHUDClass` | Class Reference | [`WBP_HUDController`](../05-ui/31_WBP_HUDController.md) | Public |
| `bPauseAllowed` | Boolean | Runtime flag — disables pause during scripted moments | Public |
| `CurrentChapterTag` | GameplayTag | Active chapter/level identifier | Public |

---

## Functions / Events

| Name | Inputs | Outputs | Description |
|------|--------|---------|-------------|
| `TransitionToChapter` | ChapterTag: GameplayTag | — | Loads next level, sets chapter tag, triggers narrative hooks |
| `TriggerGameOver` | Cause: E_DeathCause | — | Routes to death handler or alt death space |
| `TriggerEnding` | EndingTag: GameplayTag | — | Passes ending tag to [`BPC_EndingAccumulatorSystem`](../06-narrative/42_BPC_EndingAccumulatorSystem.md) |
| `SetPauseAllowed` | bAllowed: Boolean | — | Enables/disables pause permission |
| `HandlePlayerDead` | — | — | Called by [`BPC_DeathHandlingSystem`](../08-saveload/23_BPC_DeathHandlingSystem.md); routes respawn or game-over |
| `SetChapterTag` | ChapterTag: GameplayTag | — | Updates CurrentChapterTag and syncs to [`GS_CoreGameState`](01-core/06_GS_CoreGameState.md) |
| `GetCurrentChapter` | — | GameplayTag | Returns CurrentChapterTag |

### Function Details

#### `TransitionToChapter`

```
Input:  ChapterTag (GameplayTag)
Output: none
Flow:
  └─► Set ChapterTag on GM
  └─► Set GamePhase(Loading) on GI_GameFramework
  └─► OpenLevel / StreamLevel by ChapterTag
  └─► On level loaded:
      ├─► Sync chapter to GS_CoreGameState
      ├─► Fire BPC_NarrativeSystem.OnChapterStart
      └─► SetGamePhase(InGame)
```

#### `HandlePlayerDead`

```
Input:  none (triggered by dispatcher)
Output: none
Flow:
  └─► bPauseAllowed = false
  └─► SetGamePhase(DeathLoop) on GI_GameFramework
  └─► Decision:
      ├─► Alt death space configured? → TriggerEnding(AltDeathSpace)
      └─► No → SetGamePhase(Loading)
               → SS_SaveSystem.LoadCheckpoint()
               → On load → BPC_PlayerRespawnSystem.Respawn()
```

---

## Event Dispatchers

| Name | Parameters | Fired When |
|------|-----------|------------|
| `OnChapterTransition` | NewChapterTag: GameplayTag | Before level loads for chapter transition |
| `OnGameOverTriggered` | Cause: E_DeathCause | Game-over sequence begins |

---

## Blueprint Flow

```mermaid
flowchart TD
    A[BeginPlay / Init] --> B[Set Default Classes]
    B --> C{Has Save Data?}
    C -->|Yes| D[SS_SaveSystem.LoadFromSlot]
    C -->|No| E[Start New Game]
    D --> F[OnLoadComplete -> SetGamePhase InGame]
    E --> G[TransitionToChapter first chapter]
    
    H[Player Dies] --> I[BPC_DeathHandlingSystem dispatches]
    I --> J[HandlePlayerDead]
    J --> K{Alt Death Space?}
    K -->|Yes| L[SetGamePhase AltDeathSpace]
    K -->|No| M[SetGamePhase Loading]
    M --> N[SS_SaveSystem.LoadCheckpoint]
    N --> O[Respawn Player]
    O --> P[SetGamePhase InGame]

    Q[Chapter Trigger] --> R[TransitionToChapter]
    R --> S[SetGamePhase Loading]
    S --> T[Load Chapter Level]
    T --> U[Update GS_CoreGameState]
    U --> V[SetGamePhase InGame]
```

---

## Communication Matrix

| Target System | Method | Direction | Why |
|---------------|--------|-----------|-----|
| [`GI_GameFramework`](01-core/04_GI_GameFramework.md) | Direct reference | Both ways | Phase transitions, active slot index |
| [`GS_CoreGameState`](01-core/06_GS_CoreGameState.md) | Direct reference | Write | Sync chapter tag and objective state |
| [`BPC_DeathHandlingSystem`](../08-saveload/23_BPC_DeathHandlingSystem.md) | Dispatcher | Inbound | Receives OnPlayerDied event |
| [`SS_SaveSystem`](../08-saveload/21_SS_SaveSystem.md) | Direct reference | Outbound | Load checkpoint on respawn |
| [`BPC_NarrativeSystem`](../06-narrative/37_BPC_NarrativeSystem.md) | Interface call | Outbound | Chapter start/end narrative hooks |
| [`PC_CoreController`](../02-player/08_PC_CoreController.md) | Direct spawn | Create | Default controller class |
| All menu widgets | Phase dispatcher | Outbound | Phase transitions via GI |

---

## Validation Checklist

- [ ] All default class references point to valid Blueprint classes
- [ ] `TransitionToChapter` correctly loads the level associated with the chapter tag
- [ ] `TriggerGameOver` properly freezes input and shows game-over screen
- [ ] `HandlePlayerDead` correctly routes to checkpoint load or alt death space
- [ ] `bPauseAllowed` is respected by pause menu widget
- [ ] Chapter transitions trigger narrative system hooks
- [ ] Player respawn restores proper game state
- [ ] No hardcoded references — all class selectors are exposed as variables

---

## Reuse Notes

- **Override** default class references per project (different pawn, different controller)
- **`TransitionToChapter`** can use level streaming or full level load — configure via project settings
- **`TriggerEnding`** is the only project-specific hook — override to handle unique ending sequences
- **`bPauseAllowed`** can be extended to a tag-based system for finer control
- For multiplayer, extend to derive from a replicated GameMode base
- The entire class is project-agnostic — drop into any UE5 project and configure class references

---

## Multiplayer Networking

### Parent Class
Derive from `GameMode` (not `GameModeBase`) in multiplayer. `GameMode` is replicated — `GameModeBase` is not. All default class references and spawn logic remain identical.

### Replicated Variables
| Variable | Type | Condition | Description |
|----------|------|-----------|-------------|
| `CurrentChapterTag` | `GameplayTag` | `Replicated Using OnRep_ChapterTag` | Synced chapter for all clients |
| `bPauseAllowed` | `Boolean` | `Replicated` | Whether pause is permitted |

### Authority Notes
| Function | Authority | Notes |
|----------|-----------|-------|
| `TransitionToChapter` | `Server` | Chapter transitions are server-only. OnRep syncs chapter tag to clients. |
| `HandlePlayerDead` | `Server` | Death is server-authoritative. Routes respawn or game-over. |
| `SetPauseAllowed` | `Server` | Pause permission is server-controlled. |
| `TriggerGameOver` | `Server` | Game-over sequence runs on server. |
| `TriggerEnding` | `Server` | Ending determination is server-authoritative. |

### Server RPCs
| RPC | Direction | Description |
|-----|-----------|-------------|
| `Server_PauseRequest` | Client→Server | Client requests pause. Server checks `bPauseAllowed`, pauses if permitted. |

### Client Prediction
- Chapter transitions: no client prediction — loading screen runs on all clients.
- Death routing: clients see death animation via multicast; respawn is server-driven.
- Pause: server-authoritative with client request.

### OnRep Handlers
```
OnRep_ChapterTag(NewTag)
  → Update GS_CoreGameState.ActiveChapterTag
  → Broadcast OnChapterTransition
```