Model factories and settings
How model creation works
FPulseSaveModelFactoryRegister::CreatePulseSaveModel resolves models in this order:
IPulseSaveInterface::GetSaveModelClassoverride from the target object- Registered factories (
RegisterModelFactory, reverse registration order) - Default blueprint factory (
DefaultModelFactory) - Default script factory (
SetDefaultScriptFactory) 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:
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:
DefaultModelClass(UPulseSaveSettings): used as the last resort when no factory resolves a model for an object (defaultUPulseDefaultObjectSaveModel, which saves theUPROPERTY(SaveGame)fields; acheck()requires this to always resolve to something valid).DefaultProcessTimeout(UPulseSaveSettings): default per-model save/load timeout in seconds (default60.0,-1disables it). Overridable per model viaUPulseSaveModel::GetTimeoutOverride.DefaultModelFactory(UPulseSaveSettings): preferred blueprint factory, tried before the script default factory.SaveModelFactories(UPulseSaveSettings): additional blueprint factories registered at startup.MigrationFallback(UPulseSaveSettings): what happens if a record does not match its model and no migration is registered (Fail,ReinterpretByProperty,KeepOldModel; defaultFail).Migrations(UPulseSaveSettings):UPulseSaveModelMigrationclasses registered at startup.ClassRedirects(UPulseSaveSettings): old model class path to new model class.-
ReportPolicy(UPulseSaveSettings): when reports are recorded in the editor and in a packaged game (Disabled,OnFailure,Always; defaultsAlwaysandOnFailure) and how many report files are kept (default50). -
bKeepPlayerDataandAutoSaveTriggers(UPulseSaveSettings): whether a running session saves players who leave and gives their data back when they join (defaulttrue), and when it saves on its own (every trigger off by default). See Save manager workflow. -
bCheckBeforeLoad(UPulseSaveSettings, block Slot): Load Game (every load from a slot) checks every record of the save game before anything is applied (defaulttrue). A damaged entry loads its previous version instead while the storage keeps one; if none is sound, the load fails withDamagedbefore the world is touched (GetLastSaveChecklists the problems). See Save manager workflow. -
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; defaulttrue). Off: onlyOnLoadFailed(Destroyed) tells the object. ProfileSlotPrefix,ProfileClassandbSaveProfilesOnQuit(UPulseSaveSettings, block Profile): the slot of the profile of each local player among the slots of its platform user (defaultProfile; 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 (defaulttrue). 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.