Customize
Pulse Save works with its defaults: the save game (UPulseSaveGameSubsystem) saves every saveable object of the world into files on this machine, with no setup. A game or a studio swaps or extends only the parts it needs. The code that saves and loads stays the same: it calls the save game, whatever the parts behind it are.
| Part | Default | Where to set it | Blueprint | More |
|---|---|---|---|---|
| Storage of a purpose | Files: folders on this machine | Project Settings > Pulse > Save > Storage, Storage Classes; at runtime Set Storage, Set Storage Class | Yes | Set the storage |
| Own storage | - | A class of Pulse Save Storage, named in Storage Classes | Yes | C++, Blueprint |
| Byte layers | Every layer off | Storage > Bytes: Default Byte Layers, Byte Layers By Purpose; Set Byte Layers on one storage | Yes | Byte layers |
| Own cipher | No cipher; AES comes with the plugin and needs a key | Cipher of the byte layers | Yes | Encryption |
| Second storage (mirror, cloud) | None | Mirror in Storage Classes, or a plugin with AddMirrorStorage | Yes | Mirror |
| Storage wrapper (around every storage of a purpose) | None | A plugin with AddStorageWrapper | C++ registration | Wrapper |
| Model factories | The actor factories, then Default Model Class | C++: RegisterModelFactory; Model > Default Model Factory, Save Model Factories | Yes (a Blueprint of Pulse Save Model Factory) | Model factories |
| Collectors | The world collector | Game > Collector Classes | Yes | Collectors |
| Object filter | None | Pulse::Save::AddObjectFilter | No | Leave objects out |
| Migrations | Migration Fallback Fail | Migration > Migrations, Class Redirects, Migration Fallback | Yes | Save migration |
| Own models and saveable objects | Default Model Class (UPulseDefaultObjectSaveModel) and the actor models | The save interface of the object, a factory or Default Model Class | Yes | Implementing saveable objects |
| Manager class | UPulseSaveManager | Game > Manager Class | No | The manager class |
| Reports | Always in the editor, on failure in a packaged game | Report > Report Policy | Settings only | Reports |
| Save and load menus | UPulseSaveUIDefaultHandler | Save > UI > Handler Class | Yes | The handler |
Where saves go (storage)
Each purpose (Pulse.Save.Storage.Game, .Profile, .Server) has its own storage. Files is the default; Platform keeps the slots in the save games of the platform, Memory in memory only. A storage of your own derives from Pulse Save Storage in C++ or Blueprint and only keeps bytes; PulseSave serializes, checks and migrates. See Purposes, Set the storage, Write a storage in C++ and Write a storage in Blueprint.
Encryption and byte layers
Compression, a check sum and a cipher work on the bytes of every entry, for every storage, also one of your own. All layers are off by default. A cipher of your own derives from Pulse Save Cipher: in Blueprint it implements Encrypt and Decrypt, in C++ it returns a work that may run on a background thread. See Byte layers and Encryption.
A second storage (mirror, cloud)
A mirror keeps two storages in step: the primary storage answers the game, the secondary storage gets the slots in the background. A plugin with a cloud registers its storage with AddMirrorStorage (PulseOnlineSaveBridge does this for the save game and the profiles); a game names Mirror or a Blueprint of it in Storage Classes. Any storage can be the secondary storage. See Mirror and What a secondary storage needs.
A plugin can also put a wrapper around the storage of a purpose (AddStorageWrapper, outside a mirror), for example to keep older versions of each slot; its data goes into reserved slots the lists never show. See Wrapper.
Which model an object gets (factories)
An object gets the model class it names itself (GetSaveModelClass), else the model of the first factory that handles it, else Default Model Class. A C++ factory is made with DEFINE_SAVE_MODEL_FACTORY and registered with RegisterModelFactory. The settings Default Model Factory and Save Model Factories take classes of UBP_PulseSaveModelFactory, which a Blueprint takes as its parent (Pulse Save Model Factory). See How model creation works, C++ custom factories and Blueprint model factory.
What gets saved (collectors)
Collectors find the objects a save writes and a load fills. The save game uses the classes of Collector Classes (Project Settings > Pulse > Save > Game); the default is the world collector: actors with the save interface, objects that save themselves as bytes and the save carriers. A collector of your own derives from Pulse Save Collector Base in C++ or Blueprint and overrides Collect Save Objects and Collect Load Objects. See Models and collectors.
Leave objects out (object filter)
An add-on that keeps some objects itself leaves them out of the save of the game with an object filter (Models/PulseByteSaveModel.h). PulseSaveCharacters does this: the objects of a character belong to its character source, not to the slot of the game. A filter returns true for an object to leave out:
#include "Models/PulseByteSaveModel.h"
void FMyAddOnModule::StartupModule()
{
// The objects of the stash belong to the stash of the add-on, not to the save of the game
Pulse::Save::AddObjectFilter(TEXT("MyAddOn"), [](const UObject* InObject)
{
return InObject && InObject->IsA<UMyStashComponent>();
});
}
void FMyAddOnModule::ShutdownModule()
{
Pulse::Save::RemoveObjectFilter(TEXT("MyAddOn"));
}
- One filter per owner. Adding a filter again under the same name replaces it. A name of None or an empty function is ignored.
RemoveObjectFilterremoves the filter of a name;IsLeftOut(Object)tells whether any filter takes an object. - Game thread. Add and remove filters on the game thread. A filter runs on the game thread for every object a save or load looks at, so keep it cheap.
- For the whole process. A filter holds for every manager and every game instance until it is removed, so remove it in
ShutdownModuleof the module that added it. - Where it applies. The byte collector and the world collector leave such objects out of every save and load (objects that save themselves as bytes, also ones registered with
RegisterObject). The session neither saves nor gives back the saveable actors and components of a player that a filter takes. - Where it does not apply. Actors with the save interface that the world or the actor collector takes (their components with the interface are left out by a filter), objects of the register collector, Save Object and Load Object, and static models.
The functions are listed in the API reference.
Old saves (migration)
When a model changes, a migration moves the records of an older version or class into the current model. A migration is a Blueprint or C++ class of Save Model Migration, registered in Migrations; Class Redirects map a renamed model class, and Migration Fallback says what happens without a migration. A C++ model can also read old records itself with a custom version. See Writing a migration, Registering migrations and Changing a C++ model without a migration.
Own models and saveable objects
Any object becomes saveable with the save interface (IPulseSaveInterface, C++ or Blueprint) or saves itself as bytes (IPulseByteSaveable of Pulse Foundation). A model of your own keeps exactly the data you want saved; data that belongs to no object goes into a static model. See Implementing saveable objects, Custom save model in C++ and Static models.
The manager class
The save game makes its save manager from Manager Class (Project Settings > Pulse > Save > Game; empty: UPulseSaveManager). A C++ subclass can change how models are made, grouped and processed through the virtual functions of the manager, such as GetOrCreateModelForObject, BuildChunks, GetProcessorClassForModel and CreateModelFromRecord. The class cannot be a Blueprint. A game still saves and loads through the save game; the manager is the type the save interface passes to your objects. See Save manager workflow.
Reports
Every save and load writes a report. Report Policy (Project Settings > Pulse > Save > Report) says when reports are recorded and how many files are kept. The save game gives the report of its last save and load (Get Last Save Report, Get Last Load Report). See Reports.