UE 存档系统——SaveGame、序列化与版本迁移

一、最简单的存档#

1
UCLASS()
2
class UMySaveGame : public USaveGame {
3
    GENERATED_BODY()
4
public:
5
    UPROPERTY()
6
    int32 PlayerLevel;
7

8
    UPROPERTY()
9
    float TotalPlayTime;
10

11
    UPROPERTY()
12
    TArray<FString> CompletedQuests;
13
};
14

15
// 存档
16
UMySaveGame* SaveGame = Cast<UMySaveGame>(
17
    UGameplayStatics::CreateSaveGameObject(UMySaveGame::StaticClass()));
18
SaveGame->PlayerLevel = 10;
19
UGameplayStatics::SaveGameToSlot(SaveGame, "Slot1", 0);
20

21
// 读档
22
UMySaveGame* Loaded = Cast<UMySaveGame>(
23
    UGameplayStatics::LoadGameFromSlot("Slot1", 0));

UPROPERTY() 标记的属性自动序列化——和第 4 篇（反射与序列化）里的 FArchive 流程一模一样。SaveGameToSlot 内部走的是 FArchive → 二进制文件。

但是这太简单了。实际问题才开始。

二、存档的四个实际挑战#

1 你要存什么#

1
错误做法：
2
  把整个 UWorld 序列化 → 几 GB，加载 30 秒
3

4
正确做法：
5
  只存"差异状态"——默认值不存、临时数据不存
6
  ├── 玩家进度（等级、经验、资产）          ← 必须
7
  ├── 当前关卡、角色位置                      ← 必须
8
  ├── 已完成的任务、解锁的区域                ← 必须
9
  ├── 当前技能的冷却剩余时间                  ← 可能
10
  └── UI 的打开状态、相机的当前 FOV          ← 通常不存（恢复后重置为默认）

2 存档文件在哪里#

1
PC:     %LOCALAPPDATA%/GameName/Saved/SaveGames/
2
Console: Platform-specific save directory
3
Mobile: App sandbox document directory
4

5
每个 Slot 一个 .sav 文件

3 版本迁移——最大的坑#

你的游戏更新了，加了新属性。旧存档怎么办？

1
// v1.0 的存档
2
UCLASS()
3
class UMySaveGame : public USaveGame {
4
    UPROPERTY() int32 PlayerLevel;
5
    UPROPERTY() float TotalPlayTime;
6
};
7

8
// v1.1 加了新属性
9
UCLASS()
10
class UMySaveGame : public USaveGame {
11
    UPROPERTY() int32 PlayerLevel;
12
    UPROPERTY() float TotalPlayTime;
13
    UPROPERTY() int32 PrestigeLevel; // ← 新增！旧存档里没有
14
};

UE 的默认行为：新属性取 UPROPERTY() 的默认值。PrestigeLevel 会初始化为 0——旧存档加载不会崩溃。

但有时你需要更复杂的迁移：

1
// 手动版本管理
2
UCLASS()
3
class UMySaveGame : public USaveGame {
4
    UPROPERTY()
5
    int32 SaveVersion; // 自己维护一个版本号
6

7
    virtual void Serialize(FArchive& Ar) override {
8
        Super::Serialize(Ar);
9

10
        if (Ar.IsLoading()) {
11
            if (SaveVersion < 2) {
12
                // v1 → v2 迁移：把旧的 SeparateGold + SeparateGem 合并到 CurrencyMap
13
                CurrencyMap.Add("Gold", OldGold);
14
                CurrencyMap.Add("Gem", OldGem);
15
            }
16
            if (SaveVersion < 3) {
17
                // v2 → v3：给所有老玩家送一个补偿礼包
18
                PendingGifts.Add("MigrationGift_v3");
19
            }
20
            // 迁移完后更新版本号
21
            SaveVersion = CURRENT_SAVE_VERSION;
22
        }
23
    }
24
};

三、存档策略模式#

1 单一存档 vs 多槽位#

1
单一存档（AutoSave）：
2
  简单——每局自动覆盖，玩家不需要选 Slot
3
  适合：开放世界 RPG 的单人模式
4

5
多槽位：
6
  玩家可以手动选择存哪个位置
7
  适合：RPG、策略游戏

UE 的 SaveGameToSlot 的第三个参数 UserIndex 就是槽位编号（0 / 1 / 2…）。

2 增量存档 vs 全量存档#

1
全量：整个 USaveGame 序列化一次 → 简单但大
2

3
增量：只存变化的数据
4
  ├── Slot0：基础数据（角色、进度）
5
  ├── Slot1_QuestProgress：任务数据（独立文件，更新时只存这个）
6
  └── Slot2_Settings：玩家设置

大数据量下拆分成多个 Slot 是更好的做法——每次只存变的部分，I/O 更少。

四、异步存档#

存档在 Game Thread 上同步写文件会卡帧——文件 I/O 是不可预测的。

1
// 异步存档——不卡帧
2
FAsyncSaveGameToSlotDelegate SavedDelegate;
3
SavedDelegate.BindLambda([](const FString& SlotName, const int32 UserIndex, bool bSuccess) {
4
    if (bSuccess) {
5
        UE_LOG(LogTemp, Log, TEXT("存档成功"));
6
    }
7
});
8

9
UGameplayStatics::AsyncSaveGameToSlot(SaveGameObject, "Slot1", 0, SavedDelegate);

异步存档的注意事项：

SaveGameObject 在回调触发前不能被 GC 回收——需要持有一个引用
如果玩家在异步存档过程中退出游戏——需要等待存档完成或取消
同一槽位不能并发写——第二次 AsyncSaveGameToSlot 前等第一次回调

五、RPG 的存档设计示例#

1
UCLASS()
2
class URPGSaveGame : public USaveGame {
3
    // ===== 基础进度（全量存 =====
4
    UPROPERTY()
5
    int32 PlayerLevel;
6

7
    UPROPERTY()
8
    int64 Experience; // 总经验
9

10
    // ===== 任务（增量存 =====
11
    UPROPERTY()
12
    TMap<FGuid, FQuestSaveData> QuestStates; // 任务状态
13

14
    // ===== 赛季信息 =====
15
    UPROPERTY()
16
    FString CurrentSeasonId;
17

18
    UPROPERTY()
19
    int32 SeasonRank;
20

21
    // ===== 设置（独立的 Slot =====
22
    UPROPERTY()
23
    float MasterVolume;
24

25
    UPROPERTY()
26
    EGraphicsQuality GraphicsQuality;
27

28
    // ===== 版本管理 =====
29
    UPROPERTY()
30
    int32 SaveVersion = CURRENT_SAVE_VERSION;
31
};
32

33
// 存档时机
34
void UQuestSubsystem::OnQuestCompleted() {
35
    // 任务完成时自动存档（异步）
36
    UGameplayStatics::AsyncSaveGameToSlot(SaveGame, "Progress", 0, ...);
37
}
38

39
void UWorldProgressSubsystem::OnRegionUnlocked(FGuid RegionId) {
40
    // 解锁新区域时仅更新世界进度存档（增量）
41
    UGameplayStatics::AsyncSaveGameToSlot(WorldProgressSave, "WorldProgress", 0, ...);
42
}

六、总结#

概念	一句话
USaveGame	用 UPROPERTY 标记属性 → 自动序列化到二进制文件
Slot 槽位	多存档位 + UserIndex——玩家可以选存哪个
版本迁移	手写 Serialize → 检查版本号 → 执行迁移逻辑
增量存档	把不同类别的数据拆到不同 Slot——只存变化的部分
异步存档	`AsyncSaveGameToSlot`——不卡帧，但注意 GC 和并发写

存档系统是”做完就行”直到出 bug 的类型。花一点时间设计版本号迁移策略（从 Day 1 就开始）和合理的 Slot 拆分——三个月后的你会感谢现在的你。