Getting started

Like every Pulse plugin, Pulse Save is used in four steps: Set Up, Create, Test and Check. The Pulse window (Tools > Pulse > Pulse) walks through them, and its Guide shows each step in the editor. The list at the start of each section comes from the plugin itself; the text after it goes into the details.

To see saving working before you build anything, start with Test: the plugin brings an example map.

The details walk through a minimal setup: enable the plugin, make an actor saveable, and save and load the game with its save game. The saveable chest is an example that you can create in your project from the Pulse Docs tab of the editor (Create in project…); no Blueprint of your own saves it.

Set Up

The Pulse window (Tools > Pulse > Pulse, tab Workflow, step Set Up) checks each of these and fixes it with a click:

  • Optional: Save the game when it is closed (Auto Save Triggers On Quit and On Host Quit). A game that was saved into a slot once (from a menu, Save Game or an auto save) is saved into it again when the player closes the game or the host leaves, without code of your own.
  • Optional: Connect with PulseGameplay: PulseGameplaySaveBridge. Saves inventories, equipment and crafting queues of PulseGameplay; Continue, Load and Save in its frontend menus.
  • Optional: Connect with PulseOnline: PulseOnlineSaveBridge. Syncs the save slots with the cloud storage of the player.
  • Optional: Connect with PulseTime: PulseTimeSaveBridge. Saves the game after a rest of Pulse Time (the time saves itself without a bridge).

Enable the plugin

Pulse Save needs the free base plugin PulseFoundation (1.0 or newer); it is enabled with Pulse Save.

Enable Pulse Save in Unreal Editor (Edit > Plugins), then restart the editor.

C++ module dependency

If you use Pulse Save in C++, add PulseSave to your module dependencies:

PublicDependencyModuleNames.AddRange(new string[]
{
    "Core",
    "PulseSave"
});

Save when the game is closed

The optional step turns on two auto save triggers of the session (Project Settings > Pulse > Save > Session, Auto Save Triggers): On Quit (the application closes) and On Host Quit (the host goes back to the menu or quits). A game that was saved into a slot once is then saved into it again without code of your own. The first save comes from a menu, Save Game or an auto save of your own; see Player data and auto saves.

Create

New assets come from Add > Pulse > Save in the content browser or New in the Pulse window:

  • Save Model (Blueprint of UPulseSaveModel): Saves one kind of object in a way of its own (versioned data, references to other objects); objects without one use the default model.
  • Save Model Migration (Blueprint of UPulseSaveModelMigration): Moves records of an older model version or model class into the current model when a save game loads.
  • Save Collector (Blueprint of UPulseSaveCollectorBase): Finds the objects a save manager saves and loads, besides the actor and register collectors of the plugin.
  • Save UI Handler (Blueprint of UPulseSaveUIDefaultHandler): What the save and load menus do in your game, on top of the default handler: override saving, loading or when saving is allowed; pick it in Project Settings > Pulse > Save > UI.
  • Starter content: A saveable chest (SaveGame variables, its own save id); the save game of the game saves and loads it, no save controller needed. Add Starter Content copies it to /Game/Pulse/PulseSave.

What a project creates with Pulse Save are saveable objects: the Pulse window counts the classes of the project that implement UPulseSaveInterface. The Blueprint classes above are only needed for data of your own (models), old save games (migrations) and objects that the built-in collectors do not find.

Make an object saveable

Every function on IPulseSaveInterface is a BlueprintNativeEvent with a default implementation, so you only need to override what you actually use. At minimum, give the object a stable identifier, or a Save Identity (a tag and a key, the keys of objects that save as bytes; see Save Identity or own identifier):

// MyActor.h
UCLASS()
class AMyActor : public AActor, public IPulseSaveInterface
{
    GENERATED_BODY()

public:
    virtual FName GetUniqueSaveIdentifier_Implementation() const override { return SaveId; }

    UPROPERTY(EditInstanceOnly, Category = "Save")
    FName SaveId;
};

In Blueprint: add PulseSaveInterface in Class Settings > Interfaces and implement Get Unique Save Identifier (or Get Save Identity). Actors without an own model get UPulseSaveDefaultActorModel, which saves the location and rotation of the actor and every variable with SaveGame checked (in the variable’s advanced details). The example chest saves bOpened and Gold this way, takes its identifier from the instance-editable SaveId and prints its state in On Post Load:

See Implementing saveable objects for the full contract, and Core concepts for why saving through a model instead of the actor directly is recommended once you go beyond trivial data.

Save and load the game

The save game of the game (UPulseSaveGameSubsystem, one per game instance) saves every saveable object of the world into a slot and loads it back. It is the one API of a game for saving and loading. It only saves and loads: it starts no game and shows no menus. With PulseGameplay the frontend calls it through PulseGameplaySaveBridge; without PulseGameplay the game calls its functions and async nodes itself.

It needs no setup: its manager and collectors come from the block Game of the save settings (Project Settings > Pulse

Save). The slots are kept in the storage of the save game: files on this machine (Saved/SaveGames/Game/User_0/Save_0001/Game.sav) unless you set another storage (see Storage).

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

SaveGame->SaveGame(SaveGame->MakeNewSlotName(), TEXT("At the lake"), FPulseSaveGameDone::CreateLambda([](const FPulseResult& Result)
{
    UE_LOG(LogTemp, Log, TEXT("Save: %s"), *Result.ToString());
}));

In Blueprint: Save Game (Async), Load Game (Async), Delete Slot (Async) and Auto Save (Async) (pin On Done with the result); New Game, End Game, Get Slots and Refresh Slots are in the category Pulse > Save > Game. Save Player (Async) and Apply Player (Async) save and give back the data of one player, Save Object (Async) and Load Object (Async) one object on its own.

Every request answers with a result: success, or a reason with a text for the player (only the host saves, a save or load is running, the slot is missing). A request that reads or writes a storage or waits for objects answers once and never inside the call: in C++ through FPulseSaveGameDone, in Blueprint through On Done. A request that only changes memory or reads a state, such as New Game or Lock Auto Save, answers at once. Can Save To Slot and Can Load From Slot tell a menu before it asks.

The storage answers a moment later, so the list of slots is not there at once: Is Slot List Ready tells when it is, and On Slots Changed fires when it comes or changes. A menu or a Continue button waits for it.

The save and load menus of the plugin work on the same save game (Save and load menus); the console has PulseSaveToSlot and PulseSaveLoadSlot (Console). Auto saves, the data of players who leave and come back and the slot meta are described in Save manager workflow.

The save manager

The save game makes its save manager (UPulseSaveManager) from the save settings; a game does not call the manager itself. Saveable objects get it as a parameter of the save interface (OnSave, OnPostLoad), and Manager Class in the block Game of the save settings names a class of your own (see Customize). The data of each local player outside a game (settings, unlocks) lives in its profile (see Profiles of the players).

Test

  • Play Example in the Pulse window opens /PulseSave/Examples/LV_PulseSave_Example and starts Play in Editor.
  • The Pulse Debugger opens on its page Pulse.Reports.
  • Three chests and the save game of the game: ke * Open opens the chests, PulseSaveToSlot saves them into a new slot (Save_0001 while there is none), PulseSaveLoadSlot Save_0001 loads them back; PulseSaveMenu Save and PulseSaveMenu Load open the save and load menus (with preview pictures); PulseSaveSlots lists the slots, the Reports page of the Pulse Debugger shows every save and load.

The example map

The plugin brings an example map, /PulseSave/Examples/LV_PulseSave_Example (enable Show Plugin Content in the content browser): three saveable chests (Chest1 to Chest3); the save game of the game saves them, the map has no Blueprint for it. Play Example for Save in the Pulse window opens it, starts Play in Editor and opens the Reports page of the Pulse Debugger. In the console: ke * Open opens the chests, PulseSaveToSlot saves them into a new slot (Save_0001 while there is none), stop and play again, PulseSaveLoadSlot Save_0001 loads them back opened. PulseSaveMenu Save and PulseSaveMenu Load do the same in the menus. PulseSaveSlots lists the slots and PulseSaveDeleteSlot Save_0001 removes the slot again (see Console). Add > Pulse > Save > Add Starter Content copies the chest to /Game/Pulse/PulseSave/Save.

Check

  • Check in the Pulse window, Check All there (console Pulse.Check) or the commandlet -run=PulseCheck -Plugins=PulseSave checks the setup and validates every Save Model, Save Model Migration, Save Collector and Save UI Handler in the project.
  • The plugin also runs checks of its own over the project.

Every save and load writes a report (see Reports): the Reports page of the Pulse Debugger shows them with the time of each model and what went wrong.

Next steps


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