Core concepts
Why a model instead of the object itself?
Pulse Save is built around one idea: you save a small, explicit model, not your live gameplay object.
Live object (AActor, UObject, ...) <-- OnSave / OnPostLoad --> UPulseSaveModel (persisted)
This is the same separation MVVM uses between a view and its view-model:
- The model only contains the data that actually needs to persist (health, inventory ids, a position), declared explicitly as
UPROPERTY()fields on a smallUPulseSaveModelsubclass. - Your live object stays free to have transient components, delegates, widgets, physics state, render state, etc. None of that has to be save-safe or even considered, because it is never serialized directly.
- Data moves between the two only at two points:
IPulseSaveInterface::OnSave(copy live -> model) andIPulseSaveInterface::OnPostLoad(copy model -> live), giving you one obvious place to reason about save compatibility, versioning and migrations.
By default (bSerializeAllSaveGameProperties = false on UPulseSaveModel), nothing is copied automatically: you own the mapping explicitly. If an object does not define its own UPulseSaveModel class, the default model class from the settings is used. That default is UPulseDefaultObjectSaveModel: it has bSerializeAllSaveGameProperties = true and serializes all UPROPERTY(SaveGame) properties of the object in its OnPostSave method.
bool AMyActor::OnSave_Implementation(UPulseSaveManager* SaveManager, UPulseSaveModel* SaveModel)
{
if (UMyActorModel* MyModel = Cast<UMyActorModel>(SaveModel))
{
MyModel->Health = Health;
MyModel->InventoryIds = Inventory->GetItemIds();
}
return true;
}
bool AMyActor::OnPostLoad_Implementation(UPulseSaveManager* SaveManager, UPulseSaveModel* SaveModel)
{
if (const UMyActorModel* MyModel = Cast<UMyActorModel>(SaveModel))
{
Health = MyModel->Health;
Inventory->SetItemIds(MyModel->InventoryIds);
}
return true;
}
You can opt back into “serialize every SaveGame property automatically” per model by setting bSerializeAllSaveGameProperties = true on that model class. This is useful for quick prototypes, but the explicit approach above is recommended for anything you intend to keep long-term, since it keeps the model as a stable, minimal save contract that survives refactors of the live object.
Objects without a matching live instance to bind to (e.g. simple global/save-slot metadata such as a save name or playtime) don’t need this dance at all. See the static model API in Models and collectors.
Save game wrappers
Pulse Save uses three save-game wrapper structs:
FPulseSaveGame: value handle to the shared, serialized payload.FPulseWeakSaveGame: weak reference wrapper.FPulseStrongSaveGame: strong reference wrapper; convert withPin()back toFPulseSaveGame.
The save manager keeps its save game as a strong reference, so the data stays alive while the manager works on it; GetSaveGame() returns it. The save game of the game gives its manager a new save game on New Game and the loaded one on Load Game, and Save Game writes it into a slot of a storage (see below).
Slots and storage
A save game is kept as bytes in a slot of a save storage:
FPulseSaveGame --Save Game--> entry of a slot --> slots of an owner --> storage (Files, Platform, a cloud, ...)
- A storage (
UPulseSaveStorage) keeps bytes only. PulseSave serializes, checks and migrates. Each purpose has its own storage:Pulse.Save.Storage.Game(the slots of the game),Pulse.Save.Storage.Profile(the profile of each local player) andPulse.Save.Storage.Server(data the server keeps for itself and its players). The default is Files: folders on this machine. Platform keeps the slots in the save games of the platform, Memory in memory only. Project Settings > Pulse > Save > Storage names another class, or the game sets one at runtime. - An owner (
FPulseSaveOwner) says whose slots they are: a local user, the server, or a player by key. - A slot (
FPulseSaveSlotRef: storage, owner and slot name) holds entries (FPulseSaveSlotEntryId): the save game (Game), the meta of the slot (slot_meta) and any data of the game next to them. A save writes its entries as one package: every entry lands, or none does. A storage can keep the previous version of each entry; a load of a damaged save falls back to it. - A storage never answers inside the call. The answer comes on a later tick, through
Done. Requests on one slot run one after another.
See Storage and Slots of a storage.
Save game, session and profiles
A game does not call the manager or the storage itself. Three subsystems do it:
- The save game (
UPulseSaveGameSubsystem, game instance) is the one API of a game for saving and loading: one save manager made from the settings Project Settings > Pulse > Save > Game, the slots of its owner (GetOwner()) in the storage of the purpose Game with their list (IsSlotListReady,GetSlots,OnSlotsChanged), and the requestsNewGame,SaveGame,LoadGame,DeleteSlot,AutoSave,SavePlayer,ApplyPlayer,SaveObject,LoadObjectandEndGame. A request that reads or writes a storage or waits for objects answers once with anFPulseResult, never inside the call (an async node in Blueprint); a request that only changes memory answers at once.MakeSlot(SlotName)gives theFPulseSaveSlotRefof one of its slots. See The save game of the game. - The session (
UPulseSaveSessionSubsystem, game instance) is the engine of the save game: New Game, Save Game and Load Game give it the manager and the slot of the running game. On the server it keeps the data of players who leave and gives it back when they join, and it runs the auto saves and their locks. A game uses it through the save game (AutoSave,LockAutoSave,SavePlayer,ApplyPlayer). See Player data and auto saves (session). - The profile (
UPulseSaveProfileSubsystem, local player) gives every local player aUPulseSaveProfilein a slot of its own in the storage of the purpose Profile. With a storage elsewhere (a cloud) it may load a moment later (IsProfileLoaded,WhenProfileLoaded). See Profiles of the players.
Save records
Each model is serialized into FPulseSaveModelRecord:
Type(EPulseSaveRecordType)Identifier(FName)bPersistentModelClassPathandModelVersionSaveData(TArray<uint8>)
FPulseSaveGame stores all records in one list. The record type says which kind of model a record belongs to, and the model chooses it (UPulseSaveModelBase::GetRecordType()):
| Type | Models | How they are handled |
|---|---|---|
Collected | Object models (UPulseSaveModel) and custom models of collectors | Gathered by collectors and processed asynchronously (chunks, processors, timeout) by every save and load. |
Static | Static models (UPulseStaticSaveModelBase, see Models and collectors) | Requested by code with GetOrCreateStaticModel, loaded and saved synchronously. Always persistent. |
Identifiers are unique per type: a static model and an object may use the same identifier.
Records stay in the save game until their object is destroyed for good. An object that is not in the world when the game saves (a chest in an unloaded cell, the inventory of a co-op guest who is offline) keeps its record as it was: a save writes only models whose object is in the world now. A load that finds no object for a record leaves it in the save game (counted in KeptWithoutObjectCount, no failure). It does not spawn a copy of a placed actor whose level is not loaded (the actor model remembers bWasPlaced), but a placed actor destroyed in this session whose level is loaded comes back when the save is loaded in place. It never spawns the objects of players (records of the kind Player): the session applies them when the player joins.
Tombstones: when a saveable actor is destroyed (DestroyActor), the next save turns the record of a placed actor (loaded with its level) into a tombstone and removes the record of a spawned one. This covers objects with IPulseSaveInterface and objects that save themselves as bytes. Not destroyed for good are: actors of players that leave with their player (controller, player state, the pawn while its controller goes; a vehicle destroyed while a player drives it counts as destroyed), records of the kind Player (MarkDestroyed still removes them), and actors whose level streams out. A destroy is forgotten once an object with that identifier is saved or loaded again, and a load decides anew what is destroyed. Objects destroyed while a save runs (phase 1 spans frames) are not written as alive. Loading a tombstone tells the object OnLoadFailed with Destroyed and destroys its actor again (bDestroyObjectsWithTombstone), so a broken chest stays broken although the level brings it back; this also works for objects that load themselves later (Load Object, Load On Register). Objects that are no actors are marked with MarkDestroyed(Object, bPlaced) of the save manager; RemoveRecord(Identifier) of the save game drops a record by hand.
The rules work on ids only (Data/PulseSaveTombstonePlan.h): Pulse::Save::PlanTombstones(SaveGame, DestroyedObjects, FormerIds) plans which records go, which become tombstones and which already are (the destroyed objects come from UPulseSaveDestroyTracker::GetDestroyedObjects; a record still under a former id of a placed object is moved to the current id first, records of a spawned object go under both). The tombstone records are made first (MakeTombstoneRecord), then ApplyTombstones changes the save game in one pass. A tombstone that cannot be written leaves its record as it was and is tried again on the next save.
IsPersistent() is stored with the record; it does not decide whether a record is dropped.
A record also stores the ModelVersion (UPulseSaveModelBase::GetModelVersion()). Together with ModelClassPath it is used to migrate saves that were written by another model class or an older model version, see Save migration.
The save game format has a version (PULSE_SAVE_SAVE_GAME_VERSION, PULSE_SAVE_MODEL_RECORD_VERSION). A save game or record of an older format is not loaded: LoadGameFromByteArray returns an invalid save game and logs Save game version X is not supported.
Save interface contract
Objects must implement UPulseSaveInterface to participate in save/load. Every function is a BlueprintNativeEvent with a default (no-op / neutral) implementation, so a minimal, practical implementation only needs to:
- Give it a name for its record: a Save Identity (
GetSaveIdentity(), a tag and a key, the same keys as objects that save as bytes) or a stable, uniqueGetUniqueSaveIdentifier()(an own identifier wins). - Provide save/load readiness through
IsReadyToSave/IsReadyToLoadif asynchronous behavior is needed (e.g. waiting for a streamed level or an async load to finish). - Implement
OnSave/OnPostLoad(see Why a model instead of the object itself?) and any other callbacks your object needs (OnLoad,OnPostSave,OnLoadFailed,ShouldSave, …).
If identifiers (Pulse::Save::GetObjectSaveIdentifier: the own identifier, else the key of the Save Identity) are invalid (NAME_None) or duplicated across objects, the affected object/model is skipped and counted in FPulseSaveProcessReport (see Save manager workflow).
Save model lifecycle
The manager processes models in this order:
- Read the record into the model, with a migration when needed (load path only)
OnPreSave()/OnPreLoad()(an object model callsOnLoadof its object here)- Poll readiness (
IsReadyToSave()/IsReadyToLoad()) until ready or timed out OnPostSave()/OnPostLoad()- Serialize model data into save records (save path only)
Collectors
Collectors define which objects are included:
UPulseSaveWorldCollector, the default of the save game: actors and components withIPulseSaveInterface, actors and components that save themselves as bytes, and save carriers, in one pass over the world.UPulseSaveActorCollector: iterates world actors and their components that implementIPulseSaveInterface.UPulseSaveByteCollector: actors and components that save themselves as bytes (IPulseByteSaveable), plus registered objects.UPulseSaveRegisterCollector: manually register/unregister objects at runtime.- Custom subclasses of
UPulseSaveCollectorBase.
The save game uses the collectors of Collector Classes (Project Settings > Pulse > Save > Game). See Models and collectors for details on each, and Customize for what else a game can change.
Replacing and switching off subsystems
UPulseSaveUISubsystem (module PulseSaveUI) is switchable: add it to Project Settings > Pulse > Foundation > Subsystems > Disabled Subsystems when your game brings its own save and load menu. The menu and the save UI handler of each local player then stay away. Saving and loading stay: the save game, session, profiles and storage keep working. How the list works: Replacing and switching off subsystems of Pulse Foundation.
The other subsystems of Pulse Save stay on, because other plugins build on them (save game, session, profiles, storage, play time); their behaviour is exchangeable through the classes in the settings (Customize). Every caller of the save UI handles its absence: UPulseSaveUISubsystem::Get and the Blueprint getter give None, the save widgets show nothing.
Spec: PulseSaveUI.Subsystems.