/ue-serialization-savegames

UE Serialization & Save Games

Target engine: UE 5.8. APIs below are verified against the 5.8 headers; older forms are listed under "Deprecated — do not use".

This skill covers persisting game state: USaveGame objects through UGameplayStatics, the platform ISaveGameSystem, FArchive binary serialization, UPROPERTY(SaveGame) actor snapshots, save versioning, and config/settings storage. Build.cs modules: Core, CoreUObject, Engine; add DeveloperSettings to PublicDependencyModuleNames for UDeveloperSettings, and Json + JsonUtilities to PrivateDependencyModuleNames for FJsonObjectConverter.

Context

Read .agents/ue-project-context.md if it exists (module names, conventions, enabled plugins, GAS/networking setup). Do not stop if it is missing.

Identify the area from the request and the codebase. Ask only when two plausible readings would produce different code.

USaveGame and the Slot API

USaveGame is an abstract UObject declared in GameFramework/SaveGame.h:23. Subclass it, add UPROPERTY fields, and route everything through UGameplayStatics.

UGameplayStatics::SaveGameToSlot writes every non-transient UPROPERTY — it does not filter on the SaveGame flag (Kismet/GameplayStatics.h:1159). Mark fields Transient to exclude them. The SaveGame specifier only matters for archives with ArIsSaveGame set — see Actor State.

// MySaveGame.h
#pragma once

#include "CoreMinimal.h"
#include "GameFramework/SaveGame.h"
#include "UObject/SoftObjectPath.h"
#include "MySaveGame.generated.h"

USTRUCT(BlueprintType)
struct FMyInventoryItem
{
    GENERATED_BODY()

    UPROPERTY(SaveGame) FName ItemId;
    UPROPERTY(SaveGame) int32 Quantity = 0;
};

UCLASS(BlueprintType)
class MYGAME_API UMySaveGame : public USaveGame
{
    GENERATED_BODY()

public:
    UPROPERTY(SaveGame) int32 SaveVersion = 0;   // bump alongside MySaveStage::Latest
    UPROPERTY(SaveGame) float PlayerHealth = 100.f;
    UPROPERTY(SaveGame) FVector LastCheckpoint = FVector::ZeroVector;
    UPROPERTY(SaveGame) TArray<FMyInventoryItem> InventoryItems;
    UPROPERTY(SaveGame) TMap<FName, int32> AbilityLevels;

    /** Store asset references as paths; a hard pointer cannot round-trip through a file. */
    UPROPERTY(SaveGame) FSoftObjectPath LastEquippedWeapon;

    /** Excluded from SaveGameToSlot because it is Transient. */
    UPROPERTY(Transient) float RuntimeOnlyScratch = 0.f;
};

Slot functions, all static on UGameplayStatics (Kismet/GameplayStatics.h):

Async Save and Load

The async entry points take plain (non-dynamic) delegates, so the bound function must not be a UFUNCTION:

• DECLARE_DELEGATE_ThreeParams(FAsyncSaveGameToSlotDelegate, const FString&, const int32, bool) (GameplayStatics.h:44)
• DECLARE_DELEGATE_ThreeParams(FAsyncLoadGameFromSlotDelegate, const FString&, const int32, USaveGame*) (GameplayStatics.h:47)

// MySaveSubsystem.h
#pragma once

#include "CoreMinimal.h"
#include "Subsystems/GameInstanceSubsystem.h"
#include "MySaveSubsystem.generated.h"

class UMySaveGame; class USaveGame;

UCLASS()
class MYGAME_API UMySaveSubsystem : public UGameInstanceSubsystem
{
    GENERATED_BODY()

public:
    void RequestSave(float PlayerHealth);
    void RequestLoad();

private:
    void HandleSaveComplete(const FString& SlotName, const int32 UserIndex, bool bSuccess);
    void HandleLoadComplete(const FString& SlotName, const int32 UserIndex, USaveGame* LoadedSave);
    void RunMigrations(UMySaveGame* Save);

    UPROPERTY()
    TObjectPtr<UMySaveGame> CurrentSave = nullptr;
    bool bSaveInProgress = false;
};

// MySaveSubsystem.cpp
#include "MySaveSubsystem.h"
#include "MySaveGame.h"
#include "Kismet/GameplayStatics.h"

static const FString GMySaveSlot = TEXT("MainSave");
static constexpr int32 GMyUserIndex = 0; // see ULocalPlayerSaveGame for per-user consoles

void UMySaveSubsystem::RequestSave(float PlayerHealth)
{
    if (bSaveInProgress) { return; } // overlapping writes to one slot can truncate the file
    if (!CurrentSave)
    {
        CurrentSave = Cast<UMySaveGame>(
            UGameplayStatics::CreateSaveGameObject(UMySaveGame::StaticClass()));
    }
    if (!CurrentSave) { return; }
    CurrentSave->PlayerHealth = PlayerHealth;
    CurrentSave->SaveVersion = MySaveStage::Latest; // in-memory data is current; see Versioning

    // Synchronous form blocks the game thread until the platform write finishes:
    // UGameplayStatics::SaveGameToSlot(CurrentSave, GMySaveSlot, GMyUserIndex);
    bSaveInProgress = true;
    UGameplayStatics::AsyncSaveGameToSlot(CurrentSave, GMySaveSlot, GMyUserIndex,
        FAsyncSaveGameToSlotDelegate::CreateUObject(this, &UMySaveSubsystem::HandleSaveComplete));
}

void UMySaveSubsystem::HandleSaveComplete(const FString& SlotName, const int32 UserIndex, bool bSuccess)
{
    bSaveInProgress = false;
    UE_LOG(LogMyGame, Log, TEXT("Save '%s' (user %d) ok=%d"), *SlotName, UserIndex, bSuccess ? 1 : 0);
}

void UMySaveSubsystem::RequestLoad()
{
    UGameplayStatics::AsyncLoadGameFromSlot(GMySaveSlot, GMyUserIndex,
        FAsyncLoadGameFromSlotDelegate::CreateUObject(this, &UMySaveSubsystem::HandleLoadComplete));
}

void UMySaveSubsystem::HandleLoadComplete(const FString& SlotName, const int32 UserIndex, USaveGame* LoadedSave)
{
    CurrentSave = Cast<UMySaveGame>(LoadedSave); // null when the slot is missing or unreadable
    if (!CurrentSave)
    {
        CurrentSave = Cast<UMySaveGame>(
            UGameplayStatics::CreateSaveGameObject(UMySaveGame::StaticClass()));
        return;
    }
    RunMigrations(CurrentSave);
}

CreateLambda works when there is no owning UObject to keep alive; capture by value, because the call returns before the write finishes. The delegate runs on the game thread (check(IsInGameThread()), GameplayStatics.cpp:2417), and runs synchronously inside the call when the slot name is empty or serialization fails (:2424). SaveGameToMemory itself always runs on the game thread (:2410); only the platform write is async.

ULocalPlayerSaveGame

ULocalPlayerSaveGame is declared in GameFramework/SaveGame.h:47 (there is no LocalPlayerSaveGame.h). It binds a save to one local player, resolves the platform user index automatically, and provides versioning hooks for subclasses to override. GetLatestDataVersion() returns the current schema number. HandlePostLoad() compares it with GetSavedDataVersion(), which is the value stored at the last save, and migrates old data. HandlePreSave() sanitises fields before they are written, and HandlePostSave(bool bSuccess) is where save results arrive. Call Super:: in each. A complete subclass with a two-step migration is in references/save-system-architecture.md.

The native delegate overload takes a ULocalPlayer*; the APlayerController* overload takes the dynamic FOnLocalPlayerSaveGameLoaded instead.

// Synchronous: returns null only for invalid parameters, otherwise creates a fresh instance.
UMyLocalPlayerSave* Save = Cast<UMyLocalPlayerSave>(
    ULocalPlayerSaveGame::LoadOrCreateSaveGameForLocalPlayer(
        UMyLocalPlayerSave::StaticClass(), PlayerController, TEXT("PlayerSlot0")));

// Asynchronous, native delegate: pass the ULocalPlayer, not the controller.
const ULocalPlayer* LocalPlayer = PlayerController ? PlayerController->GetLocalPlayer() : nullptr;
const bool bScheduled = ULocalPlayerSaveGame::AsyncLoadOrCreateSaveGameForLocalPlayer(
    UMyLocalPlayerSave::StaticClass(), LocalPlayer, TEXT("PlayerSlot0"),
    FOnLocalPlayerSaveGameLoadedNative::CreateUObject(this, &AMyPlayerController::HandleSaveLoaded));

// Writing back; results arrive through HandlePostSave, not the return value.
Save->AsyncSaveGameToSlotForLocalPlayer(); // bool: the save was requested
Save->SaveGameToSlotForLocalPlayer();      // synchronous

Other verified members (GameFramework/SaveGame.h:50-224): CreateNewSaveGameForLocalPlayer, GetLocalPlayerController, GetLocalPlayer, SetLocalPlayer, GetPlatformUserId, GetPlatformUserIndex, GetSaveSlotName, SetSaveSlotName, GetSavedDataVersion, GetInvalidDataVersion, WasLoaded, IsSaveInProgress, WasLastSaveSuccessful, WasSaveRequested, InitializeSaveGame, ResetToDefault.

FArchive and Binary Serialization

FArchive (Serialization/Archive.h) is bidirectional: one operator<< body handles both read and write.

Ar.IsLoading()                 // Archive.h:272
Ar.IsSaving()                  // Archive.h:284
Ar.IsError()                   // Archive.h:398 — check after every block
Ar.Tell()                      // Archive.h:185 — int64 position
Ar.IsSaveGame()                // Archive.h:659 — reads the ArIsSaveGame field
Ar.ArIsSaveGame = true;        // Archive.h:942 — public bitfield, no setter exists
Ar.UsingCustomVersion(Guid);   // Archive.h:2006
Ar.CustomVer(Guid);            // Archive.h:269 — int32

FMemoryWriter / FMemoryReader move bytes in and out of a TArray<uint8>. Both take bIsPersistent (MemoryWriter.h:26, MemoryReader.h:52); pass true so the archive behaves like an on-disk write rather than a transient in-memory one.

#include "Serialization/MemoryWriter.h"
#include "Serialization/MemoryReader.h"

bool UMyObject::WriteBlob(TArray<uint8>& OutBytes)
{
    FMemoryWriter Writer(OutBytes, /*bIsPersistent=*/true);
    int32 Magic = 0x4D595347;   // 'MYSG'
    int32 Version = 2;
    Writer << Magic << Version << BinaryBlob;
    return !Writer.IsError();
}

bool UMyObject::ReadBlob(const TArray<uint8>& InBytes)
{
    FMemoryReader Reader(InBytes, /*bIsPersistent=*/true);
    int32 Magic = 0;
    int32 Version = 0;
    Reader << Magic << Version;
    if (Reader.IsError() || Magic != 0x4D595347 || Version < 1) { return false; }
    Reader << BinaryBlob;
    return !Reader.IsError();
}

Overriding virtual void UMyObject::Serialize(FArchive& Ar) gives byte-level control on a UObject; call Super::Serialize(Ar) first so the tagged property block is written. Define a free FArchive& operator<<(FArchive& Ar, FMyCustomData& Data) to make a plain struct archive-serializable. FBufferArchive (Serialization/BufferArchive.h:47) derives from both the memory writer and TArray<uint8>, so the archive is the buffer.

Actor State with UPROPERTY(SaveGame)

UPROPERTY(SaveGame) sets CPF_SaveGame (UObject/ObjectMacros.h:458, specifier at :1194), which is only honoured by archives with ArIsSaveGame set. That is how you snapshot live actors: wrap a memory archive in FObjectAndNameAsStringProxyArchive (Serialization/ObjectAndNameAsStringProxyArchive.h:21) so UObject and FName references survive as strings instead of load-order-dependent indices.

// MyActorRecord.cpp — include MemoryWriter.h, MemoryReader.h,
// ObjectAndNameAsStringProxyArchive.h and GameFramework/Actor.h.
void FMyActorRecord::SaveActor(AActor* Actor)
{
    if (!Actor) { return; }
    ActorClass = Actor->GetClass();
    ActorTransform = Actor->GetActorTransform();
    ByteData.Reset();

    FMemoryWriter MemWriter(ByteData, /*bIsPersistent=*/true);
    FObjectAndNameAsStringProxyArchive Ar(MemWriter, /*bInLoadIfFindFails=*/true);
    Ar.ArIsSaveGame = true; // only UPROPERTY(SaveGame) fields are written
    Actor->Serialize(Ar);
}

void FMyActorRecord::RestoreActor(AActor* Actor) const
{
    if (!Actor || ByteData.Num() == 0) { return; }
    Actor->SetActorTransform(ActorTransform);

    FMemoryReader MemReader(ByteData, /*bIsPersistent=*/true);
    FObjectAndNameAsStringProxyArchive Ar(MemReader, /*bInLoadIfFindFails=*/true);
    Ar.ArIsSaveGame = true;
    Actor->Serialize(Ar);
}

FObjectAndNameAsStringProxyArchive also exposes bResolveRedirectors and bResolveCoreRedirects (both default false); set them when assets may have been renamed between builds. FNameAsStringProxyArchive (Serialization/NameAsStringProxyArchive.h:11) handles FName only. Full world-capture pipeline, per-actor FGuid identity, the actor save interface and respawn ordering: Save system architecture.

USTRUCT Custom Serialization

A USTRUCT hook is bool Serialize(FArchive& Ar) plus a TStructOpsTypeTraits specialization with WithSerializer = true. Without the traits specialization the function is never called — the engine gates on TStructOpsTypeTraits<CppStruct>::WithSerializer (UObject/Class.h:1307; trait declared in UObject/StructOpsTypeTraits.h:24). Return true to mean "fully handled; skip the default tagged-property path".

// MyStatBlock.h — include "CoreMinimal.h" then "MyStatBlock.generated.h".
USTRUCT(BlueprintType)
struct MYGAME_API FMyStatBlock
{
    GENERATED_BODY()

    UPROPERTY(SaveGame) float HP = 100.f;
    UPROPERTY(SaveGame) float Stamina = 100.f;

    bool Serialize(FArchive& Ar);
};

template<>
struct TStructOpsTypeTraits<FMyStatBlock> : public TStructOpsTypeTraitsBase2<FMyStatBlock>
{
    enum
    {
        WithSerializer = true
    };
};

// MyStatBlock.cpp — include "MyStatBlock.h" and "MySaveVersion.h".
bool FMyStatBlock::Serialize(FArchive& Ar)
{
    Ar.UsingCustomVersion(FMySaveVersion::GUID);
    if (Ar.CustomVer(FMySaveVersion::GUID) < FMySaveVersion::SplitStamina)
    {
        float LegacyHealth = 0.f; // the old layout stored a single float
        Ar << LegacyHealth;
        HP = LegacyHealth;
        Stamina = 100.f;
    }
    else
    {
        Ar << HP << Stamina;
    }
    return true;
}

Related traits on the same base (StructOpsTypeTraits.h): WithPostSerialize, WithStructuredSerializer, WithSerializeFromMismatchedTag, WithNetSerializer, WithIdentical.

Versioning

Explicit version field — the simplest option for a USaveGame written through UGameplayStatics, because the field is just another UPROPERTY:

namespace MySaveStage
{
    constexpr int32 Initial = 0, AddedInventory = 1, SoftRefForWeapon = 2, Latest = SoftRefForWeapon;
}

void UMySaveSubsystem::RunMigrations(UMySaveGame* Save)
{
    if (!Save || Save->SaveVersion == MySaveStage::Latest) { return; }
    if (Save->SaveVersion < MySaveStage::AddedInventory) { Save->InventoryItems.Reset(); }
    if (Save->SaveVersion < MySaveStage::SoftRefForWeapon) { Save->LastEquippedWeapon.Reset(); }
    Save->SaveVersion = MySaveStage::Latest; // stamp only after every step ran
}

FCustomVersion — per-archive versions (Serialization/CustomVersion.h: FCustomVersion at :39, FCustomVersionRegistration at :211). SaveGameToSlot/SaveGameToMemory write every registered custom version into the file header and restore them on load (GameplayStatics.cpp:233,207), so CustomVer works inside a USaveGame. A bare FMemoryWriter/FMemoryReader pair carries no versions: serialize Ar.GetCustomVersions() yourself (Archive.h:555,562) or CustomVer returns -1 on load.

// MySaveVersion.h — include "CoreMinimal.h" and "Misc/Guid.h".
struct FMySaveVersion
{
    enum Type { Initial = 0, AddedQuestData = 1, SplitStamina = 2, VersionPlusOne, Latest = VersionPlusOne - 1 };

    /** Generate once with FGuid::NewGuid(), then hardcode forever. */
    static const FGuid GUID;
};

// MySaveVersion.cpp — include "MySaveVersion.h" and "Serialization/CustomVersion.h".
const FGuid FMySaveVersion::GUID(0xA1B2C3D4, 0xE5F60718, 0x293A4B5C, 0x6D7E8F90);

// Registers the version with every archive for the module's lifetime.
FCustomVersionRegistration GRegisterMySaveVersion(
    FMySaveVersion::GUID, FMySaveVersion::Latest, TEXT("MySaveVersion"));

// Inside any Serialize(); UsingCustomVersion is required when saving (CustomVer asserts
// otherwise, Archive.cpp:646) and a harmless no-op when loading (Archive.cpp:631).
// CoreData and QuestData are UPROPERTY members of UMyObject.
void UMyObject::SerializeVersioned(FArchive& Ar)
{
    Ar.UsingCustomVersion(FMySaveVersion::GUID);
    const int32 Version = Ar.CustomVer(FMySaveVersion::GUID);
    Ar << CoreData;
    if (Version >= FMySaveVersion::AddedQuestData) { Ar << QuestData; }
    else if (Ar.IsLoading())                       { QuestData.Reset(); }
}

ISaveGameSystem and Platform Storage

UGameplayStatics routes through the platform's ISaveGameSystem (Engine/Public/SaveGameSystem.h:19), reached via IPlatformFeaturesModule::Get().GetSaveGameSystem() (Engine/Public/PlatformFeatures.h:41). Use it directly only for capabilities UGameplayStatics does not expose — enumerating slots, native save UI, or multi-user checks.

#include "SaveGameSystem.h"
#include "PlatformFeatures.h"

ISaveGameSystem* SaveSystem = IPlatformFeaturesModule::Get().GetSaveGameSystem();
if (!SaveSystem) { return; }
const bool bPerUser = SaveSystem->DoesSaveSystemSupportMultipleUsers();
TArray<FString> FoundSlots;
SaveSystem->GetSaveGameNames(FoundSlots, /*UserIndex=*/0);
const ISaveGameSystem::ESaveExistsResult R = SaveSystem->DoesSaveGameExistWithResult(TEXT("MainSave"), 0);

Interface members (SaveGameSystem.h:34-58): PlatformHasNativeUI, DoesSaveSystemSupportMultipleUsers, DoesSaveGameExist, DoesSaveGameExistWithResult, GetSaveGameNames, SaveGame, LoadGame, DeleteGame. ISaveGameSystem also declares the async set DoesSaveGameExistAsync, SaveGameAsync, LoadGameAsync, LoadGameIfExistsAsync, DeleteGameAsync, GetSaveGameNamesAsync and InitAsync, all keyed by FPlatformUserId (:78-97); FBaseAsyncSaveGameSystem (:178) is the helper base that implements them on UE::Tasks. Never build save paths by hand: FGenericSaveGameSystem::GetSaveGamePath (:169) is the desktop fallback only, and console and cloud backends ignore the filesystem entirely.

Config, Settings, and File Formats

Settings are a separate channel from save slots: .ini for options and tuning, USaveGame for progress.

Section [/Script/ModuleName.ClassName] maps to the class CDO; register a UGameUserSettings subclass with GameUserSettingsClassName=/Script/MyGame.MyGameUserSettings under [/Script/Engine.Engine] in DefaultEngine.ini. Compression uses FCompression::CompressMemoryBound / CompressMemory / UncompressMemory (Misc/Compression.h:73,108,143) with an FName format — NAME_Zlib, NAME_Oodle, NAME_Gzip, NAME_LZ4 (UObject/UnrealNames.inl:210-214) — and must store the uncompressed size alongside the blob; FArchiveSaveCompressedProxy(TArray<uint8>&, FName, ECompressionFlags) (Serialization/ArchiveSaveCompressedProxy.h:28, Flush() at :36) and FArchiveLoadCompressedProxy (ArchiveLoadCompressedProxy.h:22) wrap the same thing as archives. Worked UDeveloperSettings class, GConfig calls, JSON round-trip, compression, checksum (FCrc::MemCrc32, Misc/Crc.h:29) and FAES encryption code: Save system architecture.

Deprecated — do not use

Common Mistakes

Assuming UPROPERTY(SaveGame) filters SaveGameToSlot: it does not — SaveGameToSlot writes all non-transient properties (GameplayStatics.h:1159). Use Transient to exclude a field; SaveGame matters only for archives with ArIsSaveGame = true.

Serializing an actor without the proxy archive: a bare FMemoryWriter stores UObject and FName references as indices that do not survive a restart. Always wrap it in FObjectAndNameAsStringProxyArchive.

Passing an APlayerController* with the native local-player delegate: the FOnLocalPlayerSaveGameLoadedNative overload takes const ULocalPlayer*. Call PlayerController->GetLocalPlayer() first.

Getting versioning backwards: set SaveVersion = Latest only after every migration step has run (and on every save, so fresh saves are not migrated next load). Ar.UsingCustomVersion() is mandatory on the saving archive — CustomVer check()s otherwise — while on a loading archive it is a no-op and CustomVer returns the file's version, or -1 if the archive holds none (Archive.cpp:631,646-648).

Hardcoding Saved/SaveGames/*.sav paths: consoles and cloud backends never touch that directory; use UGameplayStatics or ISaveGameSystem.

Related Skills

• ue-cpp-foundations — UPROPERTY/USTRUCT specifiers, UObject lifetime, subsystem types
• ue-data-assets-tables — FSoftObjectPath, FPrimaryAssetId, async loading behind saved references
• ue-gameplay-framework — UGameInstance as the save manager host, GameMode-driven autosave points
• ue-world-level-streaming — persisting streamed-level and World Partition actor state
• ue-async-threading — running serialization or compression off the game thread
• ue-networking-replication — server-authoritative saves versus client-local profiles