Save & Load
Table of Contents
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
Quest Save Game to Bytes(Save Game) →Out Bytes→ store them in your own save system.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
- Create an object Blueprint (Outer = the quest manager) that implements
Pulse Quest Save Interface. - Implement
Get Unique Save Identifier(a fixed name) andGet Save Load Type=Load Existing. - Mark the variables to save with the
SaveGameflag. 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;OnSavedEventreports 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);
- Check: the manager checks the whole save game before it changes anything: every object has its record, every class of a
CreateNewrecord 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. - With
bReset(default) the manager removes all quests and objectives. - Existing objects (manager data, director, own save objects) are loaded; for
CreateNewrecords (quest data) new objects are created. Objects are loaded in order of their load priority. - 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 throughStartQuest, 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.bAllowMultipleQuestsand conditions are not checked for restored quests. OnLoadedEventreportsFPulseQuestManagerLoadResult(bLoadSuccessful,LoadedObjects,Reportwith what was refused or tolerated); the Blueprint events getFPulseQuestManagerLoadResultInfo(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
- Keep a
Pulse Quest Save Gamevariable (e.g. in yourSaveGameobject, with theSaveGameflag). Save Quest Manager Async(Quest Manager = the component, Save Game = the variable; theVIEWconversion is added automatically) → On Success:Save Game to Slot. On Failure: log.- Loading:
Load Game from Slot→ cast → take the variable →Load Quest Manager Async(Params:Resettrue) → 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
StateStructPathandStateBytesto 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 ownVersion; a newer one refuses the load in the check pass. Records withoutStateBytes(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.