Implementing saveable objects
The full contract
IPulseSaveInterface declares 13 functions. Every one is a BlueprintNativeEvent with a default implementation (return EPulseSaveChoice::Default, 0, false, nullptr, an unset identity, or no-op, as documented on each function in PulseSaveInterface.h), so you only need to override the ones that matter for your object.
| Function | When you need to override it |
|---|---|
GetUniqueSaveIdentifier | When the object has no Save Identity: without an identifier the object cannot be saved or loaded. An own identifier wins over the Save Identity. |
GetSaveIdentity | Instead of an own identifier: a tag and a key (see Save Identity or own identifier). |
ShouldSave | To conditionally exclude an object from saving (e.g. temporary/pooled objects). |
OnSave / OnPostLoad | To copy data between the live object and its model (see Core concepts). |
OnLoad / OnPostSave | For less common symmetric hooks (e.g. resetting state before deserializing). |
IsReadyToSave / IsReadyToLoad | Only for asynchronous data (e.g. waiting on a streamed level or async load). |
OnLoadFailed | To react to a failed load (e.g. destroy a partially-spawned actor). |
GetLoadPriority | To control load ordering relative to other objects. |
GetSaveModelClass | To force a specific model class instead of relying on factory resolution (see Model factories and settings). |
IsPersistent | Stored with the record. Records stay until the object is destroyed either way. |
Save Identity or own identifier
The record of an object needs a name that is the same in every session. An object of the save interface gets it in one of two ways:
- A Save Identity (
GetSaveIdentity,FPulseSaveIdentityof PulseFoundation): a tag for what is saved and a key for which one. The record gets the key an object that saves as bytes gets (Saveable as bytes):Player.<player id>.<tag>on player actors and their components,<actor>.<tag>on other actors (with the level of sublevels and level instances),World.<tag>.<key>with scope World. Renaming a component does not lose the saves; objects that must survive a rename of their actor use scope World with a Key. - An own identifier (
GetUniqueSaveIdentifier, a fixedFNamesuch as an instance-editableSaveId). It wins when it is not None, like an ownGetSaveIdof an object that saves as bytes.
A component with neither of them is named after its actor and its own name: <owner id>.<component name> when the actor saves itself and has a record name (Chest_07.Lock), else the name-based key an object that saves as bytes gets (<actor>.<component>, Player.<player id>.<component> on player actors). Renaming the component or the actor loses its saves, so Pulse Check reports it as Name based. Other objects with neither of them have no record name and are not saved.
Pulse::Save::GetObjectSaveIdentifier gives the name of the record for both kinds, Pulse::Save::GetObjectSaveIdentity the Save Identity (Models/PulseByteSaveModel.h). A model keeps the first key it got from a Save Identity: when the key changes while the game runs (a pawn without its player for a moment), the record keeps its name and the model logs a warning. Loads and the destroy tracker look the object up under its current key, so while the key differs a load does not find the kept record (the object gets ObjectNotFound) and a destroyed object is noted under the new key; both work again once the key comes back (the same as for objects that save as bytes). An own identifier names the record of every save, so a new own identifier renames the record.
Fixed identifiers and Pulse Check
Objects placed in a level need an identifier that is the same in every session. Pulse Check (Pulse window, Workflow tab, or -run=PulseCheck) checks the saveable actors and components of the open level (Pulse::Save::CheckSaveIds, Data/PulseSaveIds.h; both IPulseSaveInterface and IPulseByteSaveable objects, with one rule for both: Pulse::Save::DescribeObjectSaveId):
- Missing (warning): the object has neither an identifier nor a Save Identity, saves skip it. Components are not missing: they are named after their actor (see above) and reported as Name based.
- Duplicate (error): two objects share an identifier, only one of them is saved.
- Streamed (warning): the actor is spatially loaded in a World Partition level, so it streams out with its cell. Its record stays, but what changed since the last save is lost when the cell unloads. Turn off Is Spatially Loaded, or keep state that has to outlive streaming in Pulse Sim of Pulse Foundation (records by id, replicated by cell, saved as byte saveables). PulseSave keeps no memory of streamed-out objects of its own.
- Name based (warning): the save id is made from object names: an object that saves as bytes with its default id and without a Save Identity (renaming the actor or the component loses the saves), a component of the save interface named after its actor, an own identifier equal to the name-based key
<actor>.<component>, or a key that contains the name of an actor spawned while playing (it depends on the spawn order; also a Save Identity with scope Owner on such an actor). Give the object a Save Identity or a fixed identifier. A Save Identity with scope Owner on a placed actor still contains the actor’s name (renaming the actor loses the saves); objects that must survive a rename use scope World with a Key. Pulse Check does not warn about those.
Automatic components (added by FPulseAutoComponent entries of the plugin settings) are never in the editor world, so Pulse Check checks the Save Identity in their classes (Pulse::Save::CheckAutoComponentSaveIds): one on the game state with scope Owner (the game state is spawned; use scope World) and one on a player actor with scope World (ignored there) are reported as Name based, a component that saves as bytes without a Save Identity in its constructor too (its key is made from the class name). A component of the save interface without a Save Identity and without an own identifier is Missing.
C++ example
#include "Interfaces/PulseSaveInterface.h"
UCLASS()
class AMySaveableActor : public AActor, public IPulseSaveInterface
{
GENERATED_BODY()
public:
virtual FName GetUniqueSaveIdentifier_Implementation() const override
{
return FName(TEXT("MyActor_01"));
}
virtual void OnSave_Implementation(UPulseSaveManager* SaveManager, UPulseSaveModel* SaveModel) override
{
if (UMyActorModel* Model = Cast<UMyActorModel>(SaveModel))
{
Model->Health = Health;
}
}
virtual void OnPostLoad_Implementation(UPulseSaveManager* SaveManager, UPulseSaveModel* SaveModel) override
{
if (const UMyActorModel* Model = Cast<UMyActorModel>(SaveModel))
{
Health = Model->Health;
}
}
};
SaveManager is the manager that saves or loads the object: the manager of the save game, of a profile or of an add-on. An object that is saved or loaded on its own (spawned while the game runs, or right before it is destroyed) asks the save game: Save Object (Async) and Load Object (Async) in Blueprint, SaveObject and LoadObject in C++. Each answers once, never inside the call.
With a Save Identity instead of an own identifier (the tag is a gameplay tag of your game; set the key per instance for objects that exist more than once):
UCLASS()
class AMyChest : public AActor, public IPulseSaveInterface
{
GENERATED_BODY()
public:
AMyChest()
{
SaveIdentity.Tag = TAG_MyGame_Save_Chest;
SaveIdentity.Scope = EPulseSaveScope::World;
}
virtual FPulseSaveIdentity GetSaveIdentity_Implementation() const override
{
return SaveIdentity;
}
/** Key per placed chest ("North"): the record is World.MyGame.Save.Chest.North. */
UPROPERTY(EditAnywhere, Category = "Save")
FPulseSaveIdentity SaveIdentity;
};
Blueprint: same contract
In Blueprint classes that implement PulseSaveInterface, only implement the events you need. Unlike native C++, Blueprint events are always optional and fall back to the interface’s default when left unimplemented:
- Get Unique Save Identifier
- Get Save Identity
- Should Save
- On Save
- Is Ready To Save
- On Post Save
- On Load
- Is Ready To Load
- On Post Load
- On Load Failed
- Get Load Priority
- Get Save Model Class
- Is Persistent
Interface functions with a return value always get a graph in Blueprint; left as they are, they return the same defaults as the C++ implementation (Get Save Identity: an unset identity, so Get Unique Save Identifier names the record).
Example: a chest that implements Get Unique Save Identifier (from the instance-editable SaveId) and On Post Load, and keeps its data in variables with SaveGame checked, which the default actor model saves automatically. The save game of the game saves it without a Blueprint of your own (see Getting started).
Custom save model in C++
#include "Models/PulseSaveModel.h"
UCLASS()
class UMyActorModel : public UPulseSaveModel
{
GENERATED_BODY()
public:
// Declared explicitly instead of relying on bSerializeAllSaveGameProperties, see Core concepts.
UPROPERTY(SaveGame)
float Health = 0.f;
virtual bool OnPreSave() override
{
if (!Super::OnPreSave()) return false;
return true;
}
virtual bool OnPreLoad() override
{
if (!Super::OnPreLoad()) return false;
return true;
}
};
Blueprint models derive from UPulseSaveModel too, and can implement Is Ready to Save / Is Ready to Load events.