Models and collectors

UPulseSaveModelBase

Base lifecycle hooks:

  1. InitializeNewModel()
  2. InitializeFromRecord(const FPulseSaveModelRecord&): loads the record, or migrates it if it was saved with another class or model version (see Save migration).
  3. OnPreSave()
  4. OnPostSave()
  5. OnPreLoad()
  6. OnPostLoad()
  7. GetIdentifier()
  8. GetModelVersion()

Properties of a model are saved by name. To read records after a property was renamed or changed in a C++ model, override Serialize and use a custom version instead of a migration, see Changing a C++ model without a migration.

The save manager and the processors ask every model the same questions, so they need no special cases for object models. The defaults fit a custom model of a collector that is not bound to an object:

Function Default Meaning
GetRecordType() Collected Which kind of record the model is saved in.
IsPersistent() true Stored with the record; records stay until their object is destroyed either way.
GetLoadPriority() MIN_int32 Higher values load first. Models with the default load after all object models.
GetTimeoutOverride(float&) false Override of DefaultProcessTimeout.
IsReadyToSave() / IsReadyToLoad() false Polled every tick. false means the model calls ReadyToSave() / ReadyToLoad() itself.
GetSaveTiming() Synchronous Asynchronous for models that take frames; a save runs them first (two phases).
GetSaveCapture() AtRequest For asynchronous models: whether their data shows the request or their end.
PrepareLoadTarget() true Called before OnPreLoad. false fails the load of the model.
NotifyLoadFailed(...) no-op Object models forward it to their object.

UPulseSaveModel overrides these to use its bound object.

UPulseSaveModel

UPulseSaveModel adds object-bound save behavior. This is the class you subclass for the “model instead of object” pattern described in Core concepts.

Key functions:

  1. SetSaveObject(UObject* ObjectToSave)
  2. InitializeWithoutSaveObject(): called when loading a record with no matching live object.
  3. IsReadyToSave() / IsReadyToLoad(): polled every tick until ready or timed out.
  4. GetTimeoutOverride(float& OutTimeout)
  5. IsPersistent()
  6. GetLoadPriority()
  7. HasSaveObject()
  8. NotifyLoadFailed(EPulseSaveLoadFailureType)

Important properties:

  1. SaveObject (BlueprintReadOnly): the currently bound live object, or nullptr.
  2. Identifier: unique identifier of the model and name of its record, the bound object’s save id (Pulse::Save::GetObjectSaveIdentifier: its GetUniqueSaveIdentifier(), else the key of its Save Identity). A key of the Save Identity stays once the model has one (the record keeps its name, the model warns when it changes); an own identifier is taken again at every save.
  3. LoadPriority: higher values load first; taken from the object’s GetLoadPriority() at every save.
  4. bSerializeAllSaveGameProperties: false by default (recommended); set true to opt into automatically serializing every SaveGame property of the bound live object instead of declaring fields explicitly on the model.

Models and objects are written with every value, also those equal to the class default, so loading into a live object sets each value back (a chest opened after the save is closed again by the load).

Blueprint extension points (BlueprintImplementableEvent):

  1. Is Ready to Save (K2_IsReadyToSave)
  2. Is Ready to Load (K2_IsReadyToLoad)

UPulseSaveActorModel / UPulseSaveActorModelBase

Built-in actor model, registered automatically for AActor objects (see Model factories and settings):

  1. Saves actor class path, location, rotation, scale.
  2. Supports spawn-on-load via LoadType (EPulseSaveActorLoadType): ExistingOnly, ExistingOrSpawn, AlwaysSpawn.
  3. Applies transform according to TransformSaveFlags (EPulseActorTransformSaveFlags, bitmask of Location / Rotation / Scale) and TeleportType.

UPulseSaveActorModelBase provides the spawn/transform plumbing (HandleSpawnActor, GetSpawnTransform, BuildSpawnParameters) that UPulseSaveActorModel builds on; subclass UPulseSaveActorModelBase directly if you need custom spawn behavior without the built-in transform save flags.

UPulseSaveWorldCollector

The collector of the save game of a game and the default of Project Settings > Pulse > Save > Game (CollectorClasses). In one pass over the world of the manager it collects:

  1. actors with IPulseSaveInterface (models of the factories, like the actor collector below; ShouldCollectActor filters them) and the components with the interface of every actor of the world, also of actors without it (bCollectComponents, ShouldCollectComponent; see Components with the save interface),
  2. actors and components that save themselves as bytes (IPulseByteSaveable, like the byte collector below),
  3. save carriers (APulseSaveCarrier of Pulse Foundation): the way world subsystems save (the game clock, the time of day, the relations of factions). A carrier whose object is also registered by hand (RegisterObject) is left out, so nothing is saved twice.

It derives from the byte collector: bCollectWorld and RegisterObject work the same way. To collect only one of the two, name the actor or the byte collector in Collector Classes instead. A collector of your own goes into the same list (see Customize).

UPulseSaveActorCollector

Actor collector; scans world actors and includes those that:

  1. Implement IPulseSaveInterface.
  2. Pass CollectActorForSave(AActor*) / CollectActorForLoad(AActor*) (both BlueprintNativeEvent, default true).

Override ShouldCollectActor(AActor*) in C++ for additional filtering shared by both save and load. It also collects the components with the save interface of every world actor (see below); CollectActorForSave / CollectActorForLoad filter actors only.

Components with the save interface

The world and the actor collector take the components that implement IPulseSaveInterface on every actor they go through. The actor does not need the interface itself: a saveable lock component on a plain static mesh actor is saved and loaded like an actor.

   
bCollectComponents (Collect Components) On by default. Off: the collector takes actors only (the behavior of 1.0)
ShouldCollectComponent(UActorComponent*) C++ filter, shared by save and load. Default: valid components with the interface that no object filter leaves out

A component gets its own record with its own model (the factories decide, like for any object; without a factory the default object model saves its SaveGame properties). The record name follows the rules of the save interface: an own identifier, else the key of its Save Identity, else <owner id>.<component name> (see Save Identity or own identifier). A component that is loaded but has no record (a save written before the component existed, or before components were collected) gets OnLoadFailed with ObjectNotFound and keeps its values. Components of actors that a load spawns are not mapped in that load; give such actors a model that restores their components, or load them on their own afterwards.

UPulseSaveRegisterCollector

Manual collector for objects that aren’t reachable by iterating world actors: dynamically created objects, subsystems, non-actor UObjects, etc. Name it in Collector Classes; the collector then belongs to the manager of the save game (GetCollectors() of the manager).

// Collector: the register collector among the collectors of the manager
Collector->RegisterObject(MyObject, FPulseSaveRegisterCollectorParams()
    .CollectForSave()
    .CollectForLoad()
    .LoadOnRegister()
    .RemoveIfDestroyed());

FPulseSaveRegisterCollectorParams options:

  1. bCollectForSave (default true)
  2. bCollectForLoad (default true)
  3. bLoadOnRegister (default true): loads the object from the save game in memory as soon as it is registered (a single object process of the manager).
  4. bRemoveIfDestroyed (default true): auto-unregisters actors when destroyed.
  5. OnLoadedOnRegister: delegate fired once the bLoadOnRegister load completes, set via .OnLoadedOnRegisterDelegate(...).

Call UnregisterObject(Object) to remove an object from the collector manually.

Objects that save themselves as bytes

Components of the Pulse plugins (and of your game) that implement IPulseByteSaveable of Pulse Foundation need no model and no save bridge of their own: UPulseByteSaveModel keeps the bytes and the version the object wrote, and UPulseSaveByteCollector collects them. The world collector, the default of the save game, includes it; name the byte collector alone in Collector Classes to collect only these objects. An add-on that keeps some of these objects itself leaves them out with an object filter (see Customize).

   
bCollectWorld Collects every actor and component of the manager’s world that implements the interface (default on)
RegisterObject / UnregisterObject Objects outside the world (an object of the game instance)

Save carriers (APulseSaveCarrier) are actors that save themselves as bytes, so the byte collector takes them along; a carrier whose object is registered as well is left out.

The record identifier is the object’s GetSaveId() (by default made from its Save Identity: Player.<player id>.<tag> for components of players, <actor>.<tag> or World.<tag>.<key>; without identity from the names, Player.<player id>.<component>; see Saveable as bytes). Automatic components keep the name Pulse_<Class>_0 in every build, so ids made from their name are the same in the editor and in packaged games. Ids are looked up as they are: an object that changes its id (adopts an identity) does not find the record of its old id. The load priority is its GetLoadPriority(). Objects with GetSaveTiming() == Asynchronous (BeginSaveToBytes / BeginLoadFromBytes) are saved first, as models whose data shows the state at their end (two phases). Messages of the object’s import report appear in the save report.

  • The collector uses the models of the manager (GetOrCreateModelForObject): a model loaded or saved on its own before is the same one, so a full save has no duplicates.
  • Only objects that implement just IPulseByteSaveable are collected; an object that also implements IPulseSaveInterface uses a model of the factories, as everywhere else.
  • A model keeps its identifier (its record) once it has one. When GetSaveId() changes later (a player pawn without its player for a moment), the model warns and still writes into its record. Actors spawned while playing should use a Save Identity with scope World and a Key: the default with scope Owner uses the actor name, which depends on the spawn order (Pulse Check warns).
  • A callback of an earlier, aborted request (timeout, cancel) is dropped. A failed byte save keeps the bytes of the last good save in the record; version and priority are only taken together with new bytes.
  • A record of another model kind (a former save bridge) is migrated to the bytes model or reported, and a bytes record whose object now uses IPulseSaveInterface is migrated the other way (registered migrations or the fallback).

Static models (no live object)

For simple global/save-slot metadata that isn’t bound to any live object (save name, playtime, chosen difficulty, …), derive from UPulseStaticSaveModelBase and use the static model API of the save game (GetOrCreateStaticModel, SaveStaticModel) instead of a collector:

UCLASS()
class UMySaveMetaModel : public UPulseStaticSaveModelBase
{
    GENERATED_BODY()
public:
    virtual FName GetIdentifier() const override { return TEXT("SaveMeta"); }

    UPROPERTY() float PlaytimeSeconds = 0.f;
};

UPulseSaveGameSubsystem* SaveGame = UPulseSaveGameSubsystem::Get(this);

// Null without a save game: New Game, Save Game or Load Game first
UPulseStaticSaveModelBase* Model = SaveGame->GetOrCreateStaticModel(TEXT("SaveMeta"), UMySaveMetaModel::StaticClass());

if (UMySaveMetaModel* Meta = Cast<UMySaveMetaModel>(Model))
{
    Meta->PlaytimeSeconds += DeltaSeconds;

    // Optional: writes straight into the save game in memory right now
    SaveGame->SaveStaticModel(Meta);
}

In Blueprint, create a Blueprint class from PulseStaticSaveModelBase, add your data as variables, and implement the event Get Identifier to return the identifier. Request it with the node Get Or Create Static Model of the save game using the same identifier. The result is typed by the class you pass in. Both functions answer at once: they only change the save game in memory.

Static models are a separate path from the models that collectors produce:

  • They are stored in records of type Static (see Core concepts), always persistent, and have their own identifier space. An object and a static model may use the same identifier.
  • They are loaded and saved synchronously. They are not part of the chunks, processors, timeouts or the collected counters of the report. Their lifecycle is InitializeNewModel (no record yet) or InitializeFromRecord + OnPreLoad + OnPostLoad (record found), and OnPreSave + OnPostSave when saved.
  • GetOrCreateStaticModel returns the same instance for repeated calls with an identifier. The instance is registered with the manager of the save game, and the manager does not own it: keep a reference as long as you need it.
  • Every save writes all registered static models into the save game before collectors run, so you do not have to call SaveStaticModel before saving.
  • New Game and Load Game give the manager another save game and drop the static models it knew (policy Reset, below). A reference from before keeps its data but is no longer saved: call GetOrCreateStaticModel again after them. After Load Game the new model reads its record from the loaded save.
  • A static model that was not requested is not touched by a load. Its record stays in the save game.
  • Records of another class or model version are migrated when the model is loaded (see Save migration).

Calling SaveStaticModel manually is still useful when you want a static model persisted immediately (e.g. right before the next save into a slot), independent of the saves and loads of the game.

Cached models and the save game of the manager

Cached object models and registered static models were created against a particular save game’s records. When the save game of a manager changes, an EPulseSaveModelRetentionPolicy controls what happens to both model stores. The save game of the game uses Reset on New Game and Load Game; the policies matter for C++ code of a plugin that gives a manager another save game (SetSaveGame, ClearSaveGame):

  • Reset (default): clears all cached object models and unregisters all static models. Safest option; externally held model references remain valid but are no longer managed by the save manager.
  • RemoveMissing: removes only cached/static models whose identifier has no matching record of their type (Collected for object models, Static for static models) in the new save game.
  • KeepAll: keeps every cached and static model, regardless of whether it has a matching record in the new save game. Useful when swapping save games known to share the same model identifiers.

Reading a static model from a slot

A list of saves that shows a few values of each (a name, the play time) does not need to load every save into a manager. Pulse::Save::ReadStaticModel (PulseSaveUtils.h) reads one static model from the save game in an entry of a slot of a storage, without a manager or collectors, and answers on a later tick:

// Header: UPROPERTY() TObjectPtr<UMySaveMetaModel> SaveMeta;
Pulse::Save::ReadStaticModel(Slot, FPulseSaveSlotEntryId(TEXT("Game")), TEXT("SaveMeta"), UMySaveMetaModel::StaticClass(),
    FPulseSaveStaticModelDone::CreateWeakLambda(this, [this](const FPulseResult& InResult, UPulseStaticSaveModelBase* InModel)
    {
        // Null when the read failed; InResult says why
        SaveMeta = Cast<UMySaveMetaModel>(InModel);
    }));

In Blueprint the node is Read Static Model (Async); its pin On Done carries the result and the model.

  • The record is migrated like the record of any static model (see Save migration).
  • A save game that cannot be read is read from the previous version of the entry while the storage keeps one; nothing is written back.
  • The model is created in the transient package and belongs to no manager: keep it in a UPROPERTY as long as you need it.
  • Failures: the reason of the storage when the slot or the entry is missing or the read fails for now (offline, timed out), Pulse.Result.Failure.NotFound when the save game has no such record, Pulse.Result.Failure.Save.Damaged when no version of the entry can be read, Pulse.Result.Failure.Save.Failed when the record does not read into the model class, Pulse.Result.Failure.Invalid without an identifier or a model class.
  • The meta of the save menus is kept in an entry of its own (slot_meta): read it with ReadSlotMeta (see Save and load menus).

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