Save manager workflow
A game saves and loads through one API: the save game of the game (UPulseSaveGameSubsystem). With PulseGameplay the frontend calls it through PulseGameplaySaveBridge; without PulseGameplay the game calls its functions and async nodes. It only saves and loads: it starts no game and shows no menus. The profile of each local player (UPulseSaveProfileSubsystem) keeps what a player keeps from game to game.
Both run on a save manager (UPulseSaveManager), the engine that collects the objects and runs their models. The session (UPulseSaveSessionSubsystem) is the engine of the save game for the data of players and for auto saves. A game calls neither of them.
The save game of the game
UPulseSaveGameSubsystem (Game/PulseSaveGameSubsystem.h, game instance) is the save game of a game: one save manager made from the block Game of the save settings (ManagerClass, CollectorClasses, EntryId, SlotPrefix), the slots it keeps in the storage of the save game (Pulse.Save.Storage.Game, see Storage) with their list, the slot the game was saved into or loaded from, and the session, which it sets itself. A game that saves with it needs no manager or session code of its own.
A request that reads or writes a storage or waits for objects answers once with an FPulseResult, and never inside the call: through Done (FPulseSaveGameDone) in C++, through the pin On Done of its async node in Blueprint. Done comes on the next frame at the earliest, also when the request cannot start. The result is success, or a reason with a text for the player (Pulse.Result.Failure.Save.*, listed in the API reference). Only the host saves and loads: on a client the requests answer HostOnly.
| Request | Blueprint | What it does |
|---|---|---|
SaveGame(SlotName, DisplayName, Done) | Save Game (Async) | Captures the preview picture, saves the entry and its meta in one package and makes the slot the slot of the session. The first save without a New Game starts a save game. |
LoadGame(SlotName, Done) | Load Game (Async) | Loads the entry (with the check before the load and the previous version of a damaged save), takes the meta of the loaded save, plays on from its play time and makes the slot the slot of the session. |
DeleteSlot(SlotName, Done) | Delete Slot (Async) | Deletes the slot with its previous versions and meta; Done gets the result once the storage deleted it. The session forgets the slot when it was its slot. |
AutoSave(Reason, Done) | Auto Save (Async) | Saves into the slot of the session now (see Auto saves). |
SavePlayer(Player, Done) / ApplyPlayer(Player, Done) | Save Player (Async) / Apply Player (Async) | Saves the data of a player into the save game in memory, or gives it back (see Players). |
SaveObject(Object, Done) / LoadObject(Object, Done) | Save Object (Async) / Load Object (Async) | Saves one object into the save game in memory, or loads it from there (see Single objects). |
RefreshSlots(Done) | Refresh Slots | Lists the slots again with their meta; Done (optional, C++) gets the slots. |
A request that only changes memory or reads a state answers at once:
| Request | What it does |
|---|---|
NewGame() | An empty save game without a slot, the play time from 0; returns success or why not. The session keeps the data of players; auto saves wait for the first save into a slot. |
EndGame() | For the main menu: no current slot and no session, so nothing is auto saved into the last slot while the menu is shown. |
CanSave() / CanLoad() / CanSaveToSlot(SlotName) / CanLoadFromSlot(SlotName) | What a save or load would answer now, so a menu can tell before it asks. |
LockAutoSave(Reason) / UnlockAutoSave(Handle) / IsAutoSaveLocked() | Hold auto saves back (see Auto saves). |
GetOrCreateStaticModel(Identifier, ModelClass) / SaveStaticModel(Model) / RemoveRecord(Identifier) | Static models and records of the save game in memory (see Static models and records). |
GetLastSaveReport() / GetLastLoadReport() / IsBusy() | The reports of the last save and load, and whether one runs (see Reports and state). |
The save game keeps the slot list of its owner (GetOwner(): the server on a dedicated server, else the first local user of this machine): the slots in its storage that start with SlotPrefix, newest first, with their meta, never the slots of player profiles. It lists them when the game instance starts, and the storage answers a moment later:
IsSlotListReady()is true once the slots were listed;GetSlots()is empty before.OnSlotsChanged(C++OnSlotsChangedNative) fires when the list changed: listed again (RefreshSlots), a save or a delete of the save game. The list is listed again when the storage of the save game changes, and on the next tick when the storage tells of slots it took from elsewhere (a mirror after a round; once for several notes).CountSlots()andCanMakeNewSlot()(againstMaxSlots) read the list.MakeNewSlotName()gives a name that no listed slot and no running save has (Save_0003); while the list is not ready it gives a name with the time (with_2,_3, … while that name is taken). With a mirror that has a secondary storage (a cloud) the name ends in 4 hex digits the save game draws once per game instance (Save_0003_a1b2): the same list gives the same name, and two machines that save before they compared their slots do not write the same slot.CanLoadFromSlot()answersSlotMissingonly while the list is ready; before,LoadGamefinds out.
A menu or a Continue button waits for the list: show it once IsSlotListReady() is true, or when OnSlotsChanged fires. The save menus of the plugin do this themselves. The save game does not delete the slot of a save or load that is running (Busy).
With a mirror (a cloud), slots also come from other machines. The list always comes from the storage of this machine, so it is ready as fast as without a cloud; the slots a round of the mirror brings show up a moment later through OnSlotsChanged. A main menu that wants them before it offers Continue waits for a round with Sync Save Storage (Async) (UPulseSaveStorageSubsystem::RequestSync). The mirror never replaces or deletes a slot the game uses: the current slot, the slot of the session (the auto saves, also the first slot of an Ironman game), a slot a save writes and a slot a load reads (Pulse::Save::Game::IsSlotOfGame). Such a slot waits: while one waits, a round comes every 30 seconds, and the first one after End Game takes what changed on the other machine, a delete too.
UPulseSaveGameSubsystem* saveGame = UPulseSaveGameSubsystem::Get(this);
saveGame->SaveGame(saveGame->MakeNewSlotName(), TEXT("Before the bridge"), FPulseSaveGameDone::CreateLambda([](const FPulseResult& InResult)
{
UE_LOG(LogTemp, Log, TEXT("Save: %s"), *InResult.ToString());
}));
In Blueprint the requests that answer later are async nodes with the pin On Done; the other functions are in the category Pulse > Save > Game.
Other plugins and the game hear about it on the message bus (payload FPulseSaveSlotMessage with the slot): Pulse.Message.Save.SlotWritten (also after an auto save of the session, with its reason in AutoSaveReason), Pulse.Message.Save.SlotLoaded and Pulse.Message.Save.SlotDeleted.
Auto saves
AutoSave(Reason, Done) (Blueprint Auto Save (Async)) saves the game into the slot of the session now. A game calls it for a checkpoint, every few minutes, or before it quits through its own menu (it quits once Done answered). The triggers of the session save on their own (see Player data and auto saves). Done answers once, never inside the call:
- Success once the slot was written, else a reason of the save or the storage.
NoSlotbefore the first save into a slot (a New Game that was not saved yet),NoGameorHostOnlywithout the world of the host. The save game answers these on the next frame.Lockedwhile a lock holds auto saves back,Busywhile a save or load of the game runs or an auto save started in this frame. The session answers these on its next tick.
A session that a plugin set with a manager of its own saves the same way. The first auto save of an Ironman game makes its slot (see Ironman).
LockAutoSave(Reason) holds auto saves back while something must not be saved halfway (a boss fight, a cut scene) and returns a handle for UnlockAutoSave(Handle); IsAutoSaveLocked() tells whether a lock holds. The locks belong to the session of a slot: when New Game, Save Game or Load Game moves the session to another slot, or End Game ends it, the auto saves start without locks.
Players
On the server the session saves a player who leaves and gives the data back when the player joins again (see Player data and auto saves). SavePlayer(Player, Done) and ApplyPlayer(Player, Done) (Blueprint Save Player (Async) and Apply Player (Async)) do the same by hand:
SavePlayersaves the saveable actors and components of the player (controller, player state, pawn) into the save game of the session, in memory. The next save writes them into the slot.ApplyPlayergives the player the data the save game holds for these objects. Objects without a record keep what they have.
Done answers once when every object answered, never inside the call: Success (also with nothing to save, or when the save game holds nothing of the player), the first failure (Failed), or NoGame without a session or save game.
Single objects
SaveObject(Object, Done) and LoadObject(Object, Done) (Blueprint Save Object (Async) and Load Object (Async)) process one object with the save game in memory, independent of the collectors: save an object right before it is destroyed, load an actor spawned while the game runs. The next save writes what SaveObject saved into the slot. Done answers once, never inside the call: Success, NoGame without a save game, or Failed (not saveable, no record of the object for a load, its model failed or timed out).
Both take objects with IPulseSaveInterface and objects that save themselves as bytes (IPulseByteSaveable of PulseFoundation, saved with UPulseByteSaveModel). Pulse::Save::IsSaveable and Pulse::Save::GetObjectSaveIdentifier (Models/PulseByteSaveModel.h) answer for both kinds; for the save interface the identifier is the own identifier, else the key of the Save Identity.
Static models and records
These change the save game in memory and answer at once. They never make the manager of the game: before New Game, Save Game or Load Game there is no save game, and they return null or false.
GetOrCreateStaticModel(Identifier, ModelClass)gets or makes a static model: data of the game that belongs to no object (a chosen name, the day of the game). It is read from its record when the save game has one, else made new. Every later save writes it and every load reads it again, so the model stays valid (see Models and collectors).SaveStaticModel(Model)writes a static model into the save game now and keeps it written by every later save.RemoveRecord(Identifier)removes the record of an object; the next save into a slot drops it. Records otherwise stay until their object is destroyed for good. It returns true if there was a record.
A saveable object gets the manager in the functions of the save interface and can call the same functions on it.
Reports and state
GetLastSaveReport() and GetLastLoadReport() return the reports of the last save and the last load of the game (see Diagnostics report), empty before the first one. IsBusy() is true while a save or load of the game runs, the write or read of its slot included.
Ironman
An Ironman game has one save that only the game writes: the player cannot save into another slot or go back to an earlier save. PulseSave registers the tuning switch Pulse.Tuning.Save.Ironman (category Save, off); a difficulty, the server rules or the game turn it on like any other tuning knob. The mode belongs to the game: IsIronman() reads the field Save.Ironman of the meta of its slot (Pulse::Save::Game::IronmanField), and only before the first save or load the switch in the world of the game decides. A normal slot stays a normal game when the switch is on later.
- One slot, written by auto saves.
SaveGame(the menus, Save Game (Async),PulseSaveToSlot) answersPulse.Result.Failure.Save.Ironman;CanSave()andCanSaveToSlot()say so before. The first auto save of the game makes its slot:AutoSaveof the game or a trigger of the session (On Quit, On Host Quit, Background, Focus Lost). The session asks the save game for the slot (UPulseSaveSessionSubsystem::SlotProvider) and writes it like every auto save of the session: a new name, a meta with the field, no picture. While the game quits, models that need more frames than the teardown gives are cancelled and no slot is made. Later auto saves write into the slot and keep the field. Only the host makes the slot. - The world New Game ran in makes no slot on its own. PulseGameplaySaveBridge starts a new game while the main menu is still the world, loads the level of the game behind it and tears the menu down; the triggers of that world do not make a slot (only an
AutoSavethe game asks for does). A game that calls New Game inside its level calls Auto Save (Async) once after it: that makes the slot, and from then on every trigger saves into it. A game without New Game gets the session of the game at its firstAutoSave; until then the triggers of the session have nothing to save. - No load while the game runs. After a save or a load,
LoadGameandCanLoad()answerIronman. AfterEndGame(the main menu) and afterNewGamethe slot loads like any other (PulseGameplaySaveBridge starts a new game before it loads the slot of Continue); the loaded game is an Ironman game again. - New games, deleting slots and auto saves are never held back. A running game keeps its mode when its slot is deleted: an Ironman game makes a new slot with its next auto save.
The rule is pure (Pulse::Save::Game::CheckIronman) and the menus show its reason like every other one.
Profiles of the players
UPulseSaveProfileSubsystem (Game/PulseSaveProfile.h, local player) gives every local player a profile: what a player keeps from game to game (unlocks, statistics, tutorials seen), independent of the save game of the world. Each player of a split screen has their own. The profile lives in a slot of its own among the slots of the platform user of the player, <ProfileSlotPrefix> (Profile; a player that shares its user with a player before it keeps its profile beside the profile of the user, Profile_1; in the editor each play window gets its own, Profile_PIE1), in the storage of profiles (Pulse.Save.Storage.Profile; files on this machine unless the game sets another storage). A player without a platform user keeps its profile with the first user of the machine. Once read, the profile is written back where it was read from, even when the user of the player changes. It loads like a save game: the check before the load and the previous version of a damaged slot.
The game writes the profile itself, in two ways that can be mixed:
- Variables: make a Blueprint of Pulse Save Profile, add variables, tick SaveGame on each (Advanced), and name the Blueprint in Project Settings > Pulse > Save > Profile (
ProfileClass). Get Save Profile, a cast to the Blueprint, then set the variables. - Free values under a gameplay tag, without a class of its own: Set Bool, Set Int, Add Int (counters), Set Float, Set String, Set Tags and Set Struct (any struct through Make Instanced Struct), read with the matching Get node. Take tags of the game for the keys (
Profile.Tutorial.Crafting).
UPulseSaveProfile* profile = UPulseSaveProfileSubsystem::GetSaveProfile(PlayerController);
profile->AddInt(TAG_ProfileBossesDefeated);
profile->SetTags(TAG_ProfileSkins, UnlockedSkins);
Other objects of the game join the profile with RegisterObject (an object with the save interface or one that saves itself as bytes); it gets its data at once when the profile has some for it. While an object still loads its data (an object that loads later), SaveProfile waits for it, so a save never writes the data of before the load over the slot.
Nothing happens until the game asks: the first Get Save Profile, RegisterObject or SaveProfile reads the slot. With a storage on this machine the profile has its data when the call returns, and objects that load at once (the profile object always does) are done before it returns. With a storage elsewhere (a cloud) the data comes a moment later: IsProfileLoaded() tells whether it is there, OnProfileLoaded fires when it comes, and WhenProfileLoaded(Then) (Blueprint Wait For Profile (Async)) runs once it is there (at once when it is). A read that fails for now (offline, timed out) keeps what the profile had (the defaults at first) and makes IsPersistable() false: SaveProfile does not write it over the slot until LoadProfile worked.
SaveProfile (Blueprint Save Profile (Async)) writes the slot; it reads the slot first if nobody asked for the profile yet, so it never replaces a profile with an empty one. With bSaveProfilesOnQuit (on by default) a profile that changed is saved when its local player goes: the game ends, or a play session in the editor stops. An unchanged profile stays as it is, so a profile that was only read never gets a newer time than the changes of another machine. IsProfileChanged() tells whether the profile changed since it was last saved or read. The setters (Set Bool, Add Int, Remove Value, …) count as changes, and the profile compares the content of its objects with what it last saved or read: the SaveGame variables of the profile class and of objects joined with RegisterObject that have the save interface (saved by the default model), and the bytes of joined objects that save themselves at once. An object whose saved data is not in its SaveGame variables (a model of its own, variables filled in OnSave), or that saves its bytes later (asynchronous), calls MarkProfileChanged() (Blueprint Mark Profile Changed) when it changed. An object whose data in the slot this build cannot read keeps that data until the game changes the object. ResetProfile(Done) (Blueprint Reset Profile (Async)) puts the profile back to the defaults of its class at once (the same object, so references stay valid) and deletes the slot; Done answers once the storage deleted it (success also when there was no slot). SetStorage(Storage) keeps one profile in a storage of its own (a cloud of one player, a spec). Profiles are local: the server of a multiplayer game never sees the profile of a client.
With a mirror as the storage of profiles (a cloud), a profile that changed on another machine comes back here:
- The mirror leaves the slot of a profile alone while the profile has changes, is read or saved, or an object of it loads (
IsProfileInUse()); the next round after the save compares again. - A profile without changes reads its slot again on the next tick after a round brought a newer version, and
OnProfileLoadedfires again. A read that runs reads once more when it is done. A profile with changes keeps them; after its next save the conflict rule of the mirror decides (by default the newer version, so this save). - A profile in a storage of its own (
SetStorage) is not told by the storage subsystem: the game callsNoteSlotChanged()when that storage tells of a change.
Player data and auto saves (session)
UPulseSaveSessionSubsystem (Game/PulseSaveSession.h, game instance) is the engine of the save game for the data of players and for auto saves. It knows the running save: the manager whose save game holds the game, and the slot auto saves write. The save game of the game sets it for New Game, Save Game and Load Game and ends it with End Game. A game uses the functions of the save game; the functions of the session are for plugins and specs (see The session in C++).
- Players who leave are saved on the server when their controller is destroyed, before the engine takes the pawn and the player state away (the logout comes after that): every saveable actor and component of the player (controller, player state, pawn, see
GatherPlayerObjects) goes into the save game of the manager withSaveSingleObject, in memory, under the identifiers of the objects (Player.<player id>.*for player actors, seePulse::Player::GetPlayerId). Synchronous objects are written inside the call; the call waits only for the player’s own saves (never for a running full save) and only while they make progress, asynchronous ones finish later with the identifier they took. Every server world is watched, also the one after a seamless travel. Objects that opt out (ShouldSave/ShouldSaveBytes) are skipped. The next save of the session writes it into the slot. - Players who join get that data back (
GameModePostLoginEvent, and once for their first pawn): only objects that have a record are loaded, so a new player starts fresh without warnings. A respawn later keeps the state of the session. SavePlayerandApplyPlayerof the save game do the same by hand (see Players).bKeepPlayerDatain the settings turns the automatic part off.- Auto saves write the whole session into its slot: the storage, owner and slot the save game gave the session (the slots the save menu shows). Each trigger is its own setting in
AutoSaveTriggersand off by default:bOnHostQuit(the world of the host or single player tears down, not on a seamless travel),bOnBackground(the application goes to the background),bOnFocusLost(the window loses the focus: Slate on desktop, the deactivation on phones) andbOnQuit(the application quits: the worlds tear down before the game instance shuts down). The saves ofbOnHostQuitandbOnQuitrun inside the teardown: synchronous models are written, asynchronous ones that need more frames are cancelled after a second. Games ask for every other auto save with Auto Save (Async) (see Auto saves). - Locks hold auto saves back. A held back auto save is logged with the reasons, reported through
OnAutoSaveNativewithbStarted = falseand answersLocked. At most one auto save starts per frame, and none while the manager is busy (Busy). Locks end with the session, so a lock whose owner is gone does not hold back the auto saves of the next game. - There is no host migration: when the host leaves, the session ends with it.
- Auto saves write the entry, and the meta with it when the slot has one, in one package (
SaveToSlotWithMeta): the date, the play time, the level and the save list fields of now, the name and the preview picture of the last save of the menus (an auto save takes no picture; fields the game wrote into the meta stay). The rule isPulse::Save::MakeAutoSaveMeta. A slot without a meta stays without one.
The rules are plain data and pure functions (Game/PulseSaveSessionState.h), so they can be tested without a world: the subsystem keeps an FPulseSaveSessionState (storage, owner, slot, entry, locks, frame of the last auto save). Pulse::Save::MakeSessionState and ClearSessionState say what SetSessionManager and ClearSession keep, DecideAutoSave decides an auto save (EPulseAutoSaveDecision: NoSession, Locked, SameFrame, Busy, Save, in that order) and GetAutoSaveReason turns an FPulseAutoSaveEvent (teardown, background, focus lost) and the triggers into the reason (Quit, HostQuit, Background, FocusLost, or none). A teardown while quitting saves as Quit with bOnQuit, else as HostQuit with bOnHostQuit.
The session in C++
The functions of the session are C++ only, for plugins and specs. Only GetSessionSlot() and GetSessionSlotRef() (the slot auto saves write, with its storage and owner) are also Blueprint functions.
SetSessionManager(Manager, Slot, EntryId)sets the running save: a manager whose save game holds the game, and the slot of a storage auto saves write (an empty slot name: no auto saves untilSlotProvidernames one). A plugin or a spec that keeps a game in a manager of its own sets it; a new session starts without locks.ClearSession()ends the session,GetSessionManager()returns its manager.AutoSave(Reason, Done)saves the session into its slot now. A refusal answers throughDoneon the next tick:Locked,NoSlotwithout a session or a slot,Busywhile the manager saves or loads or an auto save started in this frame. A started save answers with the result of the write, afterOnAutoSaveFinishedNative.SavePlayer(Player, Done)andApplyPlayer(Player, Done)return the objects whose save or load started.Doneanswers like the functions of the save game (see Players).LockAutoSave(Reason),UnlockAutoSave(Handle)andIsAutoSaveLocked()are what the save game forwards to.OnAutoSaveNative(Reason,bStarted) fires for every auto save that ran or was held back.OnAutoSaveFinishedNative(Reason,const FPulseResult& Result) fires when an auto save that started was written or failed, also for the triggers, which have noDone.SlotProvidernames the first slot when an auto save finds none (the save game binds it for the one slot of an Ironman game).GetLastWrittenMeta(OutMeta)returns the meta the last auto save wrote with its entry.
The save manager
UPulseSaveManager (Manager/PulseSaveManager.h) is the engine of the save game and of the profiles: it collects the objects, runs their models and writes the save game into a slot of a storage. The save game makes its manager from ManagerClass of the save settings (a subclass of your own, or UPulseSaveManager); each profile has a UPulseSaveManager of its own. A game does not create or run a manager.
The manager is also the type saveable objects get: the functions of IPulseSaveInterface take it (ShouldSave, OnSave, OnPostLoad, …), and models live inside it. In Blueprint it offers what saveable objects call from there (Get Or Create Static Model, Save Static Model, Remove Record, Mark Destroyed), the collectors, the reports, the states and the events. Its process functions (StartProcess, Save, Load, CancelProcess, SetSaveGame, ClearSaveGame, SaveSingleObject, LoadSingleObject) and its slot functions are C++, for plugins and specs. They reach the manager of the game with UPulseSaveGameSubsystem::GetManager() (made on first use) or FindManager() (null before its first use).
Manager state
UPulseSaveManager exposes EPulseSaveManagerStateType:
IdleSavingLoading
Query it with GetCurrentState(), or use the convenience helpers IsIdle(), IsSaving(), IsLoading(), CanSave(), CanLoad() (the latter two also check that a save game is set and that CanStartProcess of the manager class allows the process).
Save flow (UPulseSaveManager::Save / StartProcess(Save))
- Validates the manager is idle and a save game is set (
CanStartProcesslets a manager subclass refuse). - The records of objects destroyed since the last save become tombstones or go (see Core concepts), and all registered static models are written into the save game (synchronously).
- Collects save objects from all registered collectors (
GetSaveModels). - Resolves or creates a
UPulseSaveModelper object identifier (GetOrCreateModelForObject). - Processes models per chunk (
OnPreSave -> IsReadyToSave (polled) -> OnPostSave), in two phases (below). - Writes each model into a
CollectedFPulseSaveModelRecord(persistent or not, see Core concepts). - Completes the process, updating
GetLastProcessReport()and broadcastingOnProcessed()/OnProcessedEventandOnProcessedWithReport()/OnProcessedWithReportEvent.
If a model is not yet ready, processing continues on subsequent ticks until it succeeds, fails, or times out (see below).
Two phases
A save should show one moment: the quest that counts the fifth ore and the inventory that holds it. Most models are synchronous: their data is taken in the frame they start. Asynchronous models (GetSaveTiming, for example the quest manager, which saves on its next tick) take frames, and say which moment their data shows (GetSaveCapture):
| Capture | What the save does |
|---|---|
AtRequest (default) | The model takes its data at once and only finishes later: every model starts in the frame of the request |
AtEnd | The model’s data shows the frame it finished in: the save runs the asynchronous models first and takes every synchronous model together in the frame the last one finished |
The report shows bCapturedAtEnd and MaxCaptureGapFrames; the entry of an asynchronous model whose data is from another frame than the synchronous models says how many frames and in which direction. The frames are the ones the models really ran in: the processor pool starts processors on its tick, synchronous models never wait for a free slot (they finish inside their start), and in a single chunk the synchronous models start first. A save fails as soon as a model of an earlier phase failed; phase 2 does not start then. While a save runs, actions that change several systems at once can wait for its end with When Pulse Saved of Pulse Foundation.
The plan is the pure function Pulse::Save::PlanChunks(Type, Models) (Data/PulseSaveChunkPlan.h): it takes what it needs of each model (MakeChunkModel: load priority, save timing, capture) and returns the chunks as indices plus bCapturedAtEnd. Loads get one chunk per load priority, higher first. A manager subclass that overrides BuildChunks can call it and change the result.
The save manager reports every save to the save status of Pulse Foundation (Pulse.Message.Save.Started, .Phase with Collect for the asynchronous and Capture for the synchronous models, .Finished) and holds its load barrier while a load runs (Pulse.Message.Save.LoadStarted / LoadFinished), so plugins without PulseSave can react.
When nothing was collected to save (no collector returned an object, or every object’s ShouldSave returned No), Save() completes inside the call, without a tick, with success and returns true; the static models are written all the same.
Without a save game (SetSaveGame was never called and no slot was loaded) Save() and Load() log an error, call the completion delegate with false and return false.
Load flow (UPulseSaveManager::Load / StartProcess(Load))
- After the same checks as a save, all registered static models are loaded in place from the save game (synchronously). They do not take part in the steps below.
- Loads models from the
Collectedrecords of the currently set save game. - Collects load objects from all registered collectors and maps them to loaded models by identifier. Objects with no matching record trigger
IPulseSaveInterface::OnLoadFailedwithEPulseSaveLoadFailureType::ObjectNotFound. - Groups the models into chunks, ordered by
GetLoadPriority()(higher first). Models that only have the default priority (custom models of collectors) load after all object models. - Processes models per chunk (
OnPreLoad -> IsReadyToLoad (polled) -> OnPostLoad). - Completes the process the same way as the save flow.
Single-object processes
SaveSingleObject(Object) and LoadSingleObject(Object) process one object directly, independent of collectors and of GetCurrentState(). SaveObject and LoadObject of the save game and the player data of the session run on them. Completion is reported through OnProcessedSingle() (native, FPulseSaveManagerProcessedSingleSignature) and OnProcessedSingleEvent (Blueprint-assignable).
Completion of one call
OnProcessed()/OnProcessedEvent/OnProcessedSingle()/OnProcessedSingleEvent are persistent multicast delegates: once bound, they fire on every future Save()/Load() (or SaveSingleObject()/LoadSingleObject()) call until manually unbound. In C++ a call can also take a one-shot completion delegate: it fires exactly once for that call and is discarded afterwards, no unbinding needed: Save(OnComplete), Load(OnComplete) and StartProcess(ProcessType, OnComplete) take a FPulseSaveManagerProcessedDelegate, SaveSingleObject(Object, OnComplete) and LoadSingleObject(Object, OnComplete) a FPulseSaveManagerProcessedSingleDelegate.
Diagnostics report
Every completed process (Save, Load, or a single-object call also updates OnProcessedSingle, but the report below only covers Save/Load) produces a FPulseSaveProcessReport, retrievable via GetLastProcessReport() or received directly through OnProcessedWithReport() / OnProcessedWithReportEvent:
| Field | Meaning |
|---|---|
ProcessType | Whether this report is for a save or a load. |
CollectedCount | Objects/records collected before deduplication/mapping. |
ModelsCreatedCount | Models newly created (not reused from cache). |
ModelsReusedCount | Models reused from the manager’s identifier cache. |
SkippedDuplicateCount | Objects skipped because another entry already used the same identifier. |
SkippedInvalidIdentifierCount | Objects skipped because they had no (valid) identifier. |
StaticModelsLoadedCount | Registered static models that were loaded from their record when Load() started. |
MigratedModelsCount | Records migrated to another model class or version (see Save migration). |
MigrationFallbackCount | Records without a registered migration that were handled by MigrationFallback. |
FailedModels | Array of {Identifier, Reason} for models that failed to process. |
TimeoutCount | Number of FailedModels that failed specifically due to a timeout. |
bCapturedAtEnd | Save: the synchronous models were taken after the asynchronous ones finished (an AtEnd model). |
MaxCaptureGapFrames | Save: the largest distance in frames between the data of a model and the synchronous models. |
KeptWithoutObjectCount / KeptWithoutObjectByKind | Load: records without object in the world now, in all and per kind of identifier. |
DurationSeconds | Total wall-clock duration of the process. The wait for the storage of a slot call is not in it. |
StorageWaitMs | Slot calls: wall time from the first request to the storage to its last answer. Requests that run at the same time (the entry and the meta of a load) count once. |
SlotQueueMs | Slot calls: how long the call waited for its slot (other calls on the same slot). |
SlotTotalMs | Slot calls: from the SaveToSlot or LoadFromSlot call to its answer; 0 otherwise. |
StorageRequestCount | Slot calls: requests to the storage. |
StorageWaits | Slot calls: an FPulseSaveStorageWait per request to the storage, in the order they were answered: Operation (ReadEntry or WriteEntries), Entry, Version, QueueMs (the wait of its slot work for the slot), WaitMs (from the request to its answer, the byte layers included), Bytes, bSucceeded, Reason, StartMs (from the slot call on). |
GameThreadMs | Time on the game thread: the manager’s own steps (collecting, starting the models, finishing them) and the work of every model in the pool (start, updates, writing the record). Frames spent waiting for asynchronous models do not count. |
FrameCount | Frames from the start to the end (1 when the process finished in the frame it started). |
CollectFrames | Save: frames of phase 1 (asynchronous models before the synchronous ones), 0 without such a phase. |
TotalSizeBytes | Sum of the record sizes of the processed models and the static records (kept records and tombstones not counted). |
SaveGameSizeBytes | Size of every record in the save game after the process (kept records, tombstones and static records too): the size of the file, used by the debugger. |
CaptureFrame | Save: the frame (from 1) the synchronous models really ran in. |
TombstoneCount | Tombstones in the save game after the process. |
Models | FPulseSaveModelStats per model, largest first: identifier, model class, kind (Bytes, Async, Tombstone, Static, Model, Kept), record size, wall time from its start to its end, frames (1 within one frame), success and a note. |
bWasSuccessful | Whether the process completed successfully overall. |
GetLastSaveReport() and GetLastLoadReport() keep the last save and the last load apart; GetLastProcessReport() is whichever ran last. The reads of a slot load come before its process and are in its report. The write of a slot save comes after its process: GetLastSaveReport() has the wait once the write answered, while OnProcessedWithReport() fires before the write and has no storage part. FPulseSaveSlotResult::StorageWaitMs tells the caller of a slot call the same wait, also when the call failed.
Use this to surface actionable diagnostics (e.g. in a debug UI or logs) without parsing engine logs.
The same information, plus a list of every processed model and the messages the models wrote, is recorded as a report and shown in the Pulse Debugger. See Reports.
Progress events
GetLastProcessReport() / OnProcessedWithReport() only report final results, once the whole process is done. For progress bars or loading-screen feedback while Save()/Load() is still running, use:
OnChunkProcessed()/OnChunkProcessedEvent: fires after each chunk (seeBuildChunks) finishes processing, withChunkIndex(1-based, chunks completed so far) andChunkCount(total chunks for the current process). Good for a coarse-grained progress bar.OnModelProcessed()/OnModelProcessedEvent: fires after each individual model finishes processing within a chunk, with the model’sIdentifier, whether it succeeded, and whether it specifically timed out. Fires more often thanOnChunkProcessed, useful for finer-grained progress (e.g. “12 / 340 objects saved”).
Both are ordinary multicast events (native DECLARE_MULTICAST_DELEGATE_* + BlueprintAssignable dynamic equivalent), following the same pattern as OnProcessed()/OnProcessedEvent.
Timeout behavior
The default per-model timeout is UPulseSaveSettings::DefaultProcessTimeout (default 60.0f seconds, -1 disables the timeout). A model can override this by implementing:
virtual bool GetTimeoutOverride(float& OutTimeout) const override;
Process control
Other useful manager functions:
ResetCachedSaveModels(): clears the object-model identifier cache used by the main process,GetOrCreateModelForObject, and the single-object functions. Static models are not part of it (they are managed by the static model registry). Clearing this cache forces new object models to be created on the next save/load access.AddCollector/AddCollectorByClass/RemoveCollector/GetCollectors(): manage collectors.GetOrCreateStaticModel/SaveStaticModel: global/save-slot metadata that isn’t bound to a live object. Static models are handled synchronously, outside of the chunks and processors. Registered static models are automatically written on everySave()and refreshed on everyLoad()(see Models and collectors).CancelProcess()(C++): cancels the currently runningSave()/Load(). Every running model processor is stopped (they are recorded as failed inGetLastProcessReport()), any pending chunks are discarded, and the manager returns toIdle.OnProcessed()/OnProcessedWithReport()still fire withbSuccess = false, so existing completion handling keeps working unchanged. Does nothing besides a warning log if the manager is already idle. Useful for level transitions, quitting, or a user-triggered cancel button while a save/load is in progress.
Slots of a storage
The manager writes its save game into a slot of a save storage and reads it back. A storage keeps bytes: the slots of an owner, and in each slot entries (FPulseSaveSlotEntryId: an optional category and an identifier, such as Game or Chunks/Forest). Which storage is used, where it keeps the bytes (files on this machine by default) and how to write one of your own is described in Storage. The save game and the profiles save and load with these calls; they are C++, for plugins and specs.
A slot is named by an FPulseSaveSlotRef: the storage, the owner (FPulseSaveOwner: a local user, the server, or a player by key) and the slot name. Make Slot of the save game gives a slot of the save game, UPulseSaveStorageSubsystem::MakeSlotRef(Purpose, Owner, SlotName) a slot in the storage of any purpose.
| Call | What it does |
|---|---|
SaveToSlot(Slot, EntryId, Done, ExtraEntries) | Runs Save() and writes the save game as one entry of the slot; further entries (data of the game next to the save) land in the same package. |
SaveToSlotWithMeta(Slot, EntryId, MakeMeta, Done, ExtraEntries) | Like SaveToSlot, with the meta of the slot in the same package; MakeMeta builds the meta from the current one (see Save with the slot meta). |
SaveToSlotWithMeta(Slot, EntryId, Meta, Done, ExtraEntries) | The same with a fixed meta (a save menu). |
LoadFromSlot(Slot, EntryId, Done, ModelRetentionPolicy) | Reads the entry and the meta, checks the save game, falls back to the previous version of a damaged save, sets the save game and runs Load(). |
IsFree() | True when the manager is idle and no slot load reads: a save or load may start. |
HasSlotWork() | True while a slot call of this manager is queued or runs. |
GetLastSlotLoaded() | What the last LoadFromSlot loaded (FPulseSaveSlotLoaded). |
Every call answers once through Done (FPulseSaveSlotDoneNative: the manager and an FPulseSaveSlotResult), on the game thread and never inside the call. A call returns false when it was refused at once (an invalid slot, the meta entry as the entry of the save game, a manager that is not free: Pulse.Result.Failure.Save.Busy); Done still comes on a later tick. Each call runs as slot work of the storage, so calls on one slot run one after another, also across managers and other callers.
FPulseSaveSlotResult holds the Result (success, or why not: busy, the process failed, damaged without a sound version, or a reason of the storage such as Pulse.Result.Failure.Save.Storage.Unavailable), Loaded (a load: what was loaded), bMetaWritten and Meta (a save with meta: the meta that was written), and StorageWaitMs (the wait for the storage, also when the call failed).
const FPulseSaveSlotRef slot = UPulseSaveGameSubsystem::Get(this)->MakeSlot(TEXT("Save_0001"));
Manager->SaveToSlot(slot, FPulseSaveSlotEntryId(TEXT("World")), FPulseSaveSlotDoneNative::CreateLambda([](UPulseSaveManager* InManager, const FPulseSaveSlotResult& InResult)
{
UE_LOG(LogTemp, Log, TEXT("Save: %s"), *InResult.Result.ToString());
}));
Slot calls read and write saves through the storage only. To show a few values of every save without loading it into a manager, read a static model from its entry (see Reading a static model from a slot).
Save into a slot
Save()runs. When it finished, the save game is turned into bytes at once, before the next process can change it.- The write waits for its turn on the slot (slot work of the storage).
- With meta, the meta entry is read first (
Pulse::Save::MetaEntryId,slot_meta). No meta, or a damaged one, is written anew; the meta save game of a Pulse meta is the base (its other records stay); a meta your game writes itself stays untouched and only the entry is written; a read that fails for now (offline, timed out) ends the save with that reason and writes nothing. - One package goes to the storage: the entry, the meta (when there is one) and the extra entries, as a new version. The current version of each entry becomes its previous version while the storage keeps one. Every entry lands, or none does.
The save status of Pulse Foundation reports the save as finished after the write, not when the process ends. The report of the save is held back until the write answered, so it holds the wait for the storage (see Reports).
Check first, then load
LoadFromSlot checks the whole save game before anything is applied (bCheckBeforeLoad, on by default): Pulse::Save::CheckSaveGame (Data/PulseSaveCheck.h) reads every record, collected and static, once into a model of its class that is thrown away. Nothing in the world changes while it checks.
- The entry and the meta are read together, in the slot work. A missing entry fails with
Pulse.Result.Failure.Save.Storage.NotFound; a read that fails for now (offline, timed out) fails with its reason. Nothing is applied in both cases. - A current version that cannot be read, cannot be turned into a save game or has a record with an error (its data cannot be read) is damaged. The manager then loads the previous version, while the storage keeps one (
FPulseSaveStorageCapabilities::bKeepsPreviousVersion; Files:bEnableSlotBackups). A sound previous version is loaded and written back as the current one (package modeRepair, with its meta when that meta belongs to it; a failed write back only logs a warning).GetLastSaveCheck()then hasbUsedBackupand the problems of the current version inPrimaryProblems. - Without a sound version the load fails before the world is touched:
DonegetsPulse.Result.Failure.Save.Damaged, no save game is set, andGetLastSaveCheck()lists the problems, so the game can stay in its menu. Load Game of the save game (and the load menu) answers the same reason. - A record whose model class does not exist any more, or is abstract now, is a warning: it loads only through a migration or a class redirect (see Save migration).
- The meta of the loaded save is chosen by
Pulse::Save::ChooseLoadedMeta: a meta written with exactly the loaded bytes wins (by its entry stamp, current before previous), else the meta of the loaded version unless it belongs to other bytes. A meta your game writes itself counts as none. GetLastSlotLoaded()(FPulseSaveSlotLoaded, the same asLoadedof the result) tells what was loaded:Owner,SlotName,EntryId,bLoaded,Version(CurrentorPrevious),bRestoredPrevious, theStampof the loaded bytes,bHasMetaandMeta. It is cleared when a save,SetSaveGameor another load starts.GetLastSaveCheck()always describes the last load: other loads (Load,SetSaveGame) clear it.CancelProcesswhile the slot load reads ends it with a cancel; nothing is applied.
Save with the slot meta
Save and load menus show the meta of a slot (name, date, play time, picture; see Save and load menus). SaveToSlotWithMeta writes the entry and the meta in one package, so the slot never shows the data of one save with the meta of another, and the previous versions of both belong to the same save. Save Game of the save game and the auto saves of the session write with it. The meta gets the entry stamp of the written save (FPulseSaveSlotMeta::Entry): loads find the meta of the data they loaded by it.
With MakeMeta (C++, FPulseSaveMakeSlotMeta) the meta is built from the meta the slot has now (null for none) when the save is written, a moment after the save was asked, so it must not read the world. Returning false writes the entry alone. bMetaWritten and Meta of the result tell what was written; bMetaWritten is false when only the entry was written (no meta, or a meta your game writes itself).
To write the meta alone (a new name), read it, or list the slots with their meta, see Save and load menus.