169 lines
7.4 KiB
Markdown
169 lines
7.4 KiB
Markdown
# 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. |