# BP_Checkpoint — Checkpoint Actor

**File:** [`Content/Framework/Save/BP_Checkpoint`](Content/Framework/Save/BP_Checkpoint.uasset)

**Purpose:** Manages checkpoint volumes in the world, tracks the most recent checkpoint crossed by the player, and triggers save operations via [`SS_SaveManager`](35_SS_SaveManager.md). Also stores respawn transform data for use by the death handling systems.

**Depends On:** [`SS_SaveManager`](35_SS_SaveManager.md), [`GM_CoreGameMode`](../01-core/05_GM_CoreGameMode.md)
**Used By:** Player Controller or Game Mode (placed at game setup)

---

## Enums

```cpp
// E_CheckpointActivationMode — Determines when a checkpoint triggers
E_CheckpointActivationMode
{
  OnOverlap,     // Player overlaps the checkpoint volume
  OnInteract,    // Player must press an interact key at the checkpoint
  Automated      // Triggered by external event (e.g., completing a puzzle)
}
```

---

## Structs

```cpp
// S_CheckpointData — Runtime data for one checkpoint
S_CheckpointData
{
  CheckpointTag:      GameplayTag   // Unique identifier for this checkpoint
  DisplayName:        FText         // "Save Room - Floor 2", etc.
  RespawnLocation:    Transform     // Where the player spawns on reload
  CameraCutTransform: Transform     // Optional camera cut point for respawn transition
  bHasBeenUsed:       Bool          // Has the player crossed this checkpoint?
  ActivationMode:     E_CheckpointActivationMode
  bAutoSave:          Bool          // Does crossing this checkpoint trigger an auto-save?
  LinkedObjectives:   Array of GameplayTag  // Objectives to mark complete on activation
}

// S_RespawnCache — Lightweight in-memory respawn data (not saved to disk)
S_RespawnCache
{
  LastCheckpointTag:      GameplayTag
  LastCheckpointLocation: Transform
  bIsRespawnFromDeath:    Bool      // False = checkpoint load, True = death respawn
  DeathCountAtCheckpoint: Integer   // Snapshot of death count for metrics
}
```

---

## Variables

| Name | Type | Description |
|------|------|-------------|
| `RegisteredCheckpoints` | Map (GameplayTag → `S_CheckpointData`) | All checkpoint volumes in the current level |
| `ActiveCheckpoint` | `S_CheckpointData` | The most recently activated checkpoint |
| `RespawnCache` | `S_RespawnCache` | Lightweight cache for respawn without full load |
| `bCanCrossCheckpoint` | Bool | Cooldown guard to prevent double-trigger (reset after 0.5s) |
| `DefaultRespawnTransform` | Transform | Fallback spawn point if no checkpoint exists (level start) |
| `CheckpointCooldownTimer` | Float | Timer handle for cooldown (0.5s default) |

---

## Functions / Events

| Name | Inputs | Outputs | Description |
|------|--------|---------|-------------|
| `RegisterCheckpoint` | Data: `S_CheckpointData` | — | Adds a checkpoint to the registered map |
| `UnregisterCheckpoint` | CheckpointTag: GameplayTag | — | Removes a checkpoint from the map |
| `ActivateCheckpoint` | CheckpointTag: GameplayTag | — | Sets the given checkpoint as active; triggers save if `bAutoSave` is true |
| `GetActiveCheckpoint` | — | `S_CheckpointData` | Returns the currently active checkpoint |
| `GetRespawnTransform` | — | Transform | Returns the respawn location (active checkpoint or fallback) |
| `HasActiveCheckpoint` | — | Bool | Returns whether a checkpoint has been crossed |
| `GetCheckpointList` | — | Array of `S_CheckpointData` | Returns all registered checkpoints (for UI map / fast travel) |
| `ClearCheckpointData` | — | — | Resets all checkpoint state (on new game) |
| `SetDefaultRespawn` | Transform: Transform | — | Sets the fallback respawn point when no checkpoint exists |
| `OnPlayerDeath` | — | — | Fired by GM_CoreGameMode; caches current checkpoint as death respawn point |
| `OnPlayerRespawn` | — | — | Fired after respawn; clears death flags |

---

## Event Dispatchers

| Name | Parameters | Fired When |
|------|-----------|------------|
| `OnCheckpointActivated` | CheckpointTag: GameplayTag, DisplayName: FText | A checkpoint is crossed and becomes active |
| `OnCheckpointSaveTriggered` | CheckpointTag: GameplayTag | An auto-save was triggered by this checkpoint |
| `OnRespawnPointSet` | RespawnTransform: Transform | The respawn point has changed |
| `OnCheckpointListChanged` | CheckpointCount: Int | A checkpoint was added or removed |

---

## Blueprint Flow Diagram

```mermaid
flowchart TD
    A[Player overlaps checkpoint volume] --> B{Volume implements\nI_CheckpointVolume?}
    B -->|No| C[Ignore]
    B -->|Yes| D[Get checkpoint GameplayTag]
    D --> E{Can cross?\nbCanCrossCheckpoint}
    E -->|No| F[Ignore]
    E -->|Yes| G[Set bCanCrossCheckpoint = false]
    G --> H[Lookup in RegisteredCheckpoints map]
    H --> I{Found?}
    I -->|No| J[Log warning: unregistered checkpoint]
    I -->|Yes| K[Set ActiveCheckpoint = found data]
    K --> L[Set RespawnCache.LastCheckpointTag]
    L --> M[Set RespawnCache.LastCheckpointLocation]
    M --> N[Broadcast OnCheckpointActivated]
    N --> O{bAutoSave?}
    O -->|Yes| P[SS_SaveManager.SaveCheckpoint\nCheckpointTag]
    P --> Q[Broadcast OnCheckpointSaveTriggered]
    O -->|No| R[Skip save]
    R --> S[Start cooldown timer 0.5s]
    Q --> S
    S --> T[Timer expires -> set bCanCrossCheckpoint = true]
```

---

## Communication Matrix

| Target System | Method | Why |
|---------------|--------|-----|
| `SS_SaveManager` | Direct call `SaveCheckpoint` | Trigger checkpoint auto-save |
| `SS_SaveManager` | Bind to `OnLoadComplete` | Restore active checkpoint tag after load |
| `GM_CoreGameMode` | Bind to death/respawn events | Receive death and respawn notifications |
| `BPC_PlayerRespawnSystem` | Provide `GetRespawnTransform` | Supply respawn location on death |
| `BPC_DeathHandlingSystem` | Provide `RespawnCache` data | Death handling reads cache for appropriate flow |
| Checkpoint Volume Actors | Interface call | Register/unregister via BeginPlay/EndPlay |
| `WBP_CheckpointNotification` | Dispatcher `OnCheckpointActivated` | Show "Checkpoint Saved" HUD notification |
| `WBP_MapWidget` | Function `GetCheckpointList` | Display discovered checkpoints on map |

---

## Checkpoint Volume Setup

```
BP_CheckpointVolume (Box Collision, Render CustomDepth)
  └── Collision: OverlapOnly (PlayerOnly)
  └── OnComponentBeginOverlap
       └── Get owner's CheckpointTag (GameplayTag)
       └── Call BP_Checkpoint.ActivateCheckpoint(Tag)
```

**Checkpoint Volume Variables:**

| Variable | Type | Source |
|----------|------|--------|
| `CheckpointTag` | GameplayTag | Set per-instance in level |
| `DisplayName` | FText | Set in defaults (e.g., "Hospital Lobby") |
| `RespawnLocation` | Transform | Arrow component on the volume |
| `CameraCutTransform` | Transform | Optional arrow component |
| `ActivationMode` | E_CheckpointActivationMode | Overlap by default |
| `bAutoSave` | Bool | True by default |

---

## Reuse Notes

- Each checkpoint volume creates itself by calling `RegisterCheckpoint` in `BeginPlay` with its configured `S_CheckpointData`
- Single-player only — multiplayer requires a server-authorised version with per-player checkpoint tracking
- The 0.5s cooldown prevents double-activation from overlapping two volumes simultaneously
- `DefaultRespawnTransform` should be set by `GM_CoreGameMode` on level start from the PlayerStart actor
- `CheckpointTag` naming convention: `Checkpoint.<LevelName>.<AreaName>`
- Renamed from `BPC_CheckpointSystem` to `BP_Checkpoint` per Master naming convention.