add blueprints
This commit is contained in:
Lefteris Notas
169
docs/blueprints/05-saveload/37_BP_Checkpoint.md
Normal file
169
docs/blueprints/05-saveload/37_BP_Checkpoint.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user