Blueprint and C++ API reference
For most plugin APIs, Blueprint node names match the C++ function names (Blueprint uses spaced, title-cased names; C++ uses PascalCase).
UPulseSaveManager
The engine of the save game and of the profiles, and the type saveable objects get (see The save manager). The save game makes its manager from ManagerClass of the settings, each profile a UPulseSaveManager; plugins and specs reach the manager of the game with UPulseSaveGameSubsystem::GetManager() or FindManager(). A game saves and loads through the save game, not through a manager. In Blueprint a manager offers what saveable objects call from the save interface, the collectors, the reports, the states and the events; rows without a Blueprint node are C++ only.
Save game / collectors
| Blueprint node | C++ function |
|---|---|
| — | void SetSaveGame(const FPulseSaveGame& InSaveGame, EPulseSaveModelRetentionPolicy ModelRetentionPolicy = Reset) |
| — | void ClearSaveGame(EPulseSaveModelRetentionPolicy ModelRetentionPolicy = Reset) |
| Get Save Game | FPulseStrongSaveGame GetSaveGame() const |
| Add Collector | bool AddCollector(UPulseSaveCollectorBase* Collector) |
| Add Collector By Class | UPulseSaveCollectorBase* AddCollectorByClass(TSubclassOf<UPulseSaveCollectorBase> CollectorClass) |
| Remove Collector | bool RemoveCollector(UPulseSaveCollectorBase* Collector) |
| Get Collectors | TArray<UPulseSaveCollectorBase*> GetCollectors() const |
| — | template<typename T> T* AddCollectorByClass() (C++) |
Process control
| Blueprint node | C++ function |
|---|---|
| — | bool Save(): StartProcess(EPulseSaveManagerProcessType::Save) |
| — | bool Load(): StartProcess(EPulseSaveManagerProcessType::Load) |
| — | bool StartProcess(EPulseSaveManagerProcessType ProcessType) |
| — | bool SaveSingleObject(UObject* Object) |
| — | bool LoadSingleObject(UObject* Object) |
| Reset Cached Save Models | void ResetCachedSaveModels() |
| — | EPulseSaveManagerStateType GetCurrentState() const (C++) |
| Is Idle | bool IsIdle() const |
| Is Saving | bool IsSaving() const |
| Is Loading | bool IsLoading() const |
| Can Save | bool CanSave() const |
| Can Load | bool CanLoad() const |
| — | const FPulseSaveProcessReport& GetLastProcessReport() const (C++) |
| Get Last Save Report / Get Last Load Report | const FPulseSaveProcessReport& GetLastSaveReport() const / GetLastLoadReport() (sizes and times per model in Models) |
| Get Last Save Check | const FPulseSaveCheckResult& GetLastSaveCheck() const (see Save check) |
| — | void CancelProcess() |
| Remove Record | bool RemoveRecord(FName Identifier): removes the record of an object from the save game of the manager |
| Mark Destroyed | void MarkDestroyed(UObject* Object, bool bPlaced): an object that is no actor was destroyed for good: the next save makes the record of a placed one a tombstone and removes the record of a spawned one |
| Set Report Slot | void SetReportSlot(const FString& SlotName, const FString& EntryId = ""): the slot written into the reports. Set automatically by the slot functions below. |
| Get Report Slot Name | FString GetReportSlotName() const |
| Set Report Context | void SetReportContext(const FString& Context): free text written into the reports to tell managers apart, e.g. "Player profile". Kept when the save game is replaced. |
| Get Report Context | FString GetReportContext() const |
| Flush Reports | void FlushReports(): writes the collected single-object and static-model reports now (see Reports) |
Completion of one call
C++ overloads with a native one-shot delegate:
| C++ function |
|---|
bool Save(const FPulseSaveManagerProcessedDelegate& OnComplete) |
bool Load(const FPulseSaveManagerProcessedDelegate& OnComplete) |
bool StartProcess(EPulseSaveManagerProcessType ProcessType, const FPulseSaveManagerProcessedDelegate& OnComplete) |
bool SaveSingleObject(UObject* Object, const FPulseSaveManagerProcessedSingleDelegate& OnComplete) |
bool LoadSingleObject(UObject* Object, const FPulseSaveManagerProcessedSingleDelegate& OnComplete) |
Each OnComplete fires exactly once, for that call only, then is discarded, unlike OnProcessed()/OnProcessedEvent/OnProcessedSingle()/OnProcessedSingleEvent, which stay bound across every future call. See Save manager workflow.
Slots of a storage
Combine Save()/Load() with a slot of a storage in one call; see Slots of a storage and Storage. Every call answers once through Done, on a later tick, never inside the call. false means it was refused at once; Done still comes. The slot calls are C++; a game saves and loads with the save game.
| Blueprint node | C++ function |
|---|---|
| — | bool SaveToSlot(const FPulseSaveSlotRef& InSlot, const FPulseSaveSlotEntryId& InEntryId, FPulseSaveSlotDoneNative InDone, TArray<FPulseSaveStorageEntryBytes> InExtraEntries = {}) |
| — | bool SaveToSlotWithMeta(const FPulseSaveSlotRef& InSlot, const FPulseSaveSlotEntryId& InEntryId, FPulseSaveMakeSlotMeta InMakeMeta, FPulseSaveSlotDoneNative InDone, TArray<FPulseSaveStorageEntryBytes> InExtraEntries = {}) |
| — | bool SaveToSlotWithMeta(const FPulseSaveSlotRef& InSlot, const FPulseSaveSlotEntryId& InEntryId, const FPulseSaveSlotMeta& InMeta, FPulseSaveSlotDoneNative InDone, TArray<FPulseSaveStorageEntryBytes> InExtraEntries = {}) |
| — | bool LoadFromSlot(const FPulseSaveSlotRef& InSlot, const FPulseSaveSlotEntryId& InEntryId, FPulseSaveSlotDoneNative InDone, EPulseSaveModelRetentionPolicy InModelRetentionPolicy = Reset) |
| Is Free | bool IsFree() const: idle and no slot load reads, so a save or load may start |
| Has Slot Work | bool HasSlotWork() const: a slot call of this manager is queued or runs |
| Get Last Slot Loaded | const FPulseSaveSlotLoaded& GetLastSlotLoaded() const: what the last LoadFromSlot loaded |
Types (Slots/PulseSaveSlotResult.h):
| Type | Fields |
|---|---|
FPulseSaveSlotResult | Result (FPulseResult), Loaded, bMetaWritten, Meta, StorageWaitMs (wall time from the first request to the storage to its last answer, also when the call failed) |
FPulseSaveSlotLoaded | Owner, SlotName, EntryId, bLoaded, Version (EPulseSaveEntryVersion), bRestoredPrevious, Stamp, bHasMeta, Meta; cleared when a save, SetSaveGame or another load starts |
FPulseSaveSlotDoneNative | (UPulseSaveManager* Manager, const FPulseSaveSlotResult& Result) |
FPulseSaveMakeSlotMeta | bool(const FPulseSaveSlotMeta* InCurrent, FPulseSaveSlotMeta& OutMeta): builds the meta from the current one when the save is written; false writes the entry alone |
Static models
| Blueprint node | C++ function |
|---|---|
| Get Or Create Static Model | UPulseStaticSaveModelBase* GetOrCreateStaticModel(FName Identifier, TSubclassOf<UPulseStaticSaveModelBase> ModelClass) (also template<T> T* GetOrCreateStaticModel(FName Identifier)) |
| Save Static Model | bool SaveStaticModel(UPulseStaticSaveModelBase* Model) |
| Read Static Model (Async) | void Pulse::Save::ReadStaticModel(const FPulseSaveSlotRef& InSlot, const FPulseSaveSlotEntryId& InEntryId, FName InIdentifier, TSubclassOf<UPulseStaticSaveModelBase> InModelClass, FPulseSaveStaticModelDone InDone) (PulseSaveUtils.h, no manager): one static model from the save game in an entry of a storage slot, see Reading a static model from a slot |
Delegates/events
| Native (C++) | Blueprint-assignable | Fired when |
|---|---|---|
OnProcessed() → FOnCompleteEvent(UPulseSaveManager*, bool bWasSuccessful) | OnProcessedEvent | Save()/Load() completes. |
OnProcessedSingle() → FPulseSaveManagerProcessedSingleSignature(UPulseSaveManager*, UObject*, bool) | OnProcessedSingleEvent | SaveSingleObject()/LoadSingleObject() completes. |
OnProcessedWithReport() → FPulseSaveManagerProcessedReportSignature(UPulseSaveManager*, const FPulseSaveProcessReport&, bool) | OnProcessedWithReportEvent | Save()/Load() completes, carries diagnostics (see Save manager workflow). |
OnChunkProcessed() → FPulseSaveManagerChunkProcessedSignature(UPulseSaveManager*, int32 ChunkIndex, int32 ChunkCount) | OnChunkProcessedEvent | A chunk finishes processing during Save()/Load() (see Save manager workflow). |
OnModelProcessed() → FPulseSaveManagerModelProcessedSignature(UPulseSaveManager*, FName Identifier, bool bWasSuccessful, bool bTimedOut) | OnModelProcessedEvent | An individual model finishes processing during Save()/Load(). |
FPulseSaveProcessReport / FPulseSaveProcessReportEntry
See the field table in Save manager workflow. Slot calls fill the wait for the storage: StorageWaitMs (wall time from the first request to the last answer; requests that run at the same time count once), SlotQueueMs, SlotTotalMs, StorageRequestCount and StorageWaits. DurationSeconds and GameThreadMs cover only the process.
FPulseSaveStorageWait (Manager/PulseSaveManagerTypes.h) is one request of a slot call to its storage: Operation (ReadEntry or WriteEntries), Entry (the entry read, or the entries of the package written), Version, QueueMs (the wait of the slot work that asked it for its slot), WaitMs (from the request to its answer, the byte layers included), Bytes, bSucceeded, Reason, StartMs (when it was asked, from the slot call on).
Enums
EPulseSaveManagerProcessType:Save,LoadEPulseSaveManagerStateType:Idle,Saving,LoadingEPulseSaveModelRetentionPolicy:Reset(default),RemoveMissing,KeepAll: what happens to cached and static models when the save game of the manager changes
Save check (Data/PulseSaveCheck.h)
| API | Purpose |
|---|---|
Pulse::Save::CheckSaveGame(SaveGame, Manager) | Reads every record into a throw-away model; returns FPulseSaveCheckResult |
FPulseSaveCheckResult | RecordCount, Problems (FPulseSaveCheckProblem: identifier, record type, model class, EPulseSaveCheckSeverity Warning/Error, message), bUsedBackup (the previous version was loaded), PrimaryProblems (the problems of the current version then), IsLoadable(), GetErrorCount(), ToString() |
UPulseSaveManager::GetLastSaveCheck() | The check of the last LoadFromSlot |
UPulseSaveManager::GetLastSlotLoaded() | What the last LoadFromSlot loaded: version, whether it was written back, stamp and meta (see Slots of a storage) |
UPulseSaveCheckLibrary | Blueprint: Is Save Loadable, Get Save Check Error Count |
UPulseSaveGameSubsystem
Game instance subsystem of the save game of the game (Game/PulseSaveGameSubsystem.h), see Save manager workflow. It is the one API of a game for saving and loading. A request that reads or writes a storage or waits for objects answers once with an FPulseResult (FPulseSaveGameDone in C++, an async node in Blueprint), never inside the call; a request that only changes memory or reads a state answers at once.
| Function | Purpose |
|---|---|
Get(WorldContext) | The save game of the game instance of any object (static) |
GetManager() | The save manager of the game, made from the block Game of the save settings on first use (C++, for plugins and specs) |
GetCurrentSlot() | The slot the game was last saved into or loaded from; empty for a new game that was not saved yet |
GetOwner() / GetStorage() | Whose slots the save game keeps (the server on a dedicated server, else the first local user); its storage (Pulse.Save.Storage.Game) |
MakeSlot(SlotName) / MakeNewSlotName() | The slot in the storage of the save game, for its owner (FPulseSaveSlotRef); a free name (Save_0003) that no listed slot and no running save has, a name with the time while the list is not ready (_2, _3, … while taken); with a mirror that has a secondary storage 4 hex digits at the end, drawn once per game instance (Save_0003_a1b2; the same list gives the same name) |
RefreshSlots(Done) / Refresh Slots | Lists the slots again with their meta; Done (optional, C++) gets the slots |
IsSlotListReady() | True once the slots were listed; GetSlots() is empty before |
GetSlots() | The slots of the save game with their meta (FPulseSaveSlotListEntry), newest first: the slots of its owner that start with SlotPrefix, never the slots of player profiles |
CountSlots() / CanMakeNewSlot() | How many slots the list has; whether one more fits MaxSlots |
OnSlotsChanged / OnSlotsChangedNative | The list changed: listed again, a save, a delete; it 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) |
CanSave() / CanLoad() | Success, or why not (no game, a client, a save or load running; Ironman: no save the game asks for, no load while the game runs) |
IsIronman() | Whether the game is an Ironman game: the field Save.Ironman of the meta of its slot; before the first save the switch Pulse.Tuning.Save.Ironman in its world |
CanSaveToSlot(SlotName) / CanLoadFromSlot(SlotName) | What SaveGame and LoadGame answer before they start, at once: also NoSlot without a name, an invalid name, and SlotMissing while the list is ready and has no such slot |
NewGame() | An empty save game without a slot, the play time from 0; starts the session (also in an Ironman game, which runs only after its first save or a load) |
SaveGame(SlotName, DisplayName, Done) | Saves the entry with its meta and makes the slot the slot of the session; Done (FPulseSaveGameDone) gets the result |
LoadGame(SlotName, Done) | Loads the entry (check before the load, 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) | Deletes the slot with its previous versions and meta; Done gets the result once the storage answered (SlotMissing, Busy for the slot of a running save or load, a reason of the storage); the session forgets the slot when it was its slot |
AutoSave(Reason, Done) | void AutoSave(FName InReason, FPulseSaveGameDone InDone = {}) (C++): saves into the slot of the session now (UPulseSaveSessionSubsystem::AutoSave), also of a session a plugin set with a manager of its own. Done answers once, never inside the call: success when the slot was written; NoSlot before the first save into a slot, NoGame or HostOnly from the save game on the next frame; Locked (the session reports it through OnAutoSaveNative) or Busy from the session on its next tick; else a reason of the save or the storage. The first auto save of an Ironman game makes its slot through the session (a new name, a meta with the Ironman field, no picture) |
LockAutoSave(Reason) / UnlockAutoSave(Handle) / IsAutoSaveLocked() | Hold auto saves back until the lock is released (FPulseHandle); whether a lock holds. The locks belong to the session of a slot: the session of another slot (New Game, Save Game or Load Game) and End Game start without them |
SavePlayer(Player, Done) / ApplyPlayer(Player, Done) | C++: save the saveable actors and components of a player into the save game of the session in memory; give a player the data the save game holds for them. Done answers once when every object answered: success (also with nothing to save or nothing of the player), the first failure, NoGame without a session or save game |
SaveObject(Object, Done) / LoadObject(Object, Done) | C++: save one object into the save game in memory, or load it from there (a single object process of the manager of the game). Done answers once: success, NoGame without a save game, Failed (not saveable, no record for a load, its model failed or timed out) |
GetOrCreateStaticModel(Identifier, ModelClass) | A static model of the save game in memory (the output is typed by the class), read from its record or made new; null without a save game. Never makes the manager |
SaveStaticModel(Model) | Writes a static model into the save game in memory now and keeps it written by every later save; false without a save game |
RemoveRecord(Identifier) | Removes the record of an object from the save game in memory; the next save into a slot drops it. True if there was a record |
GetLastSaveReport() / GetLastLoadReport() | The reports of the last save and load of the game (FPulseSaveProcessReport, by value; empty before the first one) |
IsBusy() | True while a save or load of the game runs, the write or read of its slot included |
EndGame() | For the main menu: no current slot, the session of the game ends, no game runs (an Ironman slot loads again); the save game in memory stays until New Game or Load Game |
FindManager() | The save manager of the game, null before its first use (C++, for plugins and specs, never makes one) |
Blueprint nodes of UPulseSaveGameAsyncAction, pin On Done with the result: Save Game (Async), Load Game (Async), Delete Slot (Async), Auto Save (Async), Save Player (Async), Apply Player (Async), Save Object (Async) and Load Object (Async). The other functions are in the category Pulse > Save > Game. NewGame, EndGame, the locks, the static models, RemoveRecord, the reports and IsBusy answer at once.
Reasons (namespace Pulse::Save::Game; texts in Project Settings > Pulse > Foundation > Result Texts):
| Reason | Native tag | When |
|---|---|---|
Pulse.Result.Failure.Save.NoGame | TAG_FailureNoGame | No world of a game to save or load |
Pulse.Result.Failure.Save.HostOnly | TAG_FailureHostOnly | Asked on a client: only the host saves and loads |
Pulse.Result.Failure.Save.Busy | TAG_FailureBusy | A save or load of the game is running, or an auto save started in this frame |
Pulse.Result.Failure.Save.NoSlot | TAG_FailureNoSlot | An auto save before the first save into a slot or without a session, or a save without a slot name |
Pulse.Result.Failure.Save.SlotMissing | TAG_FailureSlotMissing | The slot does not exist (load, delete) |
Pulse.Result.Failure.Save.Damaged | TAG_FailureDamaged | The save and its previous version were not usable; nothing was loaded |
Pulse.Result.Failure.Save.Failed | TAG_FailureFailed | Saving, loading or deleting failed otherwise (also the first failure of the objects of a player, and a single object that failed) |
Pulse.Result.Failure.Save.Locked | TAG_FailureLocked | A lock of the session holds auto saves back |
Pulse.Result.Failure.Save.Ironman | TAG_FailureIronman | An Ironman game: a save the game asks for, or a load while the game runs |
Pulse.Result.Failure.Save.ForeignMeta | TAG_FailureForeignMeta | Write Slot Meta: the meta entry of the slot holds data of the game itself; PulseSave does not write over it |
A storage fails with the reasons of Save storage (Pulse.Result.Failure.Save.Storage.*), and the save game passes them on.
Messages (payload FPulseSaveSlotMessage: SlotName, AutoSaveReason):
| Channel | Native tag | When |
|---|---|---|
Pulse.Message.Save.SlotWritten | TAG_MessageSlotWritten | Save Game wrote a slot, or an auto save of the session wrote its slot (AutoSaveReason: its reason) |
Pulse.Message.Save.SlotLoaded | TAG_MessageSlotLoaded | Load Game loaded a slot |
Pulse.Message.Save.SlotDeleted | TAG_MessageSlotDeleted | Delete Slot deleted a slot on this machine |
OnSlotWrittenNative (C++) is called with the slot at the same moment as the message, also without a message subsystem.
Tuning knob (switch, registered by PulseSave): Pulse.Tuning.Save.Ironman (TAG_TuningIronman), see Ironman.
Pure rules (namespace Pulse::Save::Game): IsGameSlotName(SlotName, SlotPrefix, ProfileSlotPrefix) (which slots the slot list has), IsSlotOfGame(SlotName, CurrentSlot, SessionSlot, ReservedNames, LoadingSlot) (the slots of the running game a mirror leaves alone); for Ironman the pure rule CheckIronman(Request, bIronman, bGameRunning) and IsIronmanMeta(Meta) (field IronmanField, Save.Ironman, of the slot meta).
UPulseSaveProfileSubsystem / UPulseSaveProfile
The profile of each local player (Game/PulseSaveProfile.h), see Save manager workflow.
| Function | Purpose |
|---|---|
UPulseSaveProfileSubsystem::Get(Player) | The profiles of a local player, or of any actor of one (static); null for players of other machines |
GetSaveProfile(Player) | Get Save Profile: the profile of a local player, read from its slot on first use (static, Blueprint) |
GetProfile() / IsProfileLoaded() | The profile object (with a storage on this machine it has its data when the call returns, else a moment later); whether its slot was read (or found missing) |
WhenProfileLoaded(Then) | Runs a function once the profile has its data: at once when it has, else when the slot was read (C++; Blueprint Wait For Profile (Async)) |
IsPersistable() | False after a read that failed for now (offline, timed out): SaveProfile does not write over the slot until LoadProfile worked |
SetStorage(Storage) | Keeps this profile in a storage of its own instead of the storage of profiles; null goes back (C++) |
GetSlotName() / GetSlotOwner() | The slot among the slots of the platform user of the player (Profile; Profile_1 for a player that shares its user with a player before it; in the editor Profile_PIE1; once read, the slot it was read from); whose slot it is (the platform user of the player, the first user of the machine for a player without one; once read, the owner it was read from) |
RegisterObject(Object) / UnregisterObject(Object) | Add an object of the game (save interface or bytes); it gets its data at once when the profile has some |
SaveProfile(Done) / LoadProfile(Done) | Write the slot (reads it first when that did not happen yet); read it again. Done gets the result |
ResetProfile(Done) | The same profile object goes back to the defaults of its class at once and the slot is deleted; Done gets the result once the storage answered (success also without a slot) |
MarkProfileChanged() / IsProfileChanged() | Note a change the profile cannot see itself: of a registered object whose saved data is not in its SaveGame variables (a model of its own, variables filled in OnSave) or whose bytes come later (the setters, the SaveGame variables of the profile class and of registered objects with the save interface, and the bytes of registered objects that save at once count by themselves); whether the profile changed since it was last saved or read. Only a changed profile is saved when its player goes |
IsProfileInUse() | True while the slot must stay as it is: the profile changed, or a read or a save runs; a mirror leaves the slot alone meanwhile (C++) |
NoteSlotChanged() | The slot changed in its storage without a request of the profile: a read profile without changes reads it again on the next tick, a running read reads again afterwards, a changed profile keeps its changes. The storage subsystem calls it for the storage of profiles; call it for a storage of your own (C++) |
OnProfileLoadedNative / OnProfileLoaded | The profile has its data (read, started new or reset, read again after a mirror brought a newer version) |
GetManager() | The save manager of the profile (C++) |
Blueprint nodes Save Profile (Async), Load Profile (Async), Reset Profile (Async) and Wait For Profile (Async) (UPulseSaveProfileAsyncAction, pin On Done). A request for a player of another machine fails with Pulse.Result.Failure.Save.NoProfile (Pulse::Save::Profile::TAG_FailureNoProfile); the others use the reasons of the save game (Busy, Damaged, Failed).
UPulseSaveProfile (Blueprintable; its SaveGame variables are saved by the default object model):
| Function | Purpose |
|---|---|
SetBool / GetBool(Key, Default) | A true or false under a gameplay tag |
SetInt / AddInt(Key, Amount) / GetInt(Key, Default) | A whole number; AddInt counts (returns the new value) |
SetFloat / GetFloat(Key, Default) | A number |
SetString / GetString(Key, Default) | A text |
SetTags / GetTags(Key) | Tags (unlocked skins, seen hints) |
SetStruct / GetStruct(Key) | Any struct as FInstancedStruct (Blueprint: Make Instanced Struct, Get Instanced Struct Value); C++ SetValue<T> / GetValue<T> |
HasValue / RemoveValue / GetValueKeys | Look at and remove free values |
OnValueChangedNative / OnValueChanged | A free value was set or removed (key) |
ResetToDefaults() | Every SaveGame property back to the class defaults (C++) |
GetLocalPlayer() | The local player of the profile |
The values are stored in wrapper structs (FPulseSaveProfileBool, FPulseSaveProfileInt, FPulseSaveProfileFloat, FPulseSaveProfileString, FPulseSaveProfileTags); a getter of another type returns its default. Pulse::Save::MakeProfileSlotName(Prefix, PlayerIndex, PIEInstance) is the pure rule of the slot name, Pulse::Save::GetProfilePlayerIndex(Users, PlayerIndex, PrimaryUser) tells whether a player keeps its profile beside the profile of its user (a player before it has the same user; a player without a user counts as the first user of the machine) and Pulse::Save::IsProfileSlotName(SlotName, Prefix) is the inverse (Profile, Profile_1, Profile_PIE1, Profile_1_PIE1, without case).
UPulseSaveSessionSubsystem
Game instance subsystem of the running save (Game/PulseSaveSession.h), the engine of the save game for the data of players and for auto saves, see Save manager workflow. Its functions are C++ only, for plugins and specs; only GetSessionSlot() and GetSessionSlotRef() are also Blueprint functions. A game uses the functions of the save game.
| Function | Purpose |
|---|---|
Get(WorldContext) | The session of the game instance of any object (static) |
SetSessionManager(Manager, Slot, EntryId) / ClearSession() / GetSessionManager() | Set, end and read the running save (Slot: FPulseSaveSlotRef, an empty slot name for no auto saves yet; a new session starts without locks) |
GetSessionSlot() / GetSessionSlotRef() | The slot auto saves of the session write, empty without one; with its storage and owner (Blueprint pure) |
GetLastWrittenMeta(OutMeta) | The meta the last auto save wrote with its entry; false without one |
SavePlayer(Player, Done) / ApplyPlayer(Player, Done) | int32 SavePlayer(const AActor* InPlayer, FPulseSaveGameDone InDone = {}), ApplyPlayer the same: save a player into the save game of the session, give a player their data back; return the objects whose save or load started. Done answers once when every object answered, never inside the call: success (also with nothing to save or nothing of the player), the first failure, NoGame without a session or save game |
LockAutoSave(Reason) / UnlockAutoSave(Handle) / IsAutoSaveLocked() | Hold auto saves back |
AutoSave(Reason, Done) | void AutoSave(FName InReason, FPulseSaveGameDone InDone = {}): save the session into its slot now, with the meta of now when the slot has a meta. 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 |
OnAutoSaveNative | (FName Reason, bool bStarted) for every auto save that ran or was held back |
OnAutoSaveFinishedNative | (FName Reason, const FPulseResult& Result) when an auto save that started was written or failed, before its Done |
SlotProvider | FPulseSaveSessionSlotProvider (C++): names the first slot when an auto save of a session with a manager finds none, with the meta it is first written with; the save game binds it for the one slot of an Ironman game |
GatherPlayerObjects(Player, OutObjects) | The saveable actors and components of a player (static) |
Rules (Game/PulseSaveSessionState.h, namespace Pulse::Save, pure): FPulseSaveSessionState (SlotName, EntryId, Storage, Owner, Locks, LastAutoSaveFrame, GetSlot()), MakeSessionState(State, bSameManager, Slot, EntryId), ClearSessionState(State), DecideAutoSave(State, bHasManager, bManagerIdle, Frame) (EPulseAutoSaveDecision), GetAutoSaveReason(Event, Triggers) (FPulseAutoSaveEvent, EPulseAutoSaveTrigger), DescribeLocks(State), MakeAutoSaveMeta(Last, Now) (the meta an auto save writes). FPulseAutoSaveTriggers lives there too.
UPulseSaveUtils
| Blueprint node | C++ function |
|---|---|
| Save Object To Byte Array | static bool SaveObjectToByteArray(UObject* InObject, TArray<uint8>& OutData, bool bSaveGameOnly = true, bool bCallInterface = true) |
| Load Object From Byte Array | static bool LoadObjectFromByteArray(const TArray<uint8>& InData, UObject* InObject, FLoadObjectVersionInfo& OutVersion, bool bSaveGameOnly = true, bool bCallInterface = true) |
| Is Valid Save Game | static bool IsValidSaveGame(const FPulseWeakSaveGame& InSaveGame) |
| Is Valid Strong Save Game | static bool IsValidStrongSaveGame(const FPulseStrongSaveGame& InSaveGame) |
| Pin (Save Game) | static FPulseSaveGame PinSaveGame(const FPulseWeakSaveGame& InSaveGame) |
| Strong (Pin Strong Save Game) | static FPulseStrongSaveGame PinStrongSaveGame(const FPulseWeakSaveGame& InSaveGame) |
| Pin (Save Game From Strong) | static FPulseSaveGame PinSaveGameFromStrong(const FPulseStrongSaveGame& InSaveGame) |
| Weak (Make Weak Save Game) | static FPulseWeakSaveGame MakeWeakSaveGame(const FPulseSaveGame& InSaveGame) |
| Weak (Make Weak Save Game From Strong) | static FPulseWeakSaveGame MakeWeakSaveGameFromStrong(const FPulseStrongSaveGame& InSaveGame) |
| Create Save Model | static UPulseSaveModelBase* CreateSaveModel(UObject* Outer, TSubclassOf<UPulseSaveModelBase> SaveModelClass) |
| Save Game To Byte Array | static bool SaveGameToByteArray(const FPulseSaveGame& InSaveGame, TArray<uint8>& OutData) |
| Load Game From Byte Array | static FPulseStrongSaveGame LoadGameFromByteArray(const TArray<uint8>& InData) |
Save storage
Where PulseSave keeps bytes (Storage/PulseSaveStorage.h, Storage/PulseSaveStorageTypes.h), see Storage.
| Type / function | Purpose |
|---|---|
UPulseSaveStorage | Abstract, Blueprintable provider (UPulseProvider of Pulse Foundation). Operations to override: ListSlots, ListEntries, ReadEntry, WriteEntries, DeleteSlot, DeleteEntry (BlueprintNativeEvents with a request id), answered with FinishListSlots, FinishListEntries, FinishRead, FinishWrite, FinishDelete; GetCapabilities() |
RequestListSlots, RequestListEntries, RequestRead, RequestWrite, RequestDeleteSlot, RequestDeleteEntry | C++ callers: check owner, names and package first, wait for their turn on the slot, answer once on the game thread, never inside the call |
EnqueueSlotWork(Owner, SlotName, Work) / FPulseSaveSlotWorkHandle | Work of several requests (read, decide, write) on one slot after everything asked before; requests with the handle run inside it; Finish() frees the slot (ended after three times the storage timeout) |
GetPendingCount() / FlushPendingWork(MaxSeconds) / EnterTeardown() | Requests and work not done yet; wait for them (teardown, tools); answer inside the answer from now on |
GetOwnerAccount(Owner) | The account that holds the slots of an owner now (a cloud: the signed-in user); empty: the slots belong to the owner. A mirror keeps a record per class of its secondary storage and account |
NotifySlotChanged(Owner, SlotName) / OnSlotChangedNative | A storage tells that slots changed without its own requests (empty name: several slots), e.g. a cloud after a login or a mirror after a round; lists of them are out of date |
SetByteLayers(Layers) / GetByteLayers() / GetCipher() | The byte layers of this storage instead of those of the settings; which layers apply; the cipher of the layers, made on first use (see Byte layers) |
UPulseSaveStorage_Files (Files) | The default: <Root>/<Purpose>/<Owner>/<Slot>/[<Category>/]<Identifier>.sav, .sav.prev for the previous version. RootDirectoryOverride, FolderOverride, bOverrideKeepPrevious / bKeepPreviousVersion; GetOwnerDirectory(Owner), GetSlotDirectory(Owner, SlotName) (diagnostics, never write into them) |
UPulseSaveStorage_Platform (Platform) | The save games of the platform (ISaveGameSystem, see Platform save games): <Prefix>_<Owner>_I0 and _I1 (the index, kept twice), <Prefix>_<Owner>_B<number> (a version of an entry). NamePrefix, Users (EPulseSavePlatformUsers: Automatic, InNames, BySystem), bKeepPreviousVersion, MaxPackageBytes; GetSaveNameBase(Owner) (diagnostics) |
UPulseSaveStorage_Memory (Memory) | Slots in memory only (see Memory only): SharedSpace (storages of the same name share their slots in the process), bKeepPreviousVersion, MaxTotalBytes; ClearAll(), GetTotalBytes(); C++ Put, Find, HasSlot, static ResetSharedSpaces() (specs) |
UPulseSaveStorage_Mirror (Mirror) | Two storages as one (see Mirror): PrimaryStorageClass, SecondaryStorageClass, SetStorages(Primary, Secondary), GetPrimaryStorage(), GetSecondaryStorage(), SetMirrorOptions(Options) / GetMirrorOptions(), Sync(Owner) / C++ RequestSync(Owner, Done), ResolveConflict(Owner, SlotName, Choice) / C++ RequestResolveConflict(Owner, SlotName, Choice, Done), GetConflicts(Owner), GetRefusedSlots(Owner), IsSyncing(Owner) (a round runs or is about to start, or a caller waits for one; not during the 30 s wait after a failed round or a slot left for later), OnConflict / OnConflictNative, OnSyncFinished / OnSyncFinishedNative; to override: IsSlotInUse, ShouldMirrorSlot, ChooseVersion (BlueprintNativeEvents) |
UPulseSaveStorage_Wrapper | Abstract base of a storage around another one (see Wrapper): hands every request to its inner storage; InnerStorageClass, SetInnerStorage(Inner), GetInnerStorage(), static Unwrap(Storage) (the first inner storage that is no wrapper); override the _Implementation operations it changes |
Pulse::Save::Testing (Testing/PulseSaveStorageConformance.h, automation builds) | DefineStorageConformance(Spec, GetStorage, Options) adds the checks every storage passes (see Check a storage); FStorageConformanceCalls (Write, Read, ListSlots, ListEntries, DeleteSlot, DeleteEntry, each waited for), FindConformanceOwner(Storage), MakeConformancePackage(Entries) |
UPulseSaveTestStorage | The Memory storage for specs: Answer (EPulseSaveTestAnswer: AtOnce, Manual, ManualAnswer, Never, Fail), FailReason, FailOnly, Capabilities, Calls, ReleaseManual, CountHeld, CorruptCurrent |
UPulseSaveStorageSubsystem | Game instance (Get(WorldContext)): GetStorage(Purpose), SetStorage(Purpose, Storage), SetStorageClass(Purpose, StorageClass), MakeSlotRef(Purpose, Owner, SlotName), FlushPendingWork(MaxSeconds), OnStorageChangedNative; mirrors: static AddMirrorStorage(Purpose, StorageClass), RemoveMirrorStorage, FindMirrorStorage(Purpose), FindMirror(Purpose) (also inside wrappers), C++ RequestSync(Purpose, Owner, Done); wrappers: static AddStorageWrapper(Purpose, WrapperClass), RemoveStorageWrapper, FindStorageWrapper(Purpose) (the outermost), GetUnwrappedStorageClass(Purpose), FindInnerStorageClass(Purpose, WrapperClass); slots in use: AddSlotInUseCheck(Check), RemoveSlotInUseCheck(Handle), IsSlotInUse(Purpose, Owner, SlotName); OnSlotChangedNative (slots of a purpose changed without a request of the game) |
UPulseSaveStorageSyncAsyncAction | Sync Save Storage (Async) (Purpose, Owner; no owner: the owner of the save game): waits for a round of the mirror of a purpose, pins Succeeded (also when there is nothing to compare: no mirror, or no secondary storage for the owner) and Failed |
| Type | Fields |
|---|---|
FPulseSaveOwner | Kind (EPulseSaveOwnerKind: None, LocalUser, Server, PlayerKey), UserId, PlayerKey; LocalUser(UserId), Server(), Player(Key), IsValid(), ToString(). Blueprint (UPulseSaveOwnerLibrary): Make Local User Owner, Make Primary User Owner, Make Server Owner, Make Player Key Owner, Owner To String |
FPulseSaveSlotRef | Storage, Owner, SlotName; IsValid(), ToString() |
FPulseSaveSlotEntryId | Category (optional), Identifier; IsValid(), ToString() / FromString() (Chunks/Forest) |
Pulse::Save::MetaEntryId | The reserved entry of the slot meta (slot_meta) |
FPulseSaveStoragePackage | Entries (FPulseSaveStorageEntryBytes: Entry, Bytes), Mode (EPulseSaveWriteMode: NewVersion, ReplaceCurrent, Repair), bReplaceSlot, PackageId and ModifiedAt (a copy keeps those of its source; empty: a new id, now) |
EPulseSaveEntryVersion | Current, Previous |
FPulseSaveStorageCapabilities | SupportedOwners (bits of EPulseSaveOwnerKindFlags), bKeepsPreviousVersion, bRemote, MaxPackageBytes |
FPulseSaveStorageSlotInfo | SlotName, ModifiedAt, SizeBytes, PackageId (the package of the newest current version); Blueprint read and write, so a Blueprint storage makes it for Finish List Slots |
FPulseSaveStorageEntryInfo | Entry, SizeBytes, ModifiedAt, PackageId, bHasPrevious; Blueprint read and write, so a Blueprint storage makes it for Finish List Entries and Finish Read |
FPulseSaveStorageFailureDetails | Diagnosis, NativeCode (the details of a storage failure) |
FPulseSaveByteLayers | Compression (EPulseSaveCompression: None, Fast, Normal, Small), bChecksum, Cipher (class of UPulseSaveCipher), bReadUnencrypted; IsActive() |
UPulseSaveCipher | Abstract, Blueprintable: Encrypt and Decrypt (BlueprintNativeEvents, game thread) or C++ MakeWork(Context) returning an IPulseSaveCipherWork (Encrypt, Decrypt, CanRunOnAnyThread) |
UPulseSaveCipher_AES (AES) | AES-256 in counter mode with HMAC-SHA1: Key, Get Key (BlueprintNativeEvent); Pulse::Save::Storage::MakeAESWork(Secret, Binding) without an object (specs, tools) |
FPulseSaveCipherContext | Purpose, Owner, SlotName, Entry; MakeBinding() (purpose, owner kind, the key of a player owner, entry) |
FPulseSaveMirrorOptions | ConflictRule (EPulseSaveMirrorConflictRule: Newer, Primary, Secondary, Ask), SyncIntervalSeconds (300; 0: never by time) |
FPulseSaveMirrorConflict | Owner, SlotName, Primary, Secondary (FPulseSaveStorageSlotInfo of both versions) |
FPulseSaveMirrorRefusal | Owner, SlotName, From (EPulseSaveMirrorSide: Primary, Secondary), Version, Result |
EPulseSaveMirrorChoice | Primary, Secondary, Later (Choose Version, Resolve Conflict) |
Purposes and reasons (namespace Pulse::Save::Storage):
| Tag | Native tag | Meaning |
|---|---|---|
Pulse.Save.Storage.Game | TAG_PurposeGame | The slots of the game (menus, auto saves, Ironman) |
Pulse.Save.Storage.Profile | TAG_PurposeProfile | The profile of each local player |
Pulse.Save.Storage.Server | TAG_PurposeServer | Data the server keeps for itself and its players |
Pulse.Result.Failure.Save.Storage.NotFound | TAG_FailureNotFound | The slot, the entry or the asked version is not there |
Pulse.Result.Failure.Save.Storage.InvalidName | TAG_FailureInvalidName | An owner, slot or entry the storage cannot keep |
Pulse.Result.Failure.Save.Storage.Unsupported | TAG_FailureUnsupported | The storage does not keep this kind of owner or does not do this operation |
Pulse.Result.Failure.Save.Storage.ReadFailed | TAG_FailureReadFailed | Reading failed (disk, network) |
Pulse.Result.Failure.Save.Storage.WriteFailed | TAG_FailureWriteFailed | Writing failed; nothing of the package landed |
Pulse.Result.Failure.Save.Storage.Damaged | TAG_FailureDamaged | The stored bytes failed the storage’s own check |
Pulse.Result.Failure.Save.Storage.Full | TAG_FailureFull | No room (disk full, quota, the largest package of the storage) |
Pulse.Result.Failure.Save.Storage.Unavailable | TAG_FailureUnavailable | The storage cannot be reached now (offline, no signed-in user) |
Timeouts and cancels use the reasons of Pulse Foundation. IsValidName(Name) is the name rule every storage accepts (1 to 64 characters without control characters, / or \, not only dots or spaces); MakeFailure(Reason, Diagnosis, NativeCode) makes a storage failure. Helpers for storage classes: GetOrMakePackageId(Package), GetPackageTime(Package), AddVersionToSlotInfo(Slot, SizeBytes, ModifiedAt, PackageId) (List Slots from the entries, the way a mirror compares them) and SortSlots(Slots). Pulse::Save::MirrorRecordSlotName (_PulseMirror) is the reserved slot of the record of a mirror; Pulse::Save::IsReservedSlotName(SlotName) tells reserved slots, plugins add theirs with AddReservedSlotName(Name) / RemoveReservedSlotName(Name) and AddReservedSlotPrefix(Prefix) / RemoveReservedSlotPrefix(Prefix) (each call counts once); GetReservedSlotNames() lists them (prefixes end with *).
Plans, slot meta and entry stamps
Tombstone plan (Data/PulseSaveTombstonePlan.h)
namespace Pulse::Save, see Core concepts:
| Function | Purpose |
|---|---|
PlanTombstones(SaveGame, Destroyed, FormerIds) | Pure: FPulseSaveTombstonePlan (Move, Remove, Tombstone, AlreadyTombstones) from FPulseSaveDestroyedObject ids |
ApplyTombstones(SaveGame, Plan, MadeRecords) | Pure: moves, removals, then the made records; FPulseSaveTombstoneResult (Moved, Removed, Tombstoned, Failed) |
MakeTombstoneRecord(Identifier, Manager, OutRecord) | The tombstone record of an id (the model lives in the manager) |
IsTombstoneRecord(Record) | Whether a record is a tombstone |
UPulseSaveDestroyTracker::GetDestroyedObjects() | The destroyed objects of a world, one per id |
Chunk plan (Data/PulseSaveChunkPlan.h)
Pulse::Save::PlanChunks(EPulseSaveManagerProcessType Type, TConstArrayView<FPulseSaveChunkModel> Models) returns an FPulseSaveChunkPlan (Chunks of FPulseSaveChunkIndices, indices into Models; bCapturedAtEnd), pure; MakeChunkModel(Model) reads LoadPriority, Timing and Capture of a model. UPulseSaveManager::BuildChunks (virtual) runs it (Two phases).
Slot meta functions (Slots/PulseSaveSlotMeta.h)
namespace Pulse::Save, see Save and load menus:
| Function | Purpose |
|---|---|
MakeMetaSaveGame(Base, Meta, OutGame) | The meta save game: the records of Base (copied) plus the meta record |
GetMetaFromSaveGame(Game, OutMeta) | The meta of a meta save game |
ReadSlotMeta(Slot, Done) | Reads the meta of a slot (FPulseSaveSlotMetaDone: result, bHasMeta, meta); Blueprint Read Slot Meta (Async) |
WriteSlotMeta(Slot, EntryId, Meta, Done) | Writes the meta alone (ReplaceCurrent), the other records stay; Pulse.Result.Failure.Save.ForeignMeta for a meta of the game; Blueprint Write Slot Meta (Async) |
ListSlotsWithMeta(Storage, Owner, Prefix, Done) | The slots of an owner with their meta, newest first (FPulseSaveSlotListDone with FPulseSaveSlotListEntry: Info, bHasSlotMeta, Meta); Blueprint List Slots With Meta (Async) |
MakeNewSlotName(Prefix, TakenNames) | Pure: the first free <Prefix>_0001, … |
GetSlotDate(Entry) / SortSlotsByDate(Slots) | The saved date of the meta, else the date of the slot; newest first |
ClassifyMetaRead(Read, Bytes, OutGame, OutMeta, bOutHasMeta) | Pure (Slots/PulseSaveSlotResult.h): what the meta entry holds (EPulseSaveMetaRead: Missing, Pulse, Foreign, Unreadable) |
ChooseLoadedMeta(Loaded, Version, Current, Previous, OutMeta) | Pure (Slots/PulseSaveSlotResult.h): the meta of a loaded save (a meta with the loaded stamp wins, current before previous) |
GatherSaveListFields(World, OutFields) | The save list fields of the objects of a world that save themselves as bytes (PulseByteSaveModel.h); Make Slot Meta puts them into the meta |
CompressThumbnail(Pixels, Size, MaxWidth, OutJpeg) / CaptureThumbnail(World, MaxWidth, Callback) | A preview picture as JPEG; the next frame of the game viewport |
Blueprint (UPulseSaveSlotMetaLibrary): Make Slot Meta, Format Play Time, Make Thumbnail Texture; Capture Slot Thumbnail (UPulseSaveCaptureThumbnail, pin On Captured with the JPEG bytes, empty without a game viewport). UPulseSavePlayTimeSubsystem (game instance) counts the play time: Get Play Time, Set Play Time.
Entry stamps (Slots/PulseSaveEntryStamp.h)
FPulseSaveEntryStamp (EntryCategory, EntryIdentifier, Size, Crc) names the bytes of one saved entry; FPulseSaveSlotMeta::Entry holds the stamp of the save a meta was written with (see Save and load menus).
Function (namespace Pulse::Save) | Purpose |
|---|---|
MakeEntryStamp(EntryId, Bytes) | The stamp of the bytes (size, CRC32) |
HasEntryStamp(Stamp) | Whether it names an entry |
GetStampEntryId(Stamp) | The entry it names |
CompareEntryStamps(Meta, Loaded) | EPulseSaveStampMatch: Unknown (no stamp, or another entry), Match, Mismatch |
IPulseSaveInterface
All 13 functions are BlueprintNativeEvent with a default implementation — see Implementing saveable objects for which ones you actually need to override.
| Blueprint event/function | C++ declaration | Default |
|---|---|---|
| Get Unique Save Identifier | FName GetUniqueSaveIdentifier() const | NAME_None |
| Get Save Identity | FPulseSaveIdentity GetSaveIdentity() const | unset (no tag, no key) |
| Should Save | EPulseSaveChoice ShouldSave(UPulseSaveManager* SaveManager) const | Default (→ Yes) |
| On Save | void OnSave(UPulseSaveManager* SaveManager, UPulseSaveModel* SaveModel) | no-op |
| On Post Save | void OnPostSave(UPulseSaveManager* SaveManager, UPulseSaveModel* SaveModel) | no-op |
| Is Ready To Save | EPulseSaveChoice IsReadyToSave(UPulseSaveManager* SaveManager, const UPulseSaveModel* SaveModel) const | Default (→ Yes) |
| On Load | void OnLoad(UPulseSaveManager* SaveManager, UPulseSaveModel* SaveModel) | no-op |
| Is Ready To Load | EPulseSaveChoice IsReadyToLoad(UPulseSaveManager* SaveManager, const UPulseSaveModel* SaveModel) const | Default (→ Yes) |
| On Post Load | void OnPostLoad(UPulseSaveManager* SaveManager, UPulseSaveModel* SaveModel) | no-op |
| On Load Failed | void OnLoadFailed(UPulseSaveManager* SaveManager, const UPulseSaveModel* SaveModel, EPulseSaveLoadFailureType FailureType) | no-op |
| Get Load Priority | int32 GetLoadPriority() const | 0 |
| Get Save Model Class | TSubclassOf<UPulseSaveModel> GetSaveModelClass(UPulseSaveManager* SaveManager) const | nullptr |
| Is Persistent | bool IsPersistent() const | false |
Enums:
EPulseSaveChoice:Default,Yes,NoEPulseSaveLoadFailureType:Unknown,ObjectNotFound,PreLoadFailed,PostLoadFailed,LoadTimeout,MigrationFailed,Destroyed
Identifiers of saveable objects (Models/PulseByteSaveModel.h, Data/PulseSaveIds.h)
For objects of both kinds (IPulseSaveInterface and IPulseByteSaveable of PulseFoundation), C++ only:
| Function | Description |
|---|---|
Pulse::Save::IsSaveable(Object) | Whether PulseSave can save the object (one of the two interfaces) |
Pulse::Save::AddObjectFilter(Owner, Filter), RemoveObjectFilter, IsLeftOut(Object) | Objects an add-on keeps itself (the characters of PulseSaveCharacters): the collectors and the session neither save nor load what a filter takes |
Pulse::Save::GetObjectSaveIdentifier(Object) | The name of its record: save interface: the own identifier, else the key of the Save Identity (Pulse::Serialization::MakeSaveKey), else for a component <owner id>.<component name> (or the name-based key <actor>.<component>), else none; bytes: GetSaveId |
Pulse::Save::GetObjectSaveIdentity(Object) | Its Save Identity (tag, key, scope), unset without one |
Pulse::Save::DescribeObjectSaveId(Object) | How far its identifier stays the same in the next session (EPulseSaveKeyStability: Stable, NameBased, SpawnOrder, None), one rule for both kinds |
Pulse::Save::CheckSaveIds(World, OutIssues) | The problems of the identifiers of a world (FPulseSaveIdIssue: Missing, Duplicate, Streamed, NameBased), what Pulse Check reports |
Pulse::Save::CheckAutoComponentSaveIds(OutIssues) | The same for the classes of automatic components (their Save Identity) |
Pulse::Save::GetIdentifierKind(Identifier) | The first part of an identifier (Player, World, …), Name without a dot |
UPulseSaveModelBase / UPulseSaveModel
See Models and collectors for the full description; quick reference:
| Function | Class | Notes |
|---|---|---|
InitializeNewModel() | UPulseSaveModelBase | Called when creating a fresh model (no record). |
InitializeFromRecord(const FPulseSaveModelRecord&) | UPulseSaveModelBase | Called when loading from an existing record. |
OnPreSave() / OnPostSave() | UPulseSaveModelBase | Save lifecycle hooks. |
OnPreLoad() / OnPostLoad() | UPulseSaveModelBase | Load lifecycle hooks. |
GetIdentifier() | UPulseSaveModelBase | Returns Identifier on UPulseSaveModel. On UPulseStaticSaveModelBase it must be provided: override it in C++ or implement the event “Get Identifier” in Blueprint. |
SetSaveObject(UObject*) | UPulseSaveModel | Binds a live object to this model. |
InitializeWithoutSaveObject() | UPulseSaveModel | Called on load when no live object matched. |
IsReadyToSave() / IsReadyToLoad() | UPulseSaveModelBase | Polled every tick. Base default false (the model calls ReadyToSave() / ReadyToLoad() itself). UPulseSaveModel delegates to the bound object’s IPulseSaveInterface + Blueprint event. |
HasSaveObject() | UPulseSaveModel | BlueprintPure. |
NotifyLoadFailed(EPulseSaveLoadFailureType) | UPulseSaveModel | Forwards to the bound object’s OnLoadFailed. |
GetTimeoutOverride(float& OutTimeout) | UPulseSaveModelBase | Return true + set OutTimeout to override UPulseSaveSettings::DefaultProcessTimeout. |
IsPersistent() / GetLoadPriority() | UPulseSaveModel | Override the base defaults: delegate to the bound object’s IPulseSaveInterface::IsPersistent, and the load priority cached during save from IPulseSaveInterface::GetLoadPriority. |
GetModelVersion() | UPulseSaveModelBase | Schema version stored in every record (default 0). Blueprint: implement the event “Get Model Version”. See Save migration. |
LogInfo(Message) / LogWarning(Message) / LogError(Message) | UPulseSaveModelBase | Write a message that appears with the model in the report. An error makes the model faulty in the report. Blueprint nodes. See Reports. |
GetRecordType() | UPulseSaveModelBase | Collected (default) or Static (UPulseStaticSaveModelBase). See EPulseSaveRecordType. |
IsPersistent() | UPulseSaveModelBase | Default true. UPulseSaveModel asks its object. Static models are always persistent. |
GetLoadPriority() | UPulseSaveModelBase | Default MIN_int32 (loads after all object models). |
PrepareLoadTarget() | UPulseSaveModelBase | Called by the load processor before OnPreLoad. |
GetObjectForModelClassResolution() | UPulseSaveModel | Object used to find the model class a record has to be migrated to. Default: the bound object. |
ReadyToSave() / ReadyToLoad() | UPulseSaveModelBase | C++. Call once the asynchronous preparation is done. |
GetSaveTiming() / GetSaveCapture() | UPulseSaveModelBase | C++. EPulseSaveTiming (default Synchronous) and EPulseSaveCapture (AtRequest default, AtEnd). See Core concepts. |
OnAbortSave() / OnAbortLoad() | UPulseSaveModelBase | C++. Called when a running save or load of the model is cancelled. |
GetSaveManager() | UPulseSaveModel | BlueprintPure, protected: the manager of the model. |
Properties: SaveObject (BlueprintReadOnly, transient), Identifier (BlueprintReadOnly), LoadPriority (BlueprintReadWrite), bSerializeAllSaveGameProperties (EditAnywhere, default false). Identifier and LoadPriority are saved with the record.
UPulseByteSaveModel (Models/PulseByteSaveModel.h) is the model of objects that save themselves as bytes (IPulseByteSaveable of PulseFoundation): GetBytes() and GetDataVersion() (C++) return what the object wrote. Its capture is AtEnd.
UPulseSaveActorModel / UPulseSaveActorModelBase
| Property/function | Notes |
|---|---|
LoadType (EPulseSaveActorLoadType) | ExistingOnly, ExistingOrSpawn, AlwaysSpawn. |
TransformSaveFlags (EPulseActorTransformSaveFlags, bitmask) | Location, Rotation, Scale, LocationAndRotation, All. |
TeleportType (ETeleportType) | Applied when restoring location/rotation. |
HandleSpawnActor() / GetSpawnTransform() / BuildSpawnParameters(...) | Protected virtuals for custom spawn behavior (subclass UPulseSaveActorModelBase). |
Collector APIs
UPulseSaveCollectorBase
| Blueprint node | C++ function |
|---|---|
| Collect Save Objects | bool CollectSaveObjects(TSet<UObject*>& OutSaveObjects) |
| Collect Load Objects | bool CollectLoadObjects(TSet<UObject*>& OutLoadObjects) |
| On Load Model Not Found | void OnLoadModelNotFound(UObject* InObject) (BlueprintNativeEvent) |
| Collect Components | bool bCollectComponents (default true): the world and the actor collector also take the components with IPulseSaveInterface of the actors they go through |
| — | virtual bool ShouldCollectComponent(UActorComponent* InComponent) const (C++ only): filter of those components |
| — | int32 AddSaveComponents(const AActor* InActor, TSet<UObject*>& OutObjects) const: adds them for a collector of your own |
UPulseSaveByteCollector / UPulseSaveWorldCollector
UPulseSaveByteCollector (Models/PulseByteSaveModel.h) collects every object that saves itself as bytes. UPulseSaveWorldCollector (Collectors/PulseSaveWorldCollector.h) derives from it and is the default collector of the save game: actors and components with the save interface, actors and components that save themselves as bytes and save carriers.
| Blueprint node / property | C++ |
|---|---|
| Collect World | bool bCollectWorld (default true): actors and components of the manager’s world |
| Register Object | void RegisterObject(UObject* Object): an object outside the world (game instance, subsystem) |
| Unregister Object | void UnregisterObject(UObject* Object) |
| — | virtual bool ShouldCollectActor(AActor* InActor) const (UPulseSaveWorldCollector, C++ only) |
UPulseSaveActorCollector
| Blueprint node/event | C++ function |
|---|---|
| Collect Actor For Save | bool CollectActorForSave(AActor* InActor) (default true) |
| Collect Actor For Load | bool CollectActorForLoad(AActor* InActor) (default true) |
| — | virtual bool ShouldCollectActor(AActor* InActor) const (C++ only, additional filtering) |
UPulseSaveRegisterCollector
| Blueprint node | C++ function |
|---|---|
| Register Object | bool RegisterObject(UObject* Object, const FPulseSaveRegisterCollectorParams& Params = FPulseSaveRegisterCollectorParams()) |
| Unregister Object | bool UnregisterObject(UObject* Object) |
FPulseSaveRegisterCollectorParams fields: bCollectForSave, bCollectForLoad, bLoadOnRegister, bRemoveIfDestroyed, OnLoadedOnRegister (native-only delegate, set via .OnLoadedOnRegisterDelegate(...)).
UPulseSaveSettings
Project Settings > Pulse > Save (UPulseDeveloperSettings, DefaultGame.ini).
| Field | Class | Default |
|---|---|---|
ManagerClass | UPulseSaveSettings | none (UPulseSaveManager): save manager of the game and of the menus |
CollectorClasses | UPulseSaveSettings | world collector (UPulseSaveWorldCollector) |
EntryId | UPulseSaveSettings | Game (entry of the slot the game is saved into) |
SlotPrefix | UPulseSaveSettings | Save (start of the names of new slots and the slots the game and the menus list; empty: all) |
MaxSlots | UPulseSaveSettings | 0 (most slots a player can have; the save menu offers no new save once reached; 0: no limit) |
ThumbnailWidth | UPulseSaveSettings | 320 (width of the preview picture of a save; 0: none) |
ProfileSlotPrefix | UPulseSaveSettings | Profile (slot of the profile of each local player among the slots of its platform user: Profile, Profile_1 for a player that shares its user with a player before it, in the editor Profile_PIE1) |
ProfileClass | UPulseSaveSettings | none (UPulseSaveProfile, free values only): class of the profile, a Blueprint with SaveGame variables |
bSaveProfilesOnQuit | UPulseSaveSettings | true (profiles that changed are saved when their local player goes; unchanged ones stay as they are) |
StorageClasses | UPulseSaveSettings | empty (storage class per purpose, Pulse.Save.Storage.*) |
DefaultStorageClass | UPulseSaveSettings | none (storage of every purpose without its own class; empty: Files) |
RootDirectory | UPulseSaveSettings | empty (Files: folder of the slots; empty: Saved/SaveGames) |
bEnableSlotBackups | UPulseSaveSettings | true (Files: every save keeps the version before it, .sav.prev) |
StorageTimeoutSeconds | UPulseSaveSettings | 60 (a storage request without an answer fails with a timeout; 0: wait forever) |
StorageShutdownSeconds | UPulseSaveSettings | 10 (how long the end of the game waits for storage work) |
DefaultByteLayers | UPulseSaveSettings | every layer off (FPulseSaveByteLayers: compression, check sum, cipher of every storage) |
ByteLayersByPurpose | UPulseSaveSettings | empty (byte layers of a purpose instead of DefaultByteLayers) |
MirrorOptions | UPulseSaveSettings | ConflictRule Newer, SyncIntervalSeconds 300 (mirrors of a purpose a plugin keeps in step with a cloud) |
DefaultModelClass | UPulseSaveSettings | UPulseDefaultObjectSaveModel (model when no factory can create one) |
DefaultProcessTimeout | UPulseSaveSettings | 60.0 seconds (-1 disables) |
MigrationFallback | UPulseSaveSettings | Fail (EPulseSaveMigrationFallback: Fail, ReinterpretByProperty, KeepOldModel) |
ReportPolicy | UPulseSaveSettings | EditorMode Always, PackagedMode OnFailure (EPulseReportMode: Disabled, OnFailure, Always), MaxStoredReports 50 (0 keeps all) |
bDestroyObjectsWithTombstone | UPulseSaveSettings | true (a load destroys the actor of an object whose record is a tombstone; off: only OnLoadFailed with Destroyed) |
bCheckBeforeLoad | UPulseSaveSettings | true (LoadFromSlot checks every record first and falls back to the previous version while the storage keeps one) |
bKeepPlayerData | UPulseSaveSettings | true (a running session saves players who leave and applies their data when they join) |
AutoSaveTriggers | UPulseSaveSettings | every trigger false (bOnHostQuit, bOnBackground, bOnFocusLost, bOnQuit) |
DefaultModelFactory | UPulseSaveSettings | none |
SaveModelFactories | UPulseSaveSettings | empty |
Migrations | UPulseSaveSettings | empty (UPulseSaveModelMigration classes) |
ClassRedirects | UPulseSaveSettings | empty (old class path -> new class) |
See Model factories and settings for the factory resolution order and Save migration for migrations.
Save and load menus (PulseSaveMVVM, PulseSaveUI)
See Save and load menus for the full description; quick reference:
| Type / function | Notes |
|---|---|
UMVVMPulseSaveSlotList (“Pulse Save Slots”) | View model of a slot list: Refresh, SelectSlot, SelectSlotByName, GetSelectedSlot, FollowSaveGame, StopFollowing, IsEmpty, IsLoading. Properties bSlotsOfSaveGame (default true), StoragePurpose, Prefix, bIncludeNewSlot, NewSlotLabel. |
UMVVMPulseSaveSlot | One slot: GetSlotName, GetDisplayName, GetDateText, GetPlayTimeText, GetLevelText, GetThumbnail, IsNewSlot, IsCurrent. |
UPulseSaveUISubsystem | Local player: OpenMenu(Mode), OpenSaveMenu, OpenLoadMenu, CloseMenus, GetHandler. |
UPulseSaveUIHandler | What the menu calls (BlueprintNativeEvent): SaveToSlot(SlotName, DisplayName, Done), LoadFromSlot(SlotName, Done), DeleteSlot(SlotName, Done), CanSave, CanLoad; GetPlayerController, GetSaveGame. Answers with FPulseResult. UPulseSaveUIDefaultHandler adds nothing. |
UPulseSaveMenu | The menu widget: SetMode, GetMode, GetSlotList, Refresh, SaveOrLoadSelected, DeleteSelected, AnswerConfirm(bYes), IsConfirmShown, IsBusy; properties Mode, bCloseAfterSave, bCloseAfterLoad; events OnSaved, OnLoaded. |
EPulseSaveMenuMode | Save, Load. |
UPulseSaveUISettings | Project Settings > Pulse > Save > UI: HandlerClass, MenuClass, PresenterClass. |
Report API
| Type / function | Notes |
|---|---|
Pulse::Save::IsRecordingReports() | Whether reports are recorded in this build (ReportPolicy is not Disabled). |
UPulseSaveManager::SetReportContext, SetReportSlot, GetReportSlotName, FlushReports | Context and slot of the reports, submit collected operations now. |
UPulseSaveModelBase::LogInfo, LogWarning, LogError, FPulseSaveModelMessage | Messages of a model (severity EPulseDebugSeverity). |
Pulse::Debug::OnReportSubmitted(), Pulse::Debug::Reports::* (PulseFoundation) | Reports of all plugins (Pulse Save: plugin Save) and their files. |
See Reports.
Migration API
| Type | Notes |
|---|---|
UPulseSaveModelMigration | Base class of a migration step. Migrate(const FPulseSaveMigrationContext&) (BlueprintNativeEvent), SourceClass, SourceVersion, TargetClass, TargetVersion. |
FPulseSaveMigrationContext | Old/new model, save object, manager, identifier, old class path and version. |
FPulseSaveMigrationRegister (IPulseSave::Get().GetMigrationRegister()) | RegisterMigration, UnregisterMigration, RegisterClassRedirect, UnregisterClassRedirect, ResolveClassRedirectPath, BuildMigrationPath, LoadModelFromRecord, MigrateRecordInto. |
EPulseSaveMigrationResult | NotNeeded, Migrated, FallbackReinterpreted, KeepOld, Failed. |
UPulseSaveMigrationLibrary | Blueprint nodes: Register Migration, Unregister Migration, Register Class Redirect, Unregister Class Redirect. |
UPulseSaveUnresolvedModel | Placeholder for a record whose model class no longer exists. |
FPulseSaveModelRecord | GetModelVersion(), GetModelClassPath(), IsCompatibleWith(Model), LoadModel(Model, bAllowClassMismatch). |