Model factories and settings

How model creation works

FPulseSaveModelFactoryRegister::CreatePulseSaveModel resolves models in this order:

  1. IPulseSaveInterface::GetSaveModelClass override from the target object
  2. Registered factories (RegisterModelFactory, reverse registration order)
  3. Default blueprint factory (DefaultModelFactory)
  4. Default script factory (SetDefaultScriptFactory)
  5. UPulseSaveSettings::DefaultModelClass

UPulseSaveManager::GetOrCreateModelForObject uses this to create the model, then calls InitializeNewModel(). If a model already exists for the object’s identifier (cached from a previous save or load), the cached model is rebound to the current object and reused instead. Every load and Load Object of the save game also reuse this identifier cache when resolving models from records. Static models are not part of this cache: they have their own records and identifiers (see Models and collectors). Cached object models are included in every save even when no collector returns them. ResetCachedSaveModels() of the manager clears the object-model cache, and New Game and Load Game of the save game clear it too. The manager keeps cached object-models alive across garbage collection until that reset is requested.

Built-in factory

At module startup (FPulseSaveModule::StartupModule), Pulse Save registers:

ModelFactoryRegister.RegisterModelFactory(MakeShared<FPulseSaveModelFactory_Actor>());
ModelFactoryRegister.RegisterModelFactory(MakeShared<FPulseSaveModelFactory_InfoActor>());

These map AActor objects to UPulseSaveDefaultActorModel and AInfo actors to UPulseSaveDefaultInfoActorModel. They are registered after the factories of the settings (SaveModelFactories), so they are asked first.

C++ custom factories

Use the provided macros:

DECLARE_SAVE_MODEL_FACTORY_EXTERN(MyFactory, MYMODULE_API)
DEFINE_SAVE_MODEL_FACTORY(MyFactory, AMySaveableActor, UMyActorSaveModel)

Then register:

IPulseSave::Get().GetModelFactoryRegister().RegisterModelFactory(MakeShared<FPulseSaveModelFactory_MyFactory>());

Blueprint model factory

Blueprint factories derive from UBP_PulseSaveModelFactory and implement:

UPulseSaveModel* CreatePulseSaveModel(UPulseSaveManager* SaveManger, UObject* ObjectToSave);

Return nullptr when a factory does not handle an object. Name the classes in Default Model Factory and Save Model Factories (block Model). In the editor the parent class is Pulse Save Model Factory.

Plugin settings

Project settings section is registered as:

  1. Project > Pulse > Save

Settings class: UPulseSaveSettings (a UPulseDeveloperSettings, Pulse::Save::GetSettings()). Factories, migrations and class redirects are read once when the module starts. The Game block holds the save manager of the save game: ManagerClass (empty: UPulseSaveManager; a C++ subclass of your own, see Customize), CollectorClasses (default: the world collector) and EntryId, and its slots: SlotPrefix, MaxSlots and ThumbnailWidth. The Profile block holds the profiles of the local players. The Storage block says where slots are kept (see Storage settings).

Available configuration fields:

  1. DefaultModelClass (UPulseSaveSettings): used as the last resort when no factory resolves a model for an object (default UPulseDefaultObjectSaveModel, which saves the UPROPERTY(SaveGame) fields; a check() requires this to always resolve to something valid).
  2. DefaultProcessTimeout (UPulseSaveSettings): default per-model save/load timeout in seconds (default 60.0, -1 disables it). Overridable per model via UPulseSaveModel::GetTimeoutOverride.
  3. DefaultModelFactory (UPulseSaveSettings): preferred blueprint factory, tried before the script default factory.
  4. SaveModelFactories (UPulseSaveSettings): additional blueprint factories registered at startup.
  5. MigrationFallback (UPulseSaveSettings): what happens if a record does not match its model and no migration is registered (Fail, ReinterpretByProperty, KeepOldModel; default Fail).
  6. Migrations (UPulseSaveSettings): UPulseSaveModelMigration classes registered at startup.
  7. ClassRedirects (UPulseSaveSettings): old model class path to new model class.
  8. ReportPolicy (UPulseSaveSettings): when reports are recorded in the editor and in a packaged game (Disabled, OnFailure, Always; defaults Always and OnFailure) and how many report files are kept (default 50).

  9. bKeepPlayerData and AutoSaveTriggers (UPulseSaveSettings): whether a running session saves players who leave and gives their data back when they join (default true), and when it saves on its own (every trigger off by default). See Save manager workflow.

  10. bCheckBeforeLoad (UPulseSaveSettings, block Slot): Load Game (every load from a slot) checks every record of the save game before anything is applied (default true). A damaged entry loads its previous version instead while the storage keeps one; if none is sound, the load fails with Damaged before the world is touched (GetLastSaveCheck lists the problems). See Save manager workflow.

  11. bDestroyObjectsWithTombstone (UPulseSaveSettings, block Tombstones): loading a save in which an object was destroyed for good destroys the object’s actor again (the actor of a component; default true). Off: only OnLoadFailed (Destroyed) tells the object.

  12. ProfileSlotPrefix, ProfileClass and bSaveProfilesOnQuit (UPulseSaveSettings, block Profile): the slot of the profile of each local player among the slots of its platform user (default Profile; a player that shares its user with a player before it gets its place added, Profile_1, and in the editor each play window gets its own, Profile_PIE1), the class of the profile (a Blueprint of Pulse Save Profile whose SaveGame variables are saved; empty: Pulse Save Profile) and whether changed profiles are saved when their local player goes (default true). See Save manager workflow.

See Reports for 8.

See Save migration for 5 to 7.

Storage settings

Project Settings > Pulse > Save > Storage says where PulseSave keeps its slots. Every slot belongs to a purpose, and each purpose has its own storage:

Purpose What it keeps
Pulse.Save.Storage.Game The slots of the save game: menus, auto saves, Ironman
Pulse.Save.Storage.Profile The profile of each local player
Pulse.Save.Storage.Server Data the server keeps for itself and its players
Setting Default What it does
StorageClasses empty A storage class per purpose (also for a purpose of your game).
DefaultStorageClass empty The storage of every purpose without its own class; empty: Files.
RootDirectory (Storage > Files) empty Folder of the Files storage; empty: Saved/SaveGames.
bEnableSlotBackups (Storage > Files) true Files: every save keeps the version before it (.sav.prev); a load of a damaged save falls back to it.
StorageTimeoutSeconds 60 A storage request without an answer for this long fails with a timeout (0: wait forever).
StorageShutdownSeconds 10 How long the end of the game (or of a play session in the editor) waits for storage work, such as the last saves.
DefaultByteLayers (Storage > Bytes) every layer off Compression, check sum and cipher of every storage (see Byte layers).
ByteLayersByPurpose (Storage > Bytes) empty Byte layers of a purpose instead of DefaultByteLayers.
MirrorOptions (Storage > Mirror) Newer, 300 Conflict rule and sync interval of mirrors, the purposes a plugin keeps in step with a cloud (see Mirror).

With both classes empty, every purpose keeps its slots in files on this machine (UPulseSaveStorage_Files): <Root>/<Purpose>/<Owner>/<Slot>/[<Category>/]<Identifier>.sav, with .sav.prev for the previous version, for example Saved/SaveGames/Game/User_0/Save_0001/Game.sav. A Files storage of your own can set RootDirectoryOverride, FolderOverride (default: the last part of the purpose tag) and, with bOverrideKeepPrevious, bKeepPreviousVersion for itself.

PulseSave also brings Platform (UPulseSaveStorage_Platform, the save games of the platform, see Platform save games), Memory (UPulseSaveStorage_Memory, slots in memory only, see Memory only) and Mirror (UPulseSaveStorage_Mirror, two storages kept in step, see Mirror) for Storage Classes and Default Storage Class. A purpose a plugin mirrors into a cloud (AddMirrorStorage, for example PulseOnlineSaveBridge) gets a mirror around the class of the settings by itself.

At runtime UPulseSaveStorageSubsystem::SetStorage(Purpose, Storage) or SetStorageClass(Purpose, StorageClass) changes the storage of a purpose (null goes back to the settings). The storage before finishes what it was asked first. See Storage for writing a storage of your own.

Resolving the model class

FPulseSaveModelFactoryRegister::ResolveModelClass follows the same order as CreatePulseSaveModel but only returns the class. It is used when loading to check if a record was saved with the model class an object uses now. IPulseSaveModelFactory::GetSaveModelClass(UObject*) lets a factory answer this without creating a model; DEFINE_SAVE_MODEL_FACTORY implements it.


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