class

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

AliasDescription
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

TypeNameDescription
static constexpr uint32_tkAutosaveSlotDefault 90.
static constexpr uint32_tkCheckpointSlotDefault 91.
static constexpr uint32_tkPointCloudSchemaSchema 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_tkJournalSchemaLayout 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_tkPlayerSchemaDefault 1.
static constexpr uint32_tkSaveObjectSchemaProgress 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

SignatureNameDescription
SaveGameManager(const SaveGameManager&) = deleteSaveGameManager

Public functions

ReturnsNameDescription
SaveGameManager&Get
floatGetAutosaveIntervalSeconds
boolGetAutosaveOnTravel
SaveGameManager&operator=
boolSaveWorldStatemetadata, 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.
boolLoadWorldState
voidSetWorldAuthorityProvider
boolIsWorldSaveAuthority
voidFlushPendingWrites
FAsyncSaveStatsGetAsyncSaveStats
boolSaveSlotDEPRECATED for games: kept for tools and the tests that pin its format.
boolLoadSlotReplace outScene with the saved state.
boolDeleteSlot
boolHasSlot
std::stringSanitizeObjectSlotName
boolSaveGameObject
MSaveGame*LoadGameObjectA 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.
boolLoadGameObjectIntoReads the slot into an object the caller already has; false leaves it as it was.
std::stringReadGameObjectClass
boolHasGameObject
boolDeleteGameObject
std::vector<std::string>EnumerateGameObjects
voidSetLocalUserKeyProgress 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::stringGetLocalUserKey
std::filesystem::pathGetUserSaveDir
std::vector<SaveSlotMetadata>EnumerateSlotsWalk the save directory and return every slot in ascending order.
boolReadMetadataRead metadata without loading any scene/custom data.
voidRegisterMigration
voidSetCurrentSchema
uint32_tGetCurrentSchema
std::filesystem::pathGetSaveDirStorage location
voidSetSaveDirOverride
boolIsCloudAvailableSteam Cloud Optional.
boolUploadSlotToCloud
boolDownloadSlotFromCloud
std::vector<uint32_t>EnumerateCloudSlotsLists slot indices that exist in Steam Cloud (may differ from local slots — designer can manually sync a missing local from cloud).

Function details

SaveGameManager

C++
SaveGameManager(const SaveGameManager&) = delete

Get

C++
static SaveGameManager& Get()

GetAutosaveIntervalSeconds

C++
static float GetAutosaveIntervalSeconds()

GetAutosaveOnTravel

C++
static bool GetAutosaveOnTravel()

operator=

C++
SaveGameManager& operator=(const SaveGameManager&) = delete

SaveWorldState

C++
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

C++
bool LoadWorldState(uint32_t slot, Scene* scene)

SetWorldAuthorityProvider

C++
static void SetWorldAuthorityProvider(FWorldAuthorityFn provider)

IsWorldSaveAuthority

C++
static bool IsWorldSaveAuthority()

FlushPendingWrites

C++
void FlushPendingWrites()

GetAsyncSaveStats

C++
FAsyncSaveStats GetAsyncSaveStats() const

SaveSlot

C++
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

C++
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

C++
bool DeleteSlot(uint32_t slot)

HasSlot

C++
bool HasSlot(uint32_t slot) const

SanitizeObjectSlotName

C++
static std::string SanitizeObjectSlotName(const std::string& slotName)

SaveGameObject

C++
bool SaveGameObject(const std::string& slotName, const MSaveGame& object)

LoadGameObject

C++
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

C++
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

C++
std::string ReadGameObjectClass(const std::string& slotName) const

HasGameObject

C++
bool HasGameObject(const std::string& slotName) const

DeleteGameObject

C++
bool DeleteGameObject(const std::string& slotName)

EnumerateGameObjects

C++
std::vector<std::string> EnumerateGameObjects() const

SetLocalUserKey

C++
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

C++
std::string GetLocalUserKey() const

GetUserSaveDir

C++
std::filesystem::path GetUserSaveDir() const

EnumerateSlots

C++
std::vector<SaveSlotMetadata> EnumerateSlots() const

Walk the save directory and return every slot in ascending order. Reads metadata only (fast) — does not deserialize the scene blob.

ReadMetadata

C++
bool ReadMetadata(uint32_t slot, SaveSlotMetadata& outMetadata) const

Read metadata without loading any scene/custom data.

RegisterMigration

C++
void RegisterMigration(uint32_t fromVersion, uint32_t toVersion, Migrator migrator)

SetCurrentSchema

C++
void SetCurrentSchema(uint32_t v)

GetCurrentSchema

C++
uint32_t GetCurrentSchema() const

GetSaveDir

C++
std::filesystem::path GetSaveDir() const

Storage location

SetSaveDirOverride

C++
void SetSaveDirOverride(const std::filesystem::path& dir)

IsCloudAvailable

C++
bool IsCloudAvailable() const

Steam 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

C++
bool UploadSlotToCloud(uint32_t slot)

DownloadSlotFromCloud

C++
bool DownloadSlotFromCloud(uint32_t slot, bool overwriteNewerLocal = false)

EnumerateCloudSlots

C++
std::vector<uint32_t> EnumerateCloudSlots() const

Lists slot indices that exist in Steam Cloud (may differ from local slots — designer can manually sync a missing local from cloud).

Generated from SaveGame/SaveGame.h via game.json · Nov 5, 2026Version 1.0.0