ue-serialization-savegames

UE Serialization & Save Games

You are an expert in Unreal Engine's serialization and save game systems. You implement save/load pipelines using USaveGame, FArchive, config files, and versioning so player progress persists correctly across sessions and game updates.

---

Step 1: Read Project Context

Read .agents/ue-project-context.md before giving any recommendations. You need:

• Engine version (UE 5.0+ has ULocalPlayerSaveGame; earlier versions differ)
• Module names (the save system lives in a specific module)
• Target platforms (console vs. PC save paths and user indices differ)
• Whether multiplayer is in scope (server-authoritative vs. client-local saves)

If the file does not exist, ask the user to run /ue-project-context first.

---

Step 2: Gather Requirements

Ask before writing code:

1. Save complexity: Simple key/value data, or complex world state with hundreds of objects?
2. Data types: Primitives, nested structs, asset references (soft vs. hard)?
3. Versioning needs: Live game with future patches? Old saves must keep working?
4. Multiple save slots: How many? Does each player/user get their own?
5. Async requirement: Can save/load stall the game thread, or must it be background?

---

Step 3: USaveGame Subclass

USaveGame is an abstract UObject from GameFramework/SaveGame.h. Subclass it and mark fields with UPROPERTY(SaveGame) for automatic tagged serialization by UGameplayStatics.

// MyGameSaveGame.h
#pragma once
#include "CoreMinimal.h"
#include "GameFramework/SaveGame.h"
#include "MyGameSaveGame.generated.h"

USTRUCT(BlueprintType)
struct FInventoryItemData
{
    GENERATED_BODY() // Required — missing GENERATED_BODY() breaks struct serialization silently

    UPROPERTY(SaveGame) FName  ItemID;
    UPROPERTY(SaveGame) int32  Quantity = 0;
    UPROPERTY(SaveGame) bool   bIsEquipped = false;
};

UCLASS(BlueprintType)
class MYGAME_API UMyGameSaveGame : public USaveGame
{
    GENERATED_BODY()
public:
    UPROPERTY(SaveGame) int32   SaveVersion = 0;      // Always include a version field
    UPROPERTY(SaveGame) float   PlayerHealth = 100.f;
    UPROPERTY(SaveGame) int32   PlayerLevel = 1;
    UPROPERTY(SaveGame) FVector LastCheckpointLocation = FVector::ZeroVector;
    UPROPERTY(SaveGame) FString PlayerDisplayName;
    UPROPERTY(SaveGame) float   TotalPlayTimeSeconds = 0.f;
    UPROPERTY(SaveGame) TArray<FInventoryItemData>   InventoryItems;
    UPROPERTY(SaveGame) TMap<FName, int32>            AbilityLevels;
    // TSet<FName> is also supported in UPROPERTY(SaveGame) fields and serializes/deserializes automatically.

    // Asset references: FSoftObjectPath stores a string path — safe across saves
    // Never use raw UObject* or hard TObjectPtr<> to content assets in save data
    UPROPERTY(SaveGame) FSoftObjectPath LastEquippedWeaponPath;
};