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() and CanMakeNewSlot() (against MaxSlots) 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() answers SlotMissing only while the list is ready; before, LoadGame finds 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.
  • NoSlot before the first save into a slot (a New Game that was not saved yet), NoGame or HostOnly without the world of the host. The save game answers these on the next frame.
  • Locked while a lock holds auto saves back, Busy while 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:

  • SavePlayer saves 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.
  • ApplyPlayer gives 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) answers Pulse.Result.Failure.Save.Ironman; CanSave() and CanSaveToSlot() say so before. The first auto save of the game makes its slot: AutoSave of 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 AutoSave the 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 first AutoSave; until then the triggers of the session have nothing to save.
  • No load while the game runs. After a save or a load, LoadGame and CanLoad() answer Ironman. After EndGame (the main menu) and after NewGame the 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 OnProfileLoaded fires 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 calls NoteSlotChanged() 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 with SaveSingleObject, in memory, under the identifiers of the objects (Player.<player id>.* for player actors, see Pulse::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.
  • SavePlayer and ApplyPlayer of the save game do the same by hand (see Players). bKeepPlayerData in 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 AutoSaveTriggers and 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) and bOnQuit (the application quits: the worlds tear down before the game instance shuts down). The saves of bOnHostQuit and bOnQuit run 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 OnAutoSaveNative with bStarted = false and answers Locked. 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 is Pulse::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 until SlotProvider names 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 through Done on the next tick: Locked, NoSlot without a session or a slot, Busy while the manager saves or loads or an auto save started in this frame. A started save answers with the result of the write, after OnAutoSaveFinishedNative.
  • SavePlayer(Player, Done) and ApplyPlayer(Player, Done) return the objects whose save or load started. Done answers like the functions of the save game (see Players).
  • LockAutoSave(Reason), UnlockAutoSave(Handle) and IsAutoSaveLocked() 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 no Done.
  • SlotProvider names 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:

  1. Idle
  2. Saving
  3. Loading

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))

  1. Validates the manager is idle and a save game is set (CanStartProcess lets a manager subclass refuse).
  2. 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).
  3. Collects save objects from all registered collectors (GetSaveModels).
  4. Resolves or creates a UPulseSaveModel per object identifier (GetOrCreateModelForObject).
  5. Processes models per chunk (OnPreSave -> IsReadyToSave (polled) -> OnPostSave), in two phases (below).
  6. Writes each model into a Collected FPulseSaveModelRecord (persistent or not, see Core concepts).
  7. Completes the process, updating GetLastProcessReport() and broadcasting OnProcessed() / OnProcessedEvent and OnProcessedWithReport() / 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))

  1. 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.
  2. Loads models from the Collected records of the currently set save game.
  3. Collects load objects from all registered collectors and maps them to loaded models by identifier. Objects with no matching record trigger IPulseSaveInterface::OnLoadFailed with EPulseSaveLoadFailureType::ObjectNotFound.
  4. 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.
  5. Processes models per chunk (OnPreLoad -> IsReadyToLoad (polled) -> OnPostLoad).
  6. 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 (see BuildChunks) finishes processing, with ChunkIndex (1-based, chunks completed so far) and ChunkCount (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’s Identifier, whether it succeeded, and whether it specifically timed out. Fires more often than OnChunkProcessed, 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:

  1. 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.
  2. AddCollector / AddCollectorByClass / RemoveCollector / GetCollectors(): manage collectors.
  3. 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 every Save() and refreshed on every Load() (see Models and collectors).
  4. CancelProcess() (C++): cancels the currently running Save()/Load(). Every running model processor is stopped (they are recorded as failed in GetLastProcessReport()), any pending chunks are discarded, and the manager returns to Idle. OnProcessed() / OnProcessedWithReport() still fire with bSuccess = 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

  1. Save() runs. When it finished, the save game is turned into bytes at once, before the next process can change it.
  2. The write waits for its turn on the slot (slot work of the storage).
  3. 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.
  4. 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 mode Repair, with its meta when that meta belongs to it; a failed write back only logs a warning). GetLastSaveCheck() then has bUsedBackup and the problems of the current version in PrimaryProblems.
  • Without a sound version the load fails before the world is touched: Done gets Pulse.Result.Failure.Save.Damaged, no save game is set, and GetLastSaveCheck() 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 as Loaded of the result) tells what was loaded: Owner, SlotName, EntryId, bLoaded, Version (Current or Previous), bRestoredPrevious, the Stamp of the loaded bytes, bHasMeta and Meta. It is cleared when a save, SetSaveGame or another load starts.
  • GetLastSaveCheck() always describes the last load: other loads (Load, SetSaveGame) clear it.
  • CancelProcess while 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.


This site uses Just the Docs, a documentation theme for Jekyll.