1
// ===== 序列化与网络复制的本质关系 =====
2
//
3
// 序列化（Serialization）：
4
//   UObject → FArchive → 字节流 → 磁盘 / 内存 / 网络包
5
//   核心问题："怎么把 C++ 对象的数据保存下来，再完整还原？"
6
//
7
// 网络复制（Replication）：
8
//   服务器 UObject → FBitWriter → 网络包 → 客户端 FBitReader → 客户端 UObject
9
//   核心问题："怎么让客户端看到服务器上的最新状态？"
10
//
11
// 两个问题的底层 100% 复用 FArchive 体系。
12
// 区别仅在于：
13
//   - 序列化：一次性全量写入/读出（SaveGame 存盘）
14
//   - 网络复制：增量、有选择地写入（只同步变化了的属性）
15
//
16
// 面试金句：
17
// "UE 网络复制的本质是 FArchive 对 UPROPERTY 的增量序列化 + UDP 传输。"

1
// ===== 最简序列化：把 UObject 的属性写入内存 =====
2
void BasicSerializeExample()
3
{
4
    // 创建一个对象
5
    UMyObject* MyObj = NewObject<UMyObject>();
6
    MyObj->Health = 100;
7
    MyObj->Name = TEXT("Hero");
8

9
    // ---- 序列化到内存 ----
10
    TArray<uint8> RawBytes;
11
    {
12
        // FMemoryWriter 是 FArchive 的子类
13
        FMemoryWriter Writer(RawBytes);
14
        MyObj->Serialize(Writer);  // ← 核心：UObject::Serialize(FArchive&)
15
    }  // Writer 析构时 flush 到 RawBytes
16
    // RawBytes 现在包含了 Health 和 Name 的二进制表示
17

18
    // ---- 从内存反序列化 ----
19
    UMyObject* NewObj = NewObject<UMyObject>();
20
    {
21
        FMemoryReader Reader(RawBytes);
22
        NewObj->Serialize(Reader);
23
    }  // NewObj->Health == 100, NewObj->Name == TEXT("Hero")
24
}

1
// ===== FArchive 核心 API 速查 =====
2

3
// 1. 基本类型序列化（已内建 operator<<）
4
FArchive& operator<<(FArchive& Ar, uint8& Value);
5
FArchive& operator<<(FArchive& Ar, int32& Value);
6
FArchive& operator<<(FArchive& Ar, float& Value);
7
FArchive& operator<<(FArchive& Ar, FString& Value);
8
FArchive& operator<<(FArchive& Ar, FName& Value);
9
FArchive& operator<<(FArchive& Ar, FText& Value);
10
FArchive& operator<<(FArchive& Ar, FVector& Value);
11
FArchive& operator<<(FArchive& Ar, FRotator& Value);
12

13
// 2. 判断归档方向
14
void SerializeExample(FArchive& Ar)
15
{
16
    if (Ar.IsSaving())    // 正在保存（写入）
17
    {
18
        // 写入数据
19
    }
20
    else if (Ar.IsLoading()) // 正在加载（读取）
21
    {
22
        // 读取数据
23
    }
24
}
25

26
// 3. 判断是否为网络归档
27
if (Ar.IsNetArchive())
28
{
29
    // 这是网络复制的序列化，不是存盘！
30
}
31

32
// 4. 自定义版本的序列化 —— 处理版本兼容
33
// Ar.UEVer() / Ar.CustomVer(GUID) —— 见 12.2.3

1
// ===== 双重序列化接口：operator<< vs Serialize() =====
2
//
3
// UE 有两个序列化入口，但它们最终走到同一个地方：
4
//
5
// 1. friend FArchive& operator<<(FArchive& Ar, UObject*& Obj)
6
//    → 引擎自动生成的代码，遍历所有 UPROPERTY
7
//    → 你通常不需要重写这个
8
//
9
// 2. virtual void Serialize(FArchive& Ar)
10
//    → 你可以重写的虚函数，添加自定义序列化逻辑
11
//    → 必须调用 Super::Serialize(Ar)
12

13
UCLASS()
14
class UMyDataObject : public UObject
15
{
16
    GENERATED_BODY()
17

18
public:
19
    // ---- 标准 UPROPERTY —— 自动序列化 ----
20
    UPROPERTY()
21
    int32 Health;
22

23
    UPROPERTY()
24
    FString Name;
25

26
    // ---- 非 UPROPERTY —— 需要手动序列化 ----
27
    int32 CachedHash;          // 未被 UPROPERTY 标记，不会自动序列化
28
    TMap<int32, float> CacheMap; // 同上
29

30
    virtual void Serialize(FArchive& Ar) override
31
    {
32
        Super::Serialize(Ar);  // ← 必须先调用 Super！这会序列化所有 UPROPERTY
33

34
        // ---- 手动序列化非 UPROPERTY 成员 ----
35
        Ar << CachedHash;       // operator<<(FArchive&, int32&)
36

37
        // 容器的序列化
38
        if (Ar.IsSaving())
39
        {
40
            int32 Num = CacheMap.Num();
41
            Ar << Num;
42
            for (auto& Pair : CacheMap)
43
            {
44
                Ar << const_cast<int32&>(Pair.Key);
45
                Ar << Pair.Value;
46
            }
47
        }
48
        else if (Ar.IsLoading())
49
        {
50
            CacheMap.Empty();
51
            int32 Num = 0;
52
            Ar << Num;
53
            for (int32 i = 0; i < Num; ++i)
54
            {
55
                int32 Key;
56
                float Value;
57
                Ar << Key;
58
                Ar << Value;
59
                CacheMap.Add(Key, Value);
60
            }
61
        }
62
    }
63
};
64

65
// ===== 最常见错误：忘记调用 Super::Serialize(Ar) =====
66
// 症状：所有 UPROPERTY 都不会被序列化——存盘后加载全是默认值！
67
// 原因：UPROPERTY 的序列化是在 Super::Serialize 中由引擎自动完成的
68
// 修复：永远在第一行写 Super::Serialize(Ar)

1
// ===== 版本管理系统 —— 处理游戏更新后的旧存档 =====
2

3
// 场景：你的游戏 v1.0 存了 Health，v2.0 想加一个 MaxHealth
4
// 问题：旧存档没有 MaxHealth 数据 → 加载旧档不能崩溃
5

6
// 方案 1：用引擎版本号
7
virtual void Serialize(FArchive& Ar) override
8
{
9
    Super::Serialize(Ar);
10

11
    // 只在引擎版本 >= VER_UE4_SOMETHING 时才序列化
12
    if (Ar.UEVer() >= VER_UE4_SOME_ENGINE_VERSION)
13
    {
14
        Ar << MaxHealth;
15
    }
16
    else
17
    {
18
        MaxHealth = 100;  // 旧存档的默认值
19
    }
20
}
21

22
// 方案 2：自定义版本 GUID（推荐——更精确）
23
// 步骤 1：在项目的 Version.h 中定义一个 GUID
24
// const FGuid GAME_SAVE_VERSION_MAXHEALTH(0x12345678, 0x9ABC, ...);
25

26
// 步骤 2：在 Serialize 中使用
27
virtual void Serialize(FArchive& Ar) override
28
{
29
    Super::Serialize(Ar);
30

31
    Ar.UsingCustomVersion(GAME_SAVE_VERSION_MAXHEALTH);
32

33
    if (Ar.CustomVer(GAME_SAVE_VERSION_MAXHEALTH) >= 1)
34
    {
35
        Ar << MaxHealth;
36
    }
37
    else
38
    {
39
        MaxHealth = 100;
40
    }
41
}
42

43
// 步骤 3：保存时设置版本号
44
// FArchiveFileWriter::SetCustomVersion(GUID, Version, FriendlyName);
45

46
// ===== 实际项目中更推荐的做法 =====
47
// 不要在 Serialize 里堆积版本判断——用 PostSerialize / PostLoad 修正数据：
48

49
virtual void PostLoad() override
50
{
51
    Super::PostLoad();
52

53
    // PostLoad 在所有属性加载完成后被调用
54
    // 在这里做"旧数据→新数据"的迁移
55
    if (MaxHealth == 0)  // 旧存档没有这个值
56
    {
57
        MaxHealth = 100;
58
    }
59
}

1
// ===== FStructuredArchive —— UE4.25+ 推荐的结构化序列化 =====
2
//
3
// FArchive 是扁平的二进制流（"第3个字节是Health"），
4
// FStructuredArchive 是结构化的键值对（"Health: 100"）。
5
//
6
// 优势：更适合 JSON/文本格式，可读性更强，支持版本迁移
7

8
void Serialize(FStructuredArchive::FRecord Record)
9
{
10
    Super::Serialize(Record);
11

12
    // 老风格（FArchive）：
13
    // Ar << Health;
14

15
    // 新风格（FStructuredArchive）：
16
    FStructuredArchive::FSlot HealthSlot = Record.EnterField(SA_FIELD_NAME(TEXT("Health")));
17
    HealthSlot << Health;  // 带名字的字段！
18

19
    // 支持嵌套结构
20
    {
21
        FStructuredArchive::FRecord SubRecord = Record.EnterRecord(TEXT("SubData"));
22
        SubRecord.EnterField(TEXT("MaxHealth")) << MaxHealth;
23
    }
24
}
25

26
// 面试信息：大多数 UE5 项目仍使用传统 FArchive::Serialize。
27
// FStructuredArchive 主要用于引擎内部的 Asset Registry 和 JSON 导出。

1
// ===== UPROPERTY 序列化控制三大说明符 =====
2

3
// ① Transient —— "这个属性永远不要被序列化，也不要网络复制"
4
UPROPERTY(Transient)
5
int32 CachedDerivedValue;  // 运行时计算出的值，存盘没意义
6
// 适用：缓存、计时器、运行时的中间结果、指向其他 UObject 的临时引用
7

8
// ② SaveGame —— "允许这个属性出现在 SaveGame 对象中"
9
UPROPERTY(SaveGame)
10
int32 PlayerScore;  // 需要被存进存档
11
// 注意：不加 SaveGame 的 UPROPERTY 在 SaveGame 对象中会被跳过！
12

13
// ③ 手动跳过序列化 —— "需要反射但不希望被引擎自动序列化写入"
14
//    没有单独的"SkipSerialization"说明符——那个东西不存在！
15
//    ✓ 标准做法：重写 Serialize(FArchive& Ar)，Super::Serialize 之后
16
//       手动处理——直接在 Ar 流中跳过该字段的写入/读取
17
//    另一种场景：编辑器专用数据 → 用 #if WITH_EDITORONLY_DATA 包裹
18
#if WITH_EDITORONLY_DATA
19
UPROPERTY()
20
int32 EditorOnlyValue;  // 只在编辑器构建中存在，烘焙后彻底消失
21
#endif
22

23
// ===== 标准组合模式 =====
24
UPROPERTY()                         int32 DefaultValue;  // 普通属性，会序列化
25
UPROPERTY(Transient)                int32 NonSerialized; // 完全不序列化
26
UPROPERTY(SaveGame)                 int32 SaveData;      // 存盘属性
27
UPROPERTY(Transient, SaveGame)      int32 SaveOnly;      // 不普通序列化但存档
28
UPROPERTY(Replicated)               int32 Health;        // 网络复制
29
UPROPERTY(ReplicatedUsing=OnRep_Health) int32 HealthWithCallback; // 复制+回调

1
// ===== 不同 UPROPERTY 修饰对序列化的影响 =====
2
//
3
// ┌─────────────────┬──────────┬──────────┬──────────┬──────────┐
4
// │ 说明符           │ 磁盘序列化│ 网络复制  │ SaveGame │ CDO 差异 │
5
// ├─────────────────┼──────────┼──────────┼──────────┼──────────┤
6
// │ (无)             │    ✓     │    ✗     │    ✗     │    ✓     │
7
// │ Transient        │    ✗     │    ✗     │    ✗     │    ✗     │
8
// │ SaveGame         │    ✓     │    ✗     │    ✓     │    ✗     │
9
// │ Replicated       │    ✓     │    ✓     │    ✗     │    ✓     │
10
// │ 手动跳过(Serialize中)│ 取决于实现 │    ✗     │    ✗     │    ✗     │
11
// │ Replicated+SaveGame│  ✓     │    ✓     │    ✓     │    ✓     │
12
// └─────────────────┴──────────┴──────────┴──────────┴──────────┘
13
//
14
// "CDO 差异" = 此属性是否参与 CDO（Class Default Object）的 delta 序列化
15
// 网络复制的基础机制：只发送"当前值与 CDO 值不同"的属性

1
// ===== 存档对象的最小定义 =====
2
UCLASS()
3
class USaveGameData : public USaveGame
4
{
5
    GENERATED_BODY()
6

7
public:
8
    UPROPERTY(SaveGame)                    // ← 每个存盘字段必须加 SaveGame！
9
    FString PlayerName;
10

11
    UPROPERTY(SaveGame)
12
    int32 PlayerLevel;
13

14
    UPROPERTY(SaveGame)
15
    float Health;
16

17
    UPROPERTY(SaveGame)
18
    FVector LastCheckpointLocation;
19

20
    UPROPERTY(SaveGame)
21
    TArray<FString> CompletedQuests;
22

23
    UPROPERTY(SaveGame)
24
    TMap<FString, int32> Inventory;        // 物品ID → 数量
25
};

1
// ===== 完整的存档管理器 =====
2
UCLASS()
3
class UMySaveManager : public UGameInstanceSubsystem
4
{
5
    GENERATED_BODY()
6

7
public:
8
    // ---------- 存档 ----------
9
    void SaveGame(const FString& SlotName, int32 UserIndex = 0)
10
    {
11
        // 1. 创建 SaveGame 对象
12
        USaveGameData* SaveData = Cast<USaveGameData>(
13
            UGameplayStatics::CreateSaveGameObject(USaveGameData::StaticClass()));
14

15
        // 2. 填充数据
16
        SaveData->PlayerName = CurrentPlayerName;
17
        SaveData->PlayerLevel = CurrentLevel;
18
        SaveData->LastCheckpointLocation = LastCheckpoint;
19
        SaveData->CompletedQuests = CompletedQuestIDs;
20
        SaveData->Inventory = CurrentInventory;
21

22
        // 3. 异步写入磁盘 —— 永远别用同步 SaveGame！
23
        FAsyncSaveGameToSlotDelegate SaveDelegate;
24
        SaveDelegate.BindUObject(this, &UMySaveManager::OnSaveComplete);
25

26
        UGameplayStatics::AsyncSaveGameToSlot(
27
            SaveData,           // SaveGame 对象
28
            SlotName,           // 存档槽名称
29
            UserIndex,          // 用户索引（本地多人）
30
            SaveDelegate        // 完成回调
31
        );
32
    }
33

34
    UFUNCTION()
35
    void OnSaveComplete(const FString& SlotName, const int32 UserIndex,
36
                        bool bSuccess)
37
    {
38
        if (bSuccess)
39
        {
40
            UE_LOG(LogSave, Log, TEXT("存档成功: %s"), *SlotName);
41
        }
42
        else
43
        {
44
            UE_LOG(LogSave, Error, TEXT("存档失败: %s"), *SlotName);
45
            // 常见失败原因：
46
            // - 磁盘空间不足
47
            // - 权限不足（主机平台）
48
            // - 存档数据过大
49
            // - 平台存储服务不可用（Xbox/PSN 云端）
50
        }
51
    }
52

53
    // ---------- 读档 ----------
54
    void LoadGame(const FString& SlotName, int32 UserIndex = 0)
55
    {
56
        FAsyncLoadGameFromSlotDelegate LoadDelegate;
57
        LoadDelegate.BindUObject(this, &UMySaveManager::OnLoadComplete);
58

59
        UGameplayStatics::AsyncLoadGameFromSlot(
60
            SlotName,
61
            UserIndex,
62
            LoadDelegate
63
        );
64
    }
65

66
    UFUNCTION()
67
    void OnLoadComplete(const FString& SlotName, const int32 UserIndex,
68
                        USaveGame* LoadedData)
69
    {
70
        USaveGameData* SaveData = Cast<USaveGameData>(LoadedData);
71
        if (!SaveData)
72
        {
73
            UE_LOG(LogSave, Warning, TEXT("没有找到存档或无数据: %s"), *SlotName);
74
            return;
75
        }
76

77
        // 恢复数据
78
        CurrentPlayerName = SaveData->PlayerName;
79
        CurrentLevel = SaveData->PlayerLevel;
80
        LastCheckpoint = SaveData->LastCheckpointLocation;
81
        CompletedQuestIDs = SaveData->CompletedQuests;
82
        CurrentInventory = SaveData->Inventory;
83

84
        // 触发游戏世界的数据恢复
85
        OnGameLoadedDelegate.Broadcast();
86
    }
87

88
    // ---------- 检查存档是否存在 ----------
89
    bool DoesSaveExist(const FString& SlotName, int32 UserIndex = 0) const
90
    {
91
        return UGameplayStatics::DoesSaveGameExist(SlotName, UserIndex);
92
    }
93

94
    // ---------- 删除存档 ----------
95
    bool DeleteSave(const FString& SlotName, int32 UserIndex = 0)
96
    {
97
        return UGameplayStatics::DeleteGameInSlot(SlotName, UserIndex);
98
    }
99

100
    // ---------- 获取所有存档槽 ----------
101
    void GetAllSaveSlots(TArray<FString>& OutSlots)
102
    {
103
        // 获取存档目录中的 .sav 文件列表
104
        const FString SaveDir = FPaths::ProjectSavedDir() / TEXT("SaveGames");
105
        IFileManager::Get().FindFiles(OutSlots, *(SaveDir / TEXT("*.sav")), true, false);
106
    }
107

108
    // 事件：通知游戏世界恢复数据
109
    DECLARE_MULTICAST_DELEGATE(FOnGameLoaded);
110
    FOnGameLoaded OnGameLoadedDelegate;
111

112
private:
113
    FString CurrentPlayerName;
114
    int32 CurrentLevel = 1;
115
    FVector LastCheckpoint;
116
    TArray<FString> CompletedQuestIDs;
117
    TMap<FString, int32> CurrentInventory;
118
};

1
// ===== 推荐：拆分存档为多个 USaveGame 对象 =====
2
//
3
// 不要把整个游戏状态塞进一个 USaveGame！
4
// 好的实践是按功能域拆分：
5

6
UCLASS()
7
class USaveGame_Progress : public USaveGame
8
{
9
    GENERATED_BODY()
10
public:
11
    UPROPERTY(SaveGame) FString CurrentLevelName;
12
    UPROPERTY(SaveGame) TArray<FString> CompletedLevels;
13
    UPROPERTY(SaveGame) FVector CheckpointLocation;
14
};
15

16
UCLASS()
17
class USaveGame_Inventory : public USaveGame
18
{
19
    GENERATED_BODY()
20
public:
21
    UPROPERTY(SaveGame) TMap<FName, int32> Items;       // 物品ID → 数量
22
    UPROPERTY(SaveGame) TArray<FName> EquippedWeapons;  // 装备中的武器
23
    UPROPERTY(SaveGame) int32 Gold;
24
};
25

26
UCLASS()
27
class USaveGame_Settings : public USaveGame
28
{
29
    GENERATED_BODY()
30
public:
31
    UPROPERTY(SaveGame) float MasterVolume;
32
    UPROPERTY(SaveGame) float MouseSensitivity;
33
    UPROPERTY(SaveGame) bool bInvertYAxis;
34
    UPROPERTY(SaveGame) FString LanguagePreference;
35
};
36

37
// 存档时分别调用：
38
// AsyncSaveGameToSlot(ProgressData, SlotName + "_Progress");
39
// AsyncSaveGameToSlot(InventoryData, SlotName + "_Inventory");
40
// AsyncSaveGameToSlot(SettingsData, SlotName + "_Settings");
41

42
// 优势：
43
// 1. 单个文件小，读写快
44
// 2. 一个文件损坏不影响其他数据
45
// 3. 设置可以跨存档共享
46
// 4. 方便做"云存档"的增量上传（只上传变了的部分）

1
// ===== SaveGame 常见错误 TOP 5 =====
2

3
// 陷阱 #1：忘记给属性加 SaveGame 说明符
4
UCLASS()
5
class UBadSaveData : public USaveGame
6
{
7
public:
8
    UPROPERTY()          // ✗ 没有 SaveGame！加载后这个值永远是 0！
9
    int32 PlayerScore;   //    引擎日志不会报错，数据悄悄丢了
10
};
11
// ✓ 修复：
12
UPROPERTY(SaveGame)
13
int32 PlayerScore;
14

15
// 陷阱 #2：存了 UObject 指针
16
UCLASS()
17
class UBadSaveData : public USaveGame
18
{
19
public:
20
    UPROPERTY(SaveGame)
21
    TObjectPtr<AActor> ReferencedActor;  // ✗ 绝对不要这么做！
22
    // 存盘时只存了这个指针的内存地址（一个数字），
23
    // 加载后这个地址指向的 Actor 早就不存在了！
24
    //
25
    // ✓ 正确做法：存 Actor 的 FName / FGuid / FString 标识符，
26
    //    加载后通过标识符查找对应的 Actor
27
    UPROPERTY(SaveGame)
28
    FName ReferencedActorTag;  // 存 Actor 的标签
29
};
30

31
// 陷阱 #3：同步 SaveGame（卡主线程）
32
void BadSaveFunction()
33
{
34
    // ✗ 同步 SaveGame 可能在写入大文件时阻塞主线程数百毫秒！
35
    UGameplayStatics::SaveGameToSlot(SaveData, SlotName, 0);
36
    // 玩家会感觉"卡了一下"——体验极差
37
}
38
// ✓ 永远用 AsyncSaveGameToSlot
39

40
// 陷阱 #4：跨版本加载时崩溃
41
// 场景：v1.0 存了 TArray<int32> Scores，v2.0 改成了 TArray<float> Scores
42
// 结果：加载旧存档时 FArchive 反序列化崩溃！
43
//
44
// ✓ 解决方案：
45
//   a) 保持旧字段，新增新字段（数据迁移在 PostLoad 中做）
46
//   b) 用 CustomVersion 分支逻辑——序列化前先检查归档版本，走不同分支
47
//   c) 在 Serialize 中反序列化前，用 Ar.TotalSize() 和 Ar.Tell() 做边界校验：
48
//      if (Ar.Tell() + ExpectedSize <= Ar.TotalSize()) { /* 安全读取 */ }
49
//
50
// ⚠️ 绝对不要写 try-catch 来兜反序列化崩溃！
51
//    ① UE 默认编译禁用了 C++ 异常（/EHsc-），try/catch 关键字直接编译报错
52
//    ② 即使强行开启异常，反序列化越界是内存访问违例（SEH/Signal），
53
//       标准 C++ try-catch 根本捕获不到——游戏照样闪退
54

55
// 陷阱 #5：在 USaveGame 中存了大量 TSubclassOf
56
// ✗ TSubclassOf 存的是类引用路径（FSoftObjectPath），
57
//    如果类被重命名或删除了，加载就会失败。
58
// ✓ 尽量存枚举或基本类型标识符，而不是类引用。

1
// ===== 网络基础概念速查 =====
2
//
3
// 服务器（Server）：
4
//   - 唯一拥有 Authority 的实例
5
//   - 所有游戏逻辑的最终裁决者
6
//   - 负责将状态"复制"给所有客户端
7
//
8
// 客户端（Client）：
9
//   - 没有 Authority——只是"镜像"
10
//   - 可以发起 RPC 请求服务器（如"我要移动"）
11
//   - 接收服务器的复制数据进行渲染
12
//
13
// 关键概念——"服务器是真理之源"（Server is the Source of Truth）：
14
//   - 伤害计算在服务器
15
//   - 碰撞检测在服务器
16
//   - 血量变化在服务器
17
//   - 客户端永远不应该直接修改"权威数据"
18
//     客户端只能说："我想开枪"，然后服务器决定是否命中、伤害多少

1
// ===== 最小可复制的 Actor =====
2
UCLASS()
3
class AMyNetworkActor : public AActor
4
{
5
    GENERATED_BODY()
6

7
public:
8
    AMyNetworkActor()
9
    {
10
        // ---- 步骤 1：启用网络复制 ----
11
        bReplicates = true;              // Actor 本身参与网络复制
12
        // bReplicates = false → 这个 Actor 只存在于本地，别人看不到它
13

14
        // ---- 步骤 2（可选）：设置网络更新频率 ----
15
        NetUpdateFrequency = 10.0f;      // 每秒最多复制 10 次
16
        // 默认值依 Actor 类型不同（一般为 1~100 Hz）
17

18
        // ---- 步骤 3（可选）：设置网络优先级 ----
19
        NetPriority = 1.0f;              // 相对优先级（越大越优先同步）
20
        // 多个 Actor 需要同步时，带宽优先分给高优先级的
21
    }
22

23
    // ---- 步骤 4：标记需要复制的属性 ----
24
    UPROPERTY(Replicated)
25
    float Health;                        // 这个属性会从服务器同步到客户端
26

27
    UPROPERTY(ReplicatedUsing = OnRep_PlayerName)
28
    FString PlayerName;                  // 变化时调用 OnRep_PlayerName
29

30
    // ---- 步骤 5：注册复制属性 ----
31
    virtual void GetLifetimeReplicatedProps(
32
        TArray<FLifetimeProperty>& OutLifetimeProps) const override
33
    {
34
        Super::GetLifetimeReplicatedProps(OutLifetimeProps);
35

36
        // 基础复制——任何时候都会同步
37
        DOREPLIFETIME(AMyNetworkActor, Health);
38

39
        // 条件复制——只在特定条件下同步（见 12.8）
40
        DOREPLIFETIME_CONDITION(AMyNetworkActor, PlayerName,
41
            COND_InitialOnly);           // 只在 Actor 首次创建时同步一次
42
    }
43

44
    // ---- 步骤 6：复制回调 ----
45
    UFUNCTION()
46
    void OnRep_PlayerName()
47
    {
48
        // 当 PlayerName 在客户端上被更新时自动调用
49
        UE_LOG(LogNet, Log, TEXT("客户端收到新的 PlayerName: %s"), *PlayerName);
50

51
        // 典型的回调内容：更新 UI、播放音效、更新材质
52
        OnPlayerNameChangedEvent(PlayerName);
53
    }
54
};
55

56
// ===== 必不可少的宏 =====
57
// DOREPLIFETIME(ClassName, PropertyName)
58
//   → 无条件复制。属性每次变化都会同步给所有相关客户端。
59
//
60
// DOREPLIFETIME_CONDITION(ClassName, PropertyName, Condition)
61
//   → 条件复制。只在满足条件时才同步（见 12.8 详解）。
62
//
63
// DOREPLIFETIME_ACTIVE_OVERRIDE(ClassName, PropertyName, bActive)
64
//   → 动态开关：可以在运行时决定是否复制这个属性。
65
//
66
// DOREPLIFETIME_CONDITION_NOTIFY(ClassName, PropertyName, Cond, RepNotifyMode)
67
//   → 条件复制 + 自定义 RepNotify 时机（总是 / 仅在值变化时 / 从不）

1
// ===== 决策矩阵 =====
2

3
// 场景 A：纯数值属性，不需要任何回调
4
UPROPERTY(Replicated)
5
float Health;  // 客户端不需要知道"Health 变了"——只需要当前值正确
6
// → 用 Replicated 就够了
7

8
// 场景 B：属性变化需要触发逻辑
9
UPROPERTY(ReplicatedUsing = OnRep_Health)
10
float Health;
11
UFUNCTION() void OnRep_Health();  // 客户端收到新值后：
12
// - 更新血条 UI
13
// - 播放受伤动画
14
// - 低于 25% 时屏幕闪红
15
// → 用 ReplicatedUsing
16

17
// 场景 C：结构体或数组
18
UPROPERTY(ReplicatedUsing = OnRep_Inventory)
19
TArray<FInventoryItem> Inventory;
20
UFUNCTION() void OnRep_Inventory();  // 客户端收到完整数组后：
21
// - 重建背包 UI
22
// - 更新快捷栏
23
// → 用 ReplicatedUsing（TArray 的变化检测比较整个数组）
24

25
// 场景 D：初始化时设置的、之后不会变的值
26
UPROPERTY(Replicated)
27
FString PlayerName;  // 但配合 DOREPLIFETIME_CONDITION(..., COND_InitialOnly)
28
// → 只在 Actor 首次生成时同步一次，之后不再消耗带宽

1
// ===== RPC 三兄弟完整示例 =====
2
UCLASS()
3
class AMyNetworkCharacter : public ACharacter
4
{
5
    GENERATED_BODY()
6

7
public:
8
    // ============================
9
    // ① Server RPC —— 客户端请求，服务器执行
10
    // ============================
11
    // 调用方：客户端（必须有网络拥有权）
12
    // 执行方：服务器
13
    // 用途：客户端发起动作（射击、交互、移动）
14
    //
15
    UFUNCTION(Server, Reliable, WithValidation)
16
    void Server_Shoot(FVector AimLocation);
17

18
    // 在客户端调用：
19
    void OnPlayerPressFire()
20
    {
21
        if (IsLocallyControlled())
22
        {
23
            FVector AimLoc = GetAimLocation();
24
            Server_Shoot(AimLoc);  // ← 客户端调用，但实际上在服务器执行！
25
        }
26
    }
27

28
    // 服务器上的实现：
29
    void AMyNetworkCharacter::Server_Shoot_Implementation(FVector AimLocation)
30
    {
31
        // 这里运行在服务器上——可以安全地修改权威数据
32
        SpawnProjectile(AimLocation);
33
        Ammo--;
34
        Health -= RecoilDamage;
35
    }
36

37
    // 验证函数——在服务器执行 RPC 之前被调用，防止作弊
38
    bool AMyNetworkCharacter::Server_Shoot_Validate(FVector AimLocation)
39
    {
40
        // 检查参数是否合理——客户端发来个 AimLocation=(999999, 999999, 999999)？
41
        if (AimLocation.Size() > 100000.0f) return false;  // 拒绝！明显是作弊
42
        if (Ammo <= 0) return false;                       // 拒绝！没子弹了
43
        return true;  // 通过验证，可以执行 _Implementation
44
    }
45

46
    // ============================
47
    // ② Client RPC —— 服务器通知特定客户端
48
    // ============================
49
    // 调用方：服务器
50
    // 执行方：拥有此 Actor 的客户端
51
    // 用途：通知单个玩家（显示消息、播放个人音效）
52
    //
53
    UFUNCTION(Client, Reliable)
54
    void Client_ShowDamage(float Damage, FVector DamageOrigin);
55

56
    // 服务器调用（通常在 GameMode 或 PlayerController 中）：
57
    void OnPlayerDealtDamage(APlayerController* VictimPC, float Damage,
58
                             FVector Origin)
59
    {
60
        if (AMyNetworkCharacter* Victim = Cast<AMyNetworkCharacter>(VictimPC->GetPawn()))
61
        {
62
            Victim->Client_ShowDamage(Damage, Origin);
63
        }
64
    }
65

66
    // 客户端上的实现：
67
    void AMyNetworkCharacter::Client_ShowDamage_Implementation(
68
        float Damage, FVector DamageOrigin)
69
    {
70
        // 这里运行在受害者自己的客户端上
71
        // 可以安全地播放 UI、音效、震屏——纯表现层逻辑
72
        ShowDamageNumber(Damage);
73
        PlayHitSound();
74
        ShowDamageDirection(DamageOrigin);
75

76
        // 触发手柄振动
77
        if (APlayerController* PC = Cast<APlayerController>(GetController()))
78
        {
79
            PC->PlayHapticEffect(DamageHapticEffect, EControllerHand::RightHand);
80
        }
81
    }
82

83
    // ============================
84
    // ③ NetMulticast RPC —— 服务器广播给所有客户端
85
    // ============================
86
    // 调用方：服务器
87
    // 执行方：所有客户端（包括服务器自己）
88
    // 用途：广播所有人可见的事件（爆炸、开门、Boss 技能）
89
    //
90
    UFUNCTION(NetMulticast, Unreliable)
91
    void Multicast_PlayExplosion(FVector Location, float Radius);
92

93
    // 服务器调用（谁触发了爆炸）：
94
    void TriggerExplosion(FVector Location, float Radius)
95
    {
96
        // 伤害逻辑在服务器：
97
        ApplyExplosionDamage(Location, Radius);
98

99
        // 表现效果广播给所有人：
100
        Multicast_PlayExplosion(Location, Radius);
101
    }
102

103
    // 所有客户端上的实现：
104
    void AMyNetworkCharacter::Multicast_PlayExplosion_Implementation(
105
        FVector Location, float Radius)
106
    {
107
        // 这里运行在每一个客户端上——包括服务器
108
        UGameplayStatics::SpawnEmitterAtLocation(GetWorld(), ExplosionVFX, Location);
109
        UGameplayStatics::PlaySoundAtLocation(GetWorld(), ExplosionSFX, Location);
110

111
        // 震屏——只在本地玩家附近才震
112
        if (APlayerController* PC = UGameplayStatics::GetPlayerController(GetWorld(), 0))
113
        {
114
            if (APawn* LocalPawn = PC->GetPawn())
115
            {
116
                float Dist = FVector::Dist(LocalPawn->GetActorLocation(), Location);
117
                if (Dist < Radius)
118
                {
119
                    PC->ClientStartCameraShake(ExplosionShake,
120
                        FMath::GetMappedRangeValueClamped(
121
                            FVector2D(0, Radius), FVector2D(1.0f, 0.0f), Dist));
122
                }
123
            }
124
        }
125
    }
126
};

1
// ===== Reliable（可靠）vs Unreliable（不可靠）的决策指南 =====
2
//
3
// Reliable RPC：
4
//   - 保证到达：底层 TCP 式重传机制确保对方一定收到
5
//   - 保证顺序：按发送顺序到达
6
//   - 代价：延迟、带宽开销、队头阻塞
7
//   - 适用：关键事件（伤害、死亡、任务完成、物品拾取）
8
//
9
// Unreliable RPC：
10
//   - 不保证到达：网络丢包就直接丢弃
11
//   - 不保证顺序
12
//   - 优势：零额外延迟、极低带宽开销
13
//   - 适用：高频更新的表现效果（脚步声、枪口火焰、表情动画）
14

15
// ---- 实战决策树 ----
16
// Server RPC：Reliable —— 漏掉一个"我开枪了"是不可接受的
17
UFUNCTION(Server, Reliable, WithValidation)
18
void Server_Fire();
19

20
// Client RPC（关键事件）：Reliable —— 伤害信息必须送达
21
UFUNCTION(Client, Reliable)
22
void Client_OnKilled(AActor* Killer);
23

24
// Client RPC（高频 UI）：Reliable —— 但要注意频率
25
UFUNCTION(Client, Reliable)
26
void Client_UpdateScore(int32 NewScore);  // 每秒最多几次——还可以
27

28
// NetMulticast（表现效果）：Unreliable —— 漏一个脚步声无所谓
29
UFUNCTION(NetMulticast, Unreliable)
30
void Multicast_PlayFootstep(FVector Location);
31

32
// NetMulticast（游戏事件）：Reliable —— 门开了必须所有人都看到
33
UFUNCTION(NetMulticast, Reliable)
34
void Multicast_OnDoorOpened();
35

36
// ===== 性能经验法则 =====
37
// 1. 高频 RPC（>10 次/秒）→ Unreliable
38
// 2. 一次性关键事件 → Reliable
39
// 3. Server RPC 几乎总是 Reliable
40
// 4. NetMulticast 效果类 → Unreliable
41
// 5. NetMulticast 状态类 → Reliable（或者改用属性复制）

1
// ===== Server RPC 的验证机制 —— 防作弊的第一道防线 =====
2

3
UFUNCTION(Server, Reliable, WithValidation)
4
void Server_UseItem(int32 ItemSlot, FVector TargetLocation);
5

6
// _Validate 函数 —— 在服务器收到 RPC 后、_Implementation 之前被调用
7
bool AMyPlayerController::Server_UseItem_Validate(int32 ItemSlot,
8
                                                    FVector TargetLocation)
9
{
10
    // 检查 1：参数范围
11
    if (ItemSlot < 0 || ItemSlot >= MaxInventorySlots)
12
    {
13
        UE_LOG(LogNet, Warning, TEXT("作弊嫌疑：无效的物品槽位 %d"), ItemSlot);
14
        return false;  // ← 返回 false → _Implementation 不会被调用！
15
    }
16

17
    // 检查 2：业务逻辑合理性
18
    if (!HasItemInSlot(ItemSlot))
19
    {
20
        UE_LOG(LogNet, Warning, TEXT("作弊嫌疑：空槽位使用 %d"), ItemSlot);
21
        return false;
22
    }
23

24
    // 检查 3：数值合理性
25
    if (TargetLocation.ContainsNaN() ||
26
        TargetLocation.GetAbsMax() > WorldBoundsMax)
27
    {
28
        return false;  // 明显的数据篡改
29
    }
30

31
    // 检查 4：冷却时间
32
    float TimeSinceLastUse = GetWorld()->GetTimeSeconds() - LastItemUseTime;
33
    if (TimeSinceLastUse < MinItemUseInterval)
34
    {
35
        return false;  // 使用速度太快——可能是加速外挂
36
    }
37

38
    return true;  // 通过！执行 _Implementation
39
}
40

41
// ⚠️ 关键：UHT 生成的函数名是两个独立的虚函数，绝不存在 _Validate_Implementation 这种合并后缀！
42
//   - bool Server_UseItem_Validate(...)      → 参数验证（返回 false 则 _Implementation 不执行）
43
//   - void Server_UseItem_Implementation(...) → 核心逻辑
44
// 如果你漏写了 _Validate 函数，UHT 自动生成一个默认返回 true 的桩——
45
// 等于没有任何验证！所有 Server RPC 请务必显式实现 _Validate
46

47
void AMyPlayerController::Server_UseItem_Implementation(int32 ItemSlot,
48
                                                          FVector TargetLocation)
49
{
50
    // 验证通过后才走到这里——执行核心逻辑
51
    UseItemInternal(ItemSlot, TargetLocation);
52
}
53

54
// ===== WithValidation 的最佳实践 =====
55
// 1. 每个 Server RPC 都加 WithValidation
56
// 2. _Validate 里只做参数检查——不做游戏逻辑
57
// 3. 返回 false 时日志记录（方便追踪作弊者）
58
// 4. _Validate 返回 false ≠ 游戏崩溃——只是这次 RPC 被安静丢弃

1
// ===== 网络角色：同一个 Actor 在不同机器上的"身份" =====
2
//
3
// 每个 Actor 在每个连接上有不同的 Role：
4
//
5
// ROLE_Authority：
6
//   - Actor 存在于服务器上
7
//   - 拥有"真理"——可以修改权威数据
8
//   - 负责向所有客户端复制
9
//
10
// ROLE_AutonomousProxy：
11
//   - Actor 存在于"拥有它的客户端"上
12
//   - 可以自主预测（如本地移动）——但最终被服务器校正
13
//   - 接收服务器来的复制数据
14
//
15
// ROLE_SimulatedProxy：
16
//   - Actor 存在于"不拥有它的客户端"上
17
//   - 只能被动接收复制数据
18
//   - 不能做任何自主操作——只能插值渲染
19
//
20
// ROLE_None：
21
//   - 不参与网络——纯本地 Actor
22

23
// ===== 实战判断：我在哪里？我是什么角色？ =====
24
void AMyNetworkActor::SomeFunction()
25
{
26
    // 判断 1：我在服务器上吗？
27
    if (HasAuthority())
28
    {
29
        // 这里运行在服务器端
30
        // 可以安全地修改 Health、扣除子弹、应用伤害
31
        Health -= 10;  // ✓ 安全
32
    }
33

34
    // 判断 2：我是本地玩家控制的 Actor 吗？
35
    if (IsLocallyControlled())
36
    {
37
        // 这里运行在"控制这个 Pawn 的客户端"上
38
        // 典型用途：显示个人 UI、播放脚步声（只有自己能听到的）
39
    }
40

41
    // 判断 3：获取当前连接上的角色
42
    ENetRole LocalRole = GetLocalRole();      // 我在自己的机器上是什么角色
43
    ENetRole RemoteRole = GetRemoteRole();    // 我在对方的机器上是什么角色
44

45
    // 在服务器上：LocalRole = Authority, RemoteRole = SimulatedProxy/AutonomousProxy
46
    // 在客户端A上（自己）：LocalRole = AutonomousProxy, RemoteRole = Authority
47
    // 在客户端B上（看别人）：LocalRole = SimulatedProxy, RemoteRole = Authority
48
}

1
// ===== 客户端预测的经典实现 =====
2
//
3
// 问题：客户端按下"前进"键 → 发 Server RPC → 等服务器回复 → 才移动
4
//        → 100ms+ 延迟的"粘滞感"——无法接受！
5
//
6
// 解决：客户端立即移动（预测），同时发 Server RPC，
7
//       服务器校正位置时平滑修正。
8

9
UCLASS()
10
class AMyPredictedCharacter : public ACharacter
11
{
12
    GENERATED_BODY()
13

14
public:
15
    // 客户端调用的移动函数
16
    void MoveForward(float Value)
17
    {
18
        if (!IsLocallyControlled()) return;
19

20
        // 步骤 1：本地立即移动（预测）
21
        AddMovementInput(GetActorForwardVector(), Value);
22

23
        // 步骤 2：保存本地移动记录
24
        FPredictedMove Move;
25
        Move.Timestamp = GetWorld()->GetTimeSeconds();
26
        Move.Delta = Value;
27
        Move.StartLocation = GetActorLocation();
28
        PendingMoves.Add(Move);
29

30
        // 步骤 3：发 Server RPC
31
        Server_MoveForward(Value, Move.Timestamp);
32
    }
33

34
    UFUNCTION(Server, Reliable, WithValidation)
35
    void Server_MoveForward(float Value, float Timestamp);
36

37
    void Server_MoveForward_Implementation(float Value, float Timestamp)
38
    {
39
        // 服务器执行同样的移动
40
        AddMovementInput(GetActorForwardVector(), Value);
41

42
        // 计算服务器位置（权威位置）
43
        FVector ServerLocation = GetActorLocation();
44

45
        // 服务器位置会自动复制回客户端
46
        // 客户端在 OnRep_Location 中做平滑校正
47
    }
48

49
    // 复制位置 + 回调
50
    UPROPERTY(ReplicatedUsing = OnRep_ReplicatedLocation)
51
    FVector ReplicatedLocation;
52

53
    UFUNCTION()
54
    void OnRep_ReplicatedLocation()
55
    {
56
        if (!IsLocallyControlled()) return;
57

58
        // 找到对应的本地预测移动
59
        FPredictedMove* Found = PendingMoves.FindByPredicate(
60
            [&](const FPredictedMove& M) {
61
                return M.StartLocation.Equals(ReplicatedLocation, 1.0f);
62
            });
63

64
        if (Found)
65
        {
66
            // 服务器位置与预测位置一致——清理预测记录
67
            PendingMoves.RemoveAll(
68
                [&](const FPredictedMove& M) { return M.Timestamp <= Found->Timestamp; });
69
        }
70
        else
71
        {
72
            // 服务器位置与预测不同 → 需要校正！
73
            // 平滑插值到服务器位置（而不是瞬间跳变）
74
            FVector Correction = ReplicatedLocation - GetActorLocation();
75
            if (Correction.Size() > MaxCorrectionThreshold)
76
            {
77
                // 偏差太大——直接设置（可能是穿墙了）
78
                SetActorLocation(ReplicatedLocation);
79
            }
80
            else
81
            {
82
                // 小偏差——平滑校正
83
                SetActorLocation(FMath::VInterpTo(
84
                    GetActorLocation(), ReplicatedLocation,
85
                    GetWorld()->GetDeltaSeconds(), CorrectionSpeed));
86
            }
87
        }
88
    }
89

90
private:
91
    struct FPredictedMove
92
    {
93
        float Timestamp;
94
        float Delta;
95
        FVector StartLocation;
96
    };
97
    TArray<FPredictedMove> PendingMoves;
98
    float CorrectionSpeed = 10.0f;
99
    float MaxCorrectionThreshold = 100.0f;
100
};

1
// ===== 所有复制条件速查 =====
2

3
virtual void GetLifetimeReplicatedProps(
4
    TArray<FLifetimeProperty>& OutLifetimeProps) const override
5
{
6
    Super::GetLifetimeReplicatedProps(OutLifetimeProps);
7

8
    // ---- 无条件复制 ----
9
    DOREPLIFETIME(AMyActor, Health);  // 每次变化都同步
10

11
    // ---- 条件复制 ----
12
    // COND_None：无条件（等同于 DOREPLIFETIME）
13
    DOREPLIFETIME_CONDITION(AMyActor, Health, COND_None);
14

15
    // COND_InitialOnly：只在 Actor 首次创建时复制一次
16
    // 适用：玩家名字、角色外观、初始配置——一旦设置就不再变的
17
    DOREPLIFETIME_CONDITION(AMyActor, PlayerName, COND_InitialOnly);
18

19
    // COND_OwnerOnly：只复制给拥有此 Actor 的客户端
20
    // 适用：弹药数、背包内容——别人不需要看到你的弹药
21
    DOREPLIFETIME_CONDITION(AMyActor, Ammo, COND_OwnerOnly);
22

23
    // COND_SkipOwner：复制给所有人除了拥有此 Actor 的客户端
24
    // 适用：其他人的位置——你自己不需要收到"你自己在哪"的复制
25
    DOREPLIFETIME_CONDITION(AMyActor, VisibleToOthers, COND_SkipOwner);
26

27
    // COND_SimulatedOnly：只复制给 SimulatedProxy 的客户端
28
    // 适用：视觉表现数据——自己不需要看到自己的"被复制版本"
29
    DOREPLIFETIME_CONDITION(AMyActor, SimulatedTransform, COND_SimulatedOnly);
30

31
    // COND_AutonomousOnly：只复制给 AutonomousProxy 的客户端
32
    // 适用：服务器校验后的状态——只有控制者需要知道
33
    DOREPLIFETIME_CONDITION(AMyActor, CorrectionData, COND_AutonomousOnly);
34

35
    // COND_SimulatedOrPhysics：SimulatedProxy 或物理激活时
36
    DOREPLIFETIME_CONDITION(AMyActor, PhysicsState, COND_SimulatedOrPhysics);
37

38
    // COND_InitialOrOwner：首次复制给所有人 + 之后只复制给拥有者
39
    // 适用：初始外观（所有人看到一次），后续变化只通知拥有者
40
    DOREPLIFETIME_CONDITION(AMyActor, SkinIndex, COND_InitialOrOwner);
41

42
    // COND_Custom：自定义条件——最灵活
43
    DOREPLIFETIME_CONDITION(AMyActor, CustomData, COND_Custom);
44
}
45

46
// ---- COND_Custom 的自定义条件实现 ----
47
// COND_Custom 不是通过重写 ReplicateSubobject 来控制的！
48
// ReplicateSubobject 是专门用来同步 Actor 身上挂载的非组件 UObject 子对象的，
49
// 与控制属性复制条件完全是两码事。
50
//
51
// ✓ 正确做法：在 PreReplicateProperties() 中调用 DOREPLIFETIME_ACTIVE_OVERRIDE
52
//   动态决定本轮复制是否发送该属性：
53

54
virtual void PreReplication(IRepChangedPropertyTracker& ChangedPropertyTracker) override
55
{
56
    Super::PreReplication(ChangedPropertyTracker);
57

58
    // 动态开关：只在目标客户端在 100 米内时才复制 CustomData
59
    // 这里获取当前的连接上下文，根据距离设置 bActive
60
    DOREPLIFETIME_ACTIVE_OVERRIDE(AMyActor, CustomData, bShouldReplicateCustomData);
61
}
62

63
// 在 Tick 或相关逻辑中更新条件标记：
64
void AMyActor::Tick(float DeltaTime)
65
{
66
    Super::Tick(DeltaTime);
67
    // 根据实际业务逻辑更新 bShouldReplicateCustomData
68
    // 例如：检查所有相关客户端的距离
69
    bShouldReplicateCustomData = IsAnyRelevantClientWithinDistance(10000.0f);
70
}
71

72
// ⚠️ 特别注意：
73
// DOREPLIFETIME_ACTIVE_OVERRIDE 必须在 PreReplication 或 PreReplicateProperties
74
// 中调用——这是在网络驱动决定"本轮复制哪些属性"之前的最后一个回调点