API Reference
The complete lookup surface. All interface methods are BlueprintNativeEvent (overridable in C++ via _Implementation and in Blueprint) unless noted. Subsystem functions are BlueprintCallable unless marked C++-only.
Interfaces
ICrimsonSaveableSystem - implement on any UObject (subsystem, component, or plain object) to make it a saveable system; register with the manager.
| Function | Returns | Description |
|---|
GetFragmentName() | FString | Required. Unique fragment file name within the slot. Must be unique across all registered systems. |
GetPlayerSaveKey() | FString | Empty (default) = global fragment. Return UCrimsonSavePlayerIdentity::ResolvePlayerSaveKey(PC) for a player-scoped fragment. |
GatherSaveData() | UCrimsonSaveGameFragmentBase* | Optional. Return a custom fragment, or nullptr to rely on SaveGame auto-serialization. Both run together. |
RestoreFromSaveData(Fragment) | void | Optional. Called after SaveGame properties are deserialized. Fragment is const and never null. |
OnPreSave() / OnPostSave() | void | Before GatherSaveData / after all fragments are written. |
OnPreRestore() / OnPostRestore() | void | Before / after RestoreFromSaveData. |
ICrimsonSaveableActor - implement on a level actor to persist it. Note actors use an FInstancedStruct payload, whereas systems use a UCrimsonSaveGameFragmentBase.
| Function | Returns | Description |
|---|
GatherActorSaveData() | FInstancedStruct | Optional custom payload beyond auto-captured state. Empty (default) = auto-capture only. |
RestoreFromSaveData(ActorData) | void | Receives the FInstancedStruct. Transform, SaveGame fields, and component state are already restored. |
OnPreRestoreState() / OnPostRestoreState() | void | Lifecycle hooks around restoration. |
ShouldRespawnAfterDestroyed() | bool | Default false. Return true so a destroyed placed actor respawns from the level. Runtime actors ignore it. |
Save Manager Subsystem - Registration
UCrimsonSaveGameManagerSubsystem (UGameInstanceSubsystem). Access via UCrimsonSaveGameManagerSubsystem::Get(WorldContextObject).
| Function | Description |
|---|
RegisterSaveableSystem(System) | Registers a saveable system. Call from BeginPlay or Initialize. If a matching fragment is already cached (loaded before the system started), it is delivered immediately. |
UnregisterSaveableSystem(System) | Call from EndPlay or Deinitialize. Safe at any time. |
Save Manager Subsystem - Save operations
All save operations are authority-guarded; calls on NM_Client are rejected. See Concept: Multiplayer & Player Scoping.
| Function | Description |
|---|
RequestNewGameSave(SlotIndex, CharacterName, OutError) | Creates a new slot directory, writes the header, and saves all registered fragments. Returns false if the slot exists or the name is empty. |
RequestSaveProgress() | Saves all registered fragments to the active slot. No-op if no slot is active. |
RequestAutoSave(DisplayName) | Saves to a rotating auto-save slot (10000-10009). Oldest overwritten past MaxAutoSaves. |
RequestQuickSave(DisplayName) | Saves to a rotating quick-save slot (10100-10109). Oldest overwritten past MaxQuickSaves. |
RequestSaveSpecificFragment(System) | Saves a single system's fragment without requiring an active slot. Useful for user preferences that save independently of game progress. |
SaveGameToActiveSlotSynchronous() | Synchronous save of systems + world actors, safe during shutdown / PIE-end. Used by the save-on-exit path. |
Save Manager Subsystem - Load operations
| Function | Description |
|---|
RequestLoadFromSlot(SlotIndex) | Loads the header and all fragment files from the slot. Each fragment is matched to its registered system and RestoreFromSaveData is called. Fires OnLoadComplete. |
LoadFragmentsForPlayer(PlayerSaveKey) | Loads only fragments matching PlayerSaveKey from the active slot. Call from PostLogin for players joining a running session. |
RequestSavePlayerFragments(PlayerSaveKey) | Synchronously flushes all fragments belonging to PlayerSaveKey. Call from Logout before the player's objects are destroyed. |
Save Manager Subsystem - Slots
| Function | Description |
|---|
RequestDeleteSlot(SlotIndex) | Deletes all files in the slot directory. Irreversible. |
GetActiveSaveHeader() | The UCrimsonSaveGameHeader for the active slot, or nullptr. |
GetAllSaveSlotHeaders() | Headers for all manual (non-auto/quick) slots. Populate a slot-selection UI with this. |
GetSlotNameByIndex(SlotIndex) | The on-disk directory name for a slot index. |
SetActiveSaveSlot(SlotIndex) / GetActiveSaveSlot() | Set / get the current gameplay slot index. GetActiveSaveSlot returns -1 if none. |
Save Manager Subsystem - Session hooks
| Function | Description |
|---|
NotifyPlayerLoggedIn(PlayerController) | Call from PostLogin. Resolves the player's save key; if bAutoLoadOnPostLogin, loads their player-scoped fragments. |
NotifyPlayerLoggedOut(PlayerController) | Call from Logout before Super::Logout. If bAutoSaveOnLogout, synchronously flushes the player's fragments. |
Save Manager Subsystem - Playtime & user prefs
| Function | Description |
|---|
StartNewPlaytimeSession() | Reset the playtime clock; call after creating a new slot. |
LoadPlaytimeFromHeader(PlayTime) | Seed the clock from a loaded header's accumulated play time. |
GetCurrentTotalPlayTime() | Current total play time; flushed to the header on save. |
GetLastSelectedSaveSlot() / SetLastSelectedSaveSlot(Index) | Per-user preference persisted outside any gameplay slot. |
ShouldAutoLoadLastSave() / SetShouldAutoLoadLastSave(bool) | Per-user "continue" preference. |
HasLoadedFragment(CacheKey) | True if a fragment for CacheKey is already in the load cache. |
Save Manager Subsystem - Delegates
| Delegate | Signature | When fired |
|---|
OnLoadComplete | bool bSuccess | After a full load. bSuccess is false if any critical file was missing. |
OnSaveSlotListChanged | (none) | After a slot is created or deleted - rebind slot-list UI here. |
ClearActiveSaveData | (none) | On return to main menu / new game - clear in-memory state. |
OnSaveError | FString SlotName, FString FragmentName | Per fragment that fails to save; the operation continues. |
OnLoadError | FString SlotName, FString FragmentName | Per fragment that fails to load; other fragments continue. |
World Manager Subsystem
UCrimsonSaveWorldManagerSubsystem (UWorldSubsystem). Discovers ICrimsonSaveableActor actors, manages per-level slabs, handles streaming. Server-authoritative.
| Function | Description |
|---|
SaveWorldState() | Capture all saveable actors in loaded levels (when bAutoCaptureActorsOnSave) then flush slabs. |
LoadWorldState() | Apply slabs, re-spawn runtime actors, resolve cross-object references. |
OnActorStateChanged(Actor) | Optional incremental capture of one actor. Not required for normal saving. |
OnActorDestroyed(Actor) | Optional manual destruction hook. Destruction is auto-detected on the server. |
Save Facade (Blueprint helper)
UCrimsonSaveFacade (UBlueprintFunctionLibrary) - a one-call surface over the save manager for save-menu UI. Every call resolves the manager from the world context.
| Function | Description |
|---|
StartNewGame(Slot, CharacterName) | Create a fresh save and make it the active slot. |
SaveGame() | Save systems + world actors to the active slot. Returns false (and logs) if no slot is active. |
QuickSave(DisplayName) / AutoSave(DisplayName) | Write a rotating quick / auto snapshot without changing the active slot. |
LoadGame(Slot) | Load a slot; world state restores automatically. |
GetSaveSlots() | Headers for every manual slot - populate a load / continue menu. |
DeleteSlot(Slot) | Delete all files for a slot. Irreversible. |
HasActiveSaveSlot() | True if a game has been started or loaded. |
Data types
| Type | Kind | Description |
|---|
UCrimsonSaveGameFragmentBase | USaveGame (Blueprintable) | Base for custom save data. Holds FragmentVersion and the auto-serialized properties blob. Overridable: GetCurrentVersion, UpgradeFromVersion. |
UCrimsonSaveGameHeader | USaveGame (BlueprintType) | Per-slot metadata: DisplayName, SlotType, SaveDateTime, PlayTime, ThumbnailData. Overridable OnHeaderUpdate. Subclass via SaveGameHeaderClass. |
FCrimsonSaveWorldActorData | USTRUCT (BlueprintType) | Per-actor slab entry: transform, actor / component SaveGame blobs, object refs, non-property state, custom FInstancedStruct, destroyed / runtime flags. |
UCrimsonSaveWorldData | USaveGame | One per-level slab. TMap<FGuid, FCrimsonSaveWorldActorData>. Managed internally. |
UCrimsonSavePlayerIdentity | UBlueprintFunctionLibrary | ResolvePlayerSaveKey(PC) - stable per-player save key. |
ECrimsonSaveSlotType | UENUM (BlueprintType) | Manual / AutoSave / QuickSave. |
ECrimsonSaveSessionMode | UENUM (BlueprintType) | AutoDetect / SinglePlayer / ListenServer / DedicatedServer - controls save-authority logic. |
Developer Settings
Project Settings -> Crimson -> Crimson Save Game Manager (UCrimsonSaveGameManagerDeveloperSettings, stored in Config/DefaultGame.ini).
PIE
| Setting | Default | Description |
|---|
DefaultPIESaveSlot | 0 | Slot index automatically activated when playing in the editor. |
DefaultPIECharacterName | EditorCharacter | Character name used when creating a new PIE debug save. |
bResetPIESaveSlotOnStart | false | Delete and recreate the PIE slot on every PIE start - clean state each play. |
MainMenuMap | (empty) | A map that starts PIE without forcing a save load - lets the main menu work in PIE. |
PIEPlayerKeys | [PIE_Server, PIE_Client1, PIE_Client2, PIE_Client3] | Named save keys per PIE window by instance ID. Index 0 = server/standalone, 1 = first client, etc. |
Session mode
| Setting | Default | Description |
|---|
SessionMode | AutoDetect | AutoDetect reads GetNetMode() at runtime. Override only when your topology doesn't match UE's net mode. |
DedicatedServerDefaultSlot | 0 | Slot the dedicated server loads on startup. Override with -CrimsonSaveSlot=N. |
Multiplayer automation
| Setting | Default | Description |
|---|
bAutoLoadOnPostLogin | true | NotifyPlayerLoggedIn auto-calls LoadFragmentsForPlayer. Disable for manual timing. |
bAutoSaveOnLogout | true | NotifyPlayerLoggedOut synchronously flushes the player's fragments. Disable for manual timing. |
bAutoSaveOnExit | true | Your game mode synchronously saves the active slot on shutdown, so "change then quit" persists. Honor it via SaveGameToActiveSlotSynchronous() in EndPlay. |
Rotating saves
| Setting | Default | Description |
|---|
MaxAutoSaves | 3 | Rotating auto-save slots (10000-10009). Oldest overwritten at the limit. |
MaxQuickSaves | 3 | Rotating quick-save slots (10100-10109). Oldest overwritten at the limit. |
World state
| Setting | Default | Description |
|---|
bAutoCaptureActorsOnSave | true | Every save (and streaming-level unload) scans loaded levels for ICrimsonSaveableActor and captures them. This is what makes implementing the interface enough. |
bIncludeWorldStateInMainSave | true | RequestSaveProgress / auto / quick / new-game saves also flush world actor state - one call saves everything. |
bAutoLoadWorldState | true | Apply world slabs automatically when a load completes. False = call LoadWorldState() yourself. |
bSaveWorldStateAfterEveryChange | false | Flush slabs on every OnActorStateChanged. Incremental; a cost on large worlds. |
bResolveCrossObjectReferences | true | Store SaveGame actor-pointer properties as GUIDs and re-resolve them after load. |
bSupportWorldPartition | true | Handle World Partition runtime cells (they stream as levels). Disable to skip WP cells. |
Header & logging
| Setting | Default | Description |
|---|
SaveGameHeaderClass | (empty = UCrimsonSaveGameHeader) | Subclass to add custom slot metadata (chapter, portrait, difficulty). Set your subclass here. |
bVerboseLogging | false | Logs per-fragment save/load, registration, slab paging, cache delivery. Enable during integration. |
CrimsonCore integration types
These ship in the CrimsonCore plugin (which depends on CrimsonSaveSystem) and provide the turnkey layer.
| Type | Kind | Description |
|---|
ACrimsonPersistentActor | AActor (Blueprintable) | Ready-made base that implements ICrimsonSaveableActor. Derive, mark properties SaveGame, done. |
ACrimsonPlayerState | APlayerState | Implements ICrimsonSaveableSystem; saves stat tags + squad id as a player-scoped fragment. Extend via GatherPlayerSaveData / RestorePlayerSaveData. |
UCrimsonPlayerStateSaveFragment | UCrimsonSaveGameFragmentBase | The player-state fragment payload. Subclass to persist additional per-player data. |
ACrimsonGameMode | AGameModeBase | Forwards login / logout and saves on exit automatically. |
MCP tools (AI agents)
One UToolsetDefinition toolset (module CrimsonSaveSystemEditor) lets an AI agent read and drive the save system in a running PIE session over MCP. It registers only when Crimson MCP is enabled (Project Settings -> Crimson -> Crimson MCP; requires an editor restart - see CrimsonEditorUtilities -> Quick Start). The save manager is a GameInstance subsystem and save/load operations are server / standalone only, so every tool operates on the authoritative (server / standalone) PIE world's GameInstance, and the act tools require it. Errors surface to the agent as a script error.
| Tool | Kind | Description |
|---|
GetActiveSave | read | Active slot index + header (display/type/saved-at/playtime/version), session total playtime, and whether this world can save. |
ListSaveSlots | read | Every manual slot on disk with its recovered index, display name, type, saved-at, playtime, and version. |
ListSaveableWorldActors | read | World actors implementing ICrimsonSaveableActor (label + class) - what a save will capture. |
StartNewGame | act | Create a fresh save in a slot and make it active. |
SaveGame | act | Save progress to the active slot (registered systems + world state). |
QuickSave | act | Rotating quick-save snapshot (active slot unchanged). |
AutoSave | act | Rotating auto-save snapshot (active slot unchanged). |
LoadGame | act | Load a slot synchronously (systems + world state). |