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. RemoveObjectFilter removes 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 ShutdownModule of 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.


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