Save & Load

Table of Contents

  1. Overview
  2. Data Structures
    1. FPulseQuestSaveGame
    2. FPulseQuestSaveGameView
    3. Byte helpers
  3. IPulseQuestSaveInterface
    1. State structs (C++)
    2. Own objects
  4. Saving
  5. Loading
    1. FPulseQuestManagerLoadParams
  6. Blueprint (async nodes)
  7. Versioning

Overview

A quest manager saves into a FPulseQuestSaveGame and loads from it. PulseQuest does not write files: store the save game in your own USaveGame, as bytes in any save system, or use the PulseSave integration.

What is saved:

Object Save id Load priority Load type
UPulseQuestManagerData (history, story flags, tracked quest) Pulse.Quest.Save.ManagerData 150 Load existing
UPulseQuestDirector Pulse.Quest.Save.Director 100 Load existing
UPulseQuestData of every running quest (run state: flags, owner, StateTree state, objectives) quest tag 0 Create new (not saved with PQF_NoSave)
Objectives of a quest (progress, target, own state) <quest tag>::<objective save id> – Saved and loaded by their quest data
Objects added with AddSaveObject their own their own their own

The state of PulseQuest’s own objects is written as versioned state structs (StateBytes of the record); the variables with the SaveGame flag of your subclasses are written next to it (Bytes). Save and load only run on the authority of a replicated manager.


Data Structures

FPulseQuestSaveGame

A Blueprint type that holds the active quest tags and one record per saved object. It is a handle: copies share the same data. It can be a SaveGame variable of a USaveGame.

C++ Description
GetActiveQuests() Quests that were active when saving
GetSaveRecords() / GetSaveRecord(Id) Saved objects
Serialize(FArchive&) Reads or writes the save game. Data of a newer PULSE_QUEST_SAVE_GAME_VERSION is refused
Reset() Clears it
AssignContentFrom(Other) Replaces the content (of all copies) with the content of another save game

FPulseQuestSaveGameView

A weak reference to a save game. The manager functions take a view; Blueprint converts automatically (VIEW, PIN). Is Valid Quest Save checks a view. The quest manager keeps the save game alive while a save or load runs.

Byte helpers

Quest Save Game to Bytes / Quest Save Game from Bytes (UPulseQuestSaveUtils) convert a save game to a byte array and back.

Blueprint: Store a quest save game as bytes

  1. Quest Save Game to Bytes (Save Game) → Out Bytes → store them in your own save system.
  2. Quest Save Game from Bytes (Bytes) → Out Save Game → Load Quest Manager Async. False = no data or written by a newer PulseQuest version.

IPulseQuestSaveInterface

Implemented by every object the manager saves. All functions are Blueprint native events:

Function Description
GetUniqueSaveIdentifier Identifier of the record. Unique within the manager
GetSaveLoadType None (not saved), CreateNew (a new object of the saved class is created on load) or LoadExisting (loaded into the existing object)
GetLoadPriority Higher priorities are loaded first
PreSaveToSaveGame / PostSaveToSaveGame Around writing the SaveGame variables
PreLoadFromSaveGame / PostLoadFromSaveGame Around reading the SaveGame variables

Objectives don’t implement the interface; they have Pre Save to Save Game, Post Save to Save Game, Pre Load Objective and Post Load Objective (see Objectives).

State structs (C++)

Three C++ functions of the interface save the state of an object as a versioned struct instead of SaveGame variables. PulseQuest calls them through Cast<IPulseQuestSaveInterface>; Blueprint implementers have no native interface and keep the old path (all their SaveGame variables, class path, class check).

Function Description
SaveQuestState(OutStruct, OutBytes) Writes the state struct as versioned bytes (Pulse::Serialization). Default: no state
ReadQuestState(Record, Params, OutState, OutReport) Reads the state of a record without applying it, also from records of older versions. Called on the object (LoadExisting) or on the class default object (CreateNew). False refuses the load
ApplyQuestState(State) Applies the read state in one step and fires the change events afterwards

FPulseQuestObjectSave::LoadToObject does all three steps for own objects. Pulse::Quest::Save (Quest/Save/PulseQuestSaveState.h) has helpers for tools: HasSaveGameProperties, FindRecordStateStruct, ReadRecordState.

Own objects

Objects that should be saved with the manager implement the interface with load type LoadExisting, use the manager as outer and are added with AddSaveObject.

Blueprint: Save an own object with the quest manager

  1. Create an object Blueprint (Outer = the quest manager) that implements Pulse Quest Save Interface.
  2. Implement Get Unique Save Identifier (a fixed name) and Get Save Load Type = Load Existing.
  3. Mark the variables to save with the SaveGame flag.
  4. Add Save Object (Target = quest manager, Object = your object) once, e.g. on begin play.

Saving

FPulseQuestSaveGame SaveGame; // keep it, e.g. in your USaveGame
QuestManager->OnSavedEvent().AddLambda([](const TScriptInterface<IPulseQuestManagerInterface>&, bool bSuccess) { /* ... */ });
QuestManager->SaveQuestManager(SaveGame, /*bSaveAsync*/ true);
  • bSaveAsync = true (default): the save runs at the next event queue processing; OnSavedEvent reports the result.
  • bSaveAsync = false: saves the current state immediately; the return value is the result. Quests that are still queued are not part of the save.
  • The save is written into a new save game first. Only if it succeeds the content of your save game is replaced, so a failed save keeps the previous content. Quests that already ended are not saved.
  • Returns false if a save or load is already running, the manager is not initialized or has no authority.
  • If the manager is destroyed while a save or load is queued, it finishes with failure.

Loading

FPulseQuestManagerLoadParams Params; // bReset = true
QuestManager->LoadQuestManager(SaveGame, Params);
  1. Check: the manager checks the whole save game before it changes anything: every object has its record, every class of a CreateNew record still exists, the class check (see below) passes, the saved bytes of every record can be read (they are read once into a temporary object) and every state struct can be read (not corrupt, not written by a newer version). If anything fails, the load ends here: the manager keeps its quests, objectives, story and director exactly as they were, and the result reports the reason.
  2. With bReset (default) the manager removes all quests and objectives.
  3. Existing objects (manager data, director, own save objects) are loaded; for CreateNew records (quest data) new objects are created. Objects are loaded in order of their load priority.
  4. The saved active quests are started again (not those with PQF_NoStartOnLoad) with their saved flags and continue with their loaded data and StateTree state. They start through StartQuest, so a quest of an asynchronous catalog waits for its definition (pending start); quests made at runtime must be registered again before the load. Quests started by the director are restarted by the director when it wants them again (see Quest Director); all others by the manager. bAllowMultipleQuests and conditions are not checked for restored quests.
  5. OnLoadedEvent reports FPulseQuestManagerLoadResult (bLoadSuccessful, LoadedObjects, Report with what was refused or tolerated); the Blueprint events get FPulseQuestManagerLoadResultInfo (bLoadSuccessful, LoadedQuests).

Without reset, records of quests that are still active are skipped.

A save keeps only the tag and the state of a quest, never the quest itself. The check reads the save in one call, so a record whose quest data class is gone is loaded into the quest data class of its quest, found with Pulse::Quest::Catalog::LoadQuestSynchronous (the only place that loads a quest at once).

FPulseQuestManagerLoadParams

Member Description
bReset Reset the manager before loading
TreatClassMismatchAsLoadFailure Default uses the project setting. If true, loading an object whose class differs from the saved class fails; if false, matching variables are loaded. The check only covers records with SaveGame bytes (variables of subclasses): a record without them loads into any class

Blueprint (async nodes)

Save Quest Manager Async and Load Quest Manager Async start the operation and fire On Success or On Failure when it is done (also for an invalid manager or save game). The manager also has the events On Quest Manager Saved / On Quest Manager Loaded.

Blueprint: Save and load a quest manager

  1. Keep a Pulse Quest Save Game variable (e.g. in your SaveGame object, with the SaveGame flag).
  2. Save Quest Manager Async (Quest Manager = the component, Save Game = the variable; the VIEW conversion is added automatically) → On Success: Save Game to Slot. On Failure: log.
  3. Loading: Load Game from Slot → cast → take the variable → Load Quest Manager Async (Params: Reset true) → On Success / On Failure.

Versioning

The save game format has a version (PULSE_QUEST_SAVE_GAME_VERSION, currently 3). Data written by a newer version is refused.

  • Version 2 changed the objective record ids from <quest tag>.<save id> to <quest tag>::<save id>, so they can’t collide with quest tags; saves of version 1 are still loaded.
  • Version 3 adds StateStructPath and StateBytes to every record: the state of PulseQuest’s objects as a versioned struct. The struct of a record comes from its path, the class path is not needed for the state. Each struct has its own Version; a newer one refuses the load in the check pass. Records without StateBytes (versions 1 and 2) are read with the old format, so older saves still load.

Records store the class path of the saved object (ObjectClassPath). The class of a CreateNew record is, in this order: the saved class while it exists (also when the quest uses another quest data class now); else, for a quest of the save game, the current QuestDataClass of the quest (its SaveGame variables are loaded tolerantly, the report gets a warning); else the load fails in the check. Objective records always load into the class their task starts. New variables keep their defaults when older saves are loaded.


Back to top

Copyright © 2026 LuQ Studios. Distributed under the MIT License.

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