SaveGameManager
Owns save slots on disk plus a migration registry so titles that ship updates can promote old saves without breaking compatibility.
- Module
- Game
- Header
#include "SaveGame/SaveGame.h"- Namespace
Mowo
File layout (per slot): {save_dir}/slot_{NN}.mwsave — MDF document, see SaveGame.cpp {save_dir}/slot_{NN}.png — optional screenshot {save_dir}/slot_{NN}_cloud_{E}_g{G}.mpcl — one scanned point cloud per owning entity and save generation, see below
save_dir defaults to FPaths::UserSaveGamesDir() — <Product>/Saved/SaveGames under the per-user state root. A packaged game writes there directly; the editor/PIE adds a per-project subfolder under the engine root. Apps with multiple branches or per-user-profile saves can override via SetSaveDirOverride().
Type aliases
| Alias | Description |
|---|---|
using FWorldAuthorityFn = bool (*)() | Co-op: the world belongs to whoever is authoritative for it. A client that autosaved its replicated copy of the host's world, or loaded one, diverged from the host the moment it did — so SaveWorldState and LoadWorldState refuse off-authority, whatever called them (autosave, travel, a checkpoint, a Visual Script graph). Personal progress belongs in a progress object (SaveGameObject), which every player keeps. The default answer is "not a client of a net session"; a game with other rules (a dedicated server's own policy) installs a provider. |
using Migrator = std::function<void(MdfNode& root)> | Migration A migrator receives the loaded SaveGame ROOT node (i.e. the whole document tree) and mutates it in-place to upgrade fromVersion → toVersion. The manager applies migrations in chain order until the schema matches GetCurrentSchema(). Example: sg.RegisterMigration(1, 2, [](MdfNode& root){ auto* custom = root.FindChild("Custom"); if (!custom) return; if (custom->HasProperty("gold")) { auto v = custom->GetProperty("gold"); custom->RemoveProperty("gold"); auto& inv = custom->FindOrAddChild("Inventory"); inv.SetProperty("gold", v); |
Properties
| Type | Name | Description |
|---|---|---|
static constexpr uint32_t | kAutosaveSlot | Default 90. |
static constexpr uint32_t | kCheckpointSlot | Default 91. |
static constexpr uint32_t | kPointCloudSchema | Schema of the slot's PointClouds block. A scanned world is millions of points — orders of magnitude past what belongs inside the save document — so each cloud is written as its own .mpcl sidecar and the document records only the entity → file mapping. Without it a save slot restores the world with everything the player revealed erased, which in a scanner game is the whole save. Every save writes its sidecars under a fresh generation and records the generation and each sidecar's CRC in the document. Overwriting one set of names in place let a crash, a failed async write or a fall back to .bak pair a document with another save's clouds. A sidecar is deleted only after the new document is renamed into place, and only when neither it nor the backup names it and no newer save still waiting to land wrote it. Default 1. |
static constexpr uint32_t | kJournalSchema | Layout versions of the engine-owned blocks of a world-state slot. The root schema_version is the game's (SetCurrentSchema); these move only with the engine, so a game bump and an engine change cannot be confused. Default 1. |
static constexpr uint32_t | kPlayerSchema | Default 1. |
static constexpr uint32_t | kSaveObjectSchema | Progress objects — UE's SaveGameToSlot. An MSaveGame goes to a NAMED slot, <name>.msavegame beside the numbered slots, with its own .bak and schema, and never carries the scene. The name keeps letters, digits, '-' and '_' (anything else becomes '_', at most 64 characters), so "Profile 1" and "Profile_1" are the same slot. Default 1. |
Constructors
| Signature | Name | Description |
|---|---|---|
SaveGameManager(const SaveGameManager&) = delete | SaveGameManager |
Public functions
| Returns | Name | Description |
|---|---|---|
SaveGameManager& | Get | |
float | GetAutosaveIntervalSeconds | |
bool | GetAutosaveOnTravel | |
SaveGameManager& | operator= | |
bool | SaveWorldState | metadata, when given, supplies the designer-facing fields (player name, play time, scene title) the slot browser shows; screenshotPNG becomes the slot's thumbnail, as with SaveSlot. |
bool | LoadWorldState | |
void | SetWorldAuthorityProvider | |
bool | IsWorldSaveAuthority | |
void | FlushPendingWrites | |
FAsyncSaveStats | GetAsyncSaveStats | |
bool | SaveSlot | DEPRECATED for games: kept for tools and the tests that pin its format. |
bool | LoadSlot | Replace outScene with the saved state. |
bool | DeleteSlot | |
bool | HasSlot | |
std::string | SanitizeObjectSlotName | |
bool | SaveGameObject | |
MSaveGame* | LoadGameObject | A new object of the class the slot recorded (MSaveGame when that class is gone or is not a save game), or nullptr when the slot is missing, unreadable or from a newer build. |
bool | LoadGameObjectInto | Reads the slot into an object the caller already has; false leaves it as it was. |
std::string | ReadGameObjectClass | |
bool | HasGameObject | |
bool | DeleteGameObject | |
std::vector<std::string> | EnumerateGameObjects | |
void | SetLocalUserKey | Progress objects are per player (UE's ULocalPlayerSaveGame): they live under <save dir>/Users/<user key>/, keyed by the platform user id from the online service, or by a key the game sets for its own profiles. |
std::string | GetLocalUserKey | |
std::filesystem::path | GetUserSaveDir | |
std::vector<SaveSlotMetadata> | EnumerateSlots | Walk the save directory and return every slot in ascending order. |
bool | ReadMetadata | Read metadata without loading any scene/custom data. |
void | RegisterMigration | |
void | SetCurrentSchema | |
uint32_t | GetCurrentSchema | |
std::filesystem::path | GetSaveDir | Storage location |
void | SetSaveDirOverride | |
bool | IsCloudAvailable | Steam Cloud Optional. |
bool | UploadSlotToCloud | |
bool | DownloadSlotFromCloud | |
std::vector<uint32_t> | EnumerateCloudSlots | Lists slot indices that exist in Steam Cloud (may differ from local slots — designer can manually sync a missing local from cloud). |
Function details
SaveGameManager
SaveGameManager(const SaveGameManager&) = deleteGet
static SaveGameManager& Get()GetAutosaveIntervalSeconds
static float GetAutosaveIntervalSeconds()GetAutosaveOnTravel
static bool GetAutosaveOnTravel()operator=
SaveGameManager& operator=(const SaveGameManager&) = deleteSaveWorldState
bool SaveWorldState(uint32_t slot, Scene* scene, bool asyncWrite = true, const SaveSlotMetadata* metadata = nullptr, const std::vector<uint8_t>* screenshotPNG = nullptr)metadata, when given, supplies the designer-facing fields (player name, play time, scene title) the slot browser shows; screenshotPNG becomes the slot's thumbnail, as with SaveSlot.
LoadWorldState
bool LoadWorldState(uint32_t slot, Scene* scene)SetWorldAuthorityProvider
static void SetWorldAuthorityProvider(FWorldAuthorityFn provider)IsWorldSaveAuthority
static bool IsWorldSaveAuthority()FlushPendingWrites
void FlushPendingWrites()GetAsyncSaveStats
FAsyncSaveStats GetAsyncSaveStats() constSaveSlot
bool SaveSlot(uint32_t slot, Scene* scene, const SaveData& custom, const SaveSlotMetadata& metadata, const std::vector<uint8_t>& screenshotPNG = {})DEPRECATED for games: kept for tools and the tests that pin its format. It writes the whole scene into the slot, so LoadSlot replaces the level with the one the save was taken on and a patched level loses to an old save. A game saves the world with SaveWorldState (a delta over the packaged level) and its progress with SaveGameObject. Snapshot the scene + custom data + metadata into slot N. Returns false on I/O failure. metadata.slotIndex / timestampUnix / schemaVersion are filled by the manager — callers only supply the designer-facing fields (playerName, sceneName, playTimeSeconds). screenshotPNG, if non-empty, gets written as a sidecar file slot_NN.png next to the .mwsave. The caller is responsible for capturing + encoding (we deliberately don't pull the renderer into the SaveGame module — runtime games + editor have different capture paths).
LoadSlot
bool LoadSlot(uint32_t slot, Scene* outScene, SaveData* outCustom = nullptr, SaveSlotMetadata* outMetadata = nullptr)Replace outScene with the saved state. Optional out parameters receive the metadata + custom blob. Returns false if the slot is missing, corrupt, or a migration was registered but didn't bring the schema forward to GetCurrentSchema.
DeleteSlot
bool DeleteSlot(uint32_t slot)HasSlot
bool HasSlot(uint32_t slot) constSanitizeObjectSlotName
static std::string SanitizeObjectSlotName(const std::string& slotName)SaveGameObject
bool SaveGameObject(const std::string& slotName, const MSaveGame& object)LoadGameObject
MSaveGame* LoadGameObject(const std::string& slotName)A new object of the class the slot recorded (MSaveGame when that class is gone or is not a save game), or nullptr when the slot is missing, unreadable or from a newer build. The caller owns it and roots it (FMObjectArray::AddRoot) for as long as it keeps it.
LoadGameObjectInto
bool LoadGameObjectInto(const std::string& slotName, MSaveGame& object)Reads the slot into an object the caller already has; false leaves it as it was.
ReadGameObjectClass
std::string ReadGameObjectClass(const std::string& slotName) constHasGameObject
bool HasGameObject(const std::string& slotName) constDeleteGameObject
bool DeleteGameObject(const std::string& slotName)EnumerateGameObjects
std::vector<std::string> EnumerateGameObjects() constSetLocalUserKey
void SetLocalUserKey(const std::string& userKey)Progress objects are per player (UE's ULocalPlayerSaveGame): they live under <save dir>/Users/<user key>/, keyed by the platform user id from the online service, or by a key the game sets for its own profiles. With no user (offline, a headless tool) they stay in the save dir itself. A slot written there before profiles existed is still read, and the next save moves it into the player's folder.
GetLocalUserKey
std::string GetLocalUserKey() constGetUserSaveDir
std::filesystem::path GetUserSaveDir() constEnumerateSlots
std::vector<SaveSlotMetadata> EnumerateSlots() constWalk the save directory and return every slot in ascending order. Reads metadata only (fast) — does not deserialize the scene blob.
ReadMetadata
bool ReadMetadata(uint32_t slot, SaveSlotMetadata& outMetadata) constRead metadata without loading any scene/custom data.
RegisterMigration
void RegisterMigration(uint32_t fromVersion, uint32_t toVersion, Migrator migrator)SetCurrentSchema
void SetCurrentSchema(uint32_t v)GetCurrentSchema
uint32_t GetCurrentSchema() constGetSaveDir
std::filesystem::path GetSaveDir() constStorage location
SetSaveDirOverride
void SetSaveDirOverride(const std::filesystem::path& dir)IsCloudAvailable
bool IsCloudAvailable() constSteam Cloud Optional. Available only when the engine was built with Steam support AND Steam initialized successfully at startup. All methods return false otherwise so calling code can blindly try and gracefully degrade. A slot goes up as a set: its scan sidecars, its thumbnail, the document, and last a manifest (slot_NN_manifest.mdfb) naming every file with its size and CRC plus the save's timestamp and play time. A download stages every file, checks it against the manifest and only then writes them (sidecars, then the document through the backup rule). It refuses when the local slot is newer than the cloud copy unless overwriteNewerLocal.
UploadSlotToCloud
bool UploadSlotToCloud(uint32_t slot)DownloadSlotFromCloud
bool DownloadSlotFromCloud(uint32_t slot, bool overwriteNewerLocal = false)EnumerateCloudSlots
std::vector<uint32_t> EnumerateCloudSlots() constLists slot indices that exist in Steam Cloud (may differ from local slots — designer can manually sync a missing local from cloud).