1
// ===== 硬编码的末日 vs 数据驱动的黎明 =====
2
//
3
// ✗ 硬编码（Hard-Coded）：
4
//   - 策划说"把 AK47 伤害从 25 改成 26" → 你改 C++ → 编译 20 分钟 → 打包 1 小时
5
//   - 所有武器数据散落在 50 个 .cpp 文件中
6
//   - 每次数值调整 = 一次完整的代码变更 + CI 流水线
7
//
8
// ✓ 数据驱动（Data-Driven）：
9
//   - 伤害值存在 DataTable 的 CSV 里 → 策划改个数字 → 编辑器内热更新 → 立刻测试
10
//   - 武器配置存为 DataAsset → 策划在编辑器中拖拽图标、调整参数
11
//   - 代码和数据的生命周期彻底解耦——你的 C++ 只定义"结构"，数据由策划维护
12
//
13
// 核心原则：
14
//   "C++ 定义 WHAT（什么结构），数据定义 HOW MUCH（数值多少）"
15
//   "代码 = 骨架，数据 = 血肉"

1
// ===== 两种 DataAsset 的选择 =====
2
//
3
// UDataAsset：
4
//   - 轻量级的 UObject 容器——一组 C++ 配置数据存为一个 .uasset 文件
5
//   - 不参与 Asset Manager 的 Primary Asset 标签体系
6
//   - 适用：小规模配置（角色属性预设、武器参数、技能定义）
7
//
8
// UPrimaryDataAsset：
9
//   - UDataAsset 的子类，额外支持 Asset Manager 的标签和 Bundle 系统
10
//   - 可以按 PrimaryAssetId 查找、管理生命周期
11
//   - 适用：大规模资产集合（所有武器的数据库、所有怪物的配置、所有 UI 皮肤）
12

13
// ---------- ① 基础 DataAsset：武器属性 ----------
14
UCLASS(BlueprintType)
15
class UWeaponData : public UDataAsset
16
{
17
    GENERATED_BODY()
18

19
public:
20
    // ---- 基础信息 ----
21
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Info")
22
    FText DisplayName;
23

24
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Info")
25
    FText Description;
26

27
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Info")
28
    TSoftObjectPtr<UTexture2D> Icon;  // 软引用——图标不加载到内存
29

30
    // ---- 战斗数值 ----
31
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Combat")
32
    float BaseDamage = 10.0f;
33

34
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Combat")
35
    float FireRate = 600.0f;  // RPM
36

37
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Combat")
38
    int32 MagazineSize = 30;
39

40
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Combat")
41
    float ReloadTime = 2.0f;
42

43
    // ---- 表现资源（软引用——运行时按需加载）----
44
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Assets")
45
    TSoftObjectPtr<USkeletalMesh> WeaponMesh;  // 只存路径，不加载网格体
46

47
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Assets")
48
    TSoftObjectPtr<UAnimMontage> FireMontage;
49

50
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Assets")
51
    TSoftObjectPtr<USoundCue> FireSound;
52

53
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Assets")
54
    TSoftObjectPtr<UNiagaraSystem> MuzzleFlashVFX;
55

56
    // ---- 工具函数 ----
57
    float GetDamagePerSecond() const { return BaseDamage * FireRate / 60.0f; }
58
};
59

60
// ---------- ② Primary DataAsset：所有武器的数据库 ----------
61
UCLASS(BlueprintType)
62
class UWeaponDatabase : public UPrimaryDataAsset
63
{
64
    GENERATED_BODY()
65

66
public:
67
    // Primary DataAsset 必须重写此函数——返回资产的唯一 ID
68
    virtual FPrimaryAssetId GetPrimaryAssetId() const override
69
    {
70
        // 格式：WeaponDatabase:Default —— 这是全局唯一的资产标识
71
        return FPrimaryAssetId(TEXT("WeaponDatabase"), GetFName());
72
    }
73

74
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Weapons")
75
    TMap<FName, TSoftObjectPtr<UWeaponData>> WeaponMap;  // 武器ID → 武器数据（软引用）
76

77
    UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Defaults")
78
    TSoftObjectPtr<UWeaponData> DefaultWeapon;
79

80
    // 按名称查找武器
81
    UWeaponData* GetWeaponData(FName WeaponID) const
82
    {
83
        if (const TSoftObjectPtr<UWeaponData>* Found = WeaponMap.Find(WeaponID))
84
        {
85
            return Found->LoadSynchronous();  // ⚠️ 同步加载——仅用于已被预载的资产
86
        }
87
        return nullptr;
88
    }
89
};

1
// ===== DataAsset 的创建和使用流程 =====
2
//
3
// 步骤 1：C++ 定义 DataAsset 类（如上）
4
// 步骤 2：编译后，编辑器中右键 → Miscellaneous → Data Asset → 选你的类
5
// 步骤 3：在编辑器属性面板中填写数值——策划可以操作，不需要 IDE
6
// 步骤 4：C++ 中获取 DataAsset 实例
7

8
// ---------- 在 GameMode 或 Subsystem 中加载 DataAsset ----------
9
UCLASS()
10
class UWeaponManager : public UGameInstanceSubsystem
11
{
12
    GENERATED_BODY()
13

14
public:
15
    // 硬引用：这个 DataAsset 会在 GameInstance 初始化时被加载到内存
16
    UPROPERTY(EditDefaultsOnly, Category = "Config")
17
    TObjectPtr<UWeaponDatabase> WeaponDB;
18

19
    // BP 中设置 WeaponDB → 指向 Content/Data/WeaponDB.uasset
20

21
    UWeaponData* GetWeaponData(FName WeaponID) const
22
    {
23
        if (!WeaponDB) return nullptr;
24
        return WeaponDB->GetWeaponData(WeaponID);
25
    }
26

27
    // 异步加载武器配置（配合 StreamableManager）
28
    void LoadWeaponDataAsync(FName WeaponID,
29
                             TFunction<void(UWeaponData*)> OnLoaded)
30
    {
31
        if (!WeaponDB) return;
32

33
        // 从 WeaponDB 中找到软引用路径
34
        const TSoftObjectPtr<UWeaponData>* Found =
35
            WeaponDB->WeaponMap.Find(WeaponID);
36
        if (!Found) return;
37

38
        // 异步加载
39
        FStreamableManager& Manager = UAssetManager::GetStreamableManager();
40
        Manager.RequestAsyncLoad(
41
            Found->ToSoftObjectPath(),
42
            FStreamableDelegate::CreateLambda(
43
                [OnLoaded, WeaponID, this]()
44
                {
45
                    UWeaponData* Data = WeaponDB->GetWeaponData(WeaponID);
46
                    OnLoaded(Data);
47
                }
48
            )
49
        );
50
    }
51
};
52

53
// ===== DataAsset vs 继承 vs Struct 的选择 =====
54
//
55
// DataAsset：
56
//   ✓ 策划可视化编辑；可作为 .uasset 独立管理；支持软引用
57
//   ✗ 有 UObject 开销；不适合存每一行数据
58
//   适用：一组相关的配置（武器预设、角色模板、技能定义、UI 皮肤集）
59
//
60
// 继承（子类）：
61
//   ✓ 行为可重写（虚函数）；编译期类型安全
62
//   ✗ 一个配置变化 = 一个新的蓝图子类 → 爆炸式增长
63
//   适用：不仅数据不同，行为也不同（不同武器发射逻辑）
64
//
65
// Struct（FTableRowBase）：
66
//   ✓ 零 UObject 开销；可存数万行
67
//   ✗ 不能独立存在为 .uasset；策划看不到实时预览
68
//   适用：表格数据，一行就是一个数据点（道具表、怪物表、经验值表）

1
// ===== DataTable 的完整定义和使用 =====
2

3
// ---------- 步骤 1：定义行结构 ----------
4
USTRUCT(BlueprintType)
5
struct FMonsterDataRow : public FTableRowBase  // ← 必须继承 FTableRowBase！
6
{
7
    GENERATED_BODY()
8

9
public:
10
    UPROPERTY(EditAnywhere, BlueprintReadOnly)
11
    FText DisplayName;
12

13
    UPROPERTY(EditAnywhere, BlueprintReadOnly)
14
    float Health = 100.0f;
15

16
    UPROPERTY(EditAnywhere, BlueprintReadOnly)
17
    float AttackPower = 10.0f;
18

19
    UPROPERTY(EditAnywhere, BlueprintReadOnly)
20
    float MoveSpeed = 600.0f;
21

22
    UPROPERTY(EditAnywhere, BlueprintReadOnly)
23
    int32 ExperienceReward = 50;
24

25
    UPROPERTY(EditAnywhere, BlueprintReadOnly)
26
    TSoftObjectPtr<USkeletalMesh> Mesh;  // 软引用——不加载模型到内存
27

28
    UPROPERTY(EditAnywhere, BlueprintReadOnly)
29
    TSoftObjectPtr<UBehaviorTree> BehaviorTree;
30

31
    UPROPERTY(EditAnywhere, BlueprintReadOnly)
32
    TArray<FName> DropItemIDs;  // 掉落物品 ID，对应另一个 DataTable
33

34
    // FTableRowBase 自带 FName RowName —— 行名即 Key，不需要额外定义
35
};
36

37
// ---------- 步骤 2：CSV 文件格式 ----------
38
// 文件：MonsterTable.csv
39
//
40
// ---,DisplayName,Health,AttackPower,MoveSpeed,ExperienceReward,Mesh,BehaviorTree,DropItemIDs
41
// Goblin,哥布林,50.0,8.0,400.0,20,/Game/Monsters/Goblin/Mesh.Mesh,/Game/AI/BT_Goblin.BT_Goblin,"(Potion,Sword)"
42
// Orc,兽人,200.0,25.0,300.0,100,/Game/Monsters/Orc/Mesh.Mesh,/Game/AI/BT_Orc.BT_Orc,"(Axe,Armor)"
43
// Dragon,龙,1000.0,80.0,500.0,500,/Game/Monsters/Dragon/Mesh.Mesh,/Game/AI/BT_Dragon.BT_Dragon,"(Gold,DragonScale)"
44
//
45
// 注意：
46
// - 第一列是行名（RowName），列头留空或写 "---"
47
// - FText 字段的 CSV 值是本地化 Key，不是显示文本
48
// - 数组字段用括号包裹，逗号分隔：(Item1,Item2,Item3)

1
// ===== DataTable 核心 API =====
2
UCLASS()
3
class UMonsterDataManager : public UGameInstanceSubsystem
4
{
5
    GENERATED_BODY()
6

7
public:
8
    // 硬引用 DataTable
9
    UPROPERTY(EditDefaultsOnly, Category = "Data")
10
    TObjectPtr<UDataTable> MonsterTable;
11

12
    // ---------- 读取操作 ----------
13

14
    // ① 按行名精确查找——最常用
15
    FMonsterDataRow* GetMonsterData(FName MonsterID) const
16
    {
17
        if (!MonsterTable) return nullptr;
18

19
        return MonsterTable->FindRow<FMonsterDataRow>(
20
            MonsterID,          // 行名（CSV 第一列）
21
            TEXT("MonsterLookup") // 上下文字符串——出错时出现在日志中方便定位
22
        );
23
    }
24

25
    // ② 遍历所有行
26
    void GetAllMonsters(TArray<FMonsterDataRow>& OutRows) const
27
    {
28
        if (!MonsterTable) return;
29

30
        // DataTable 内部的 TMap<FName, uint8*> 存储
31
        const TMap<FName, uint8*>& RowMap = MonsterTable->GetRowMap();
32
        for (const auto& Pair : RowMap)
33
        {
34
            FMonsterDataRow* Row =
35
                reinterpret_cast<FMonsterDataRow*>(Pair.Value);
36
            if (Row) OutRows.Add(*Row);
37
        }
38
    }
39

40
    // ③ 按条件筛选——高等级怪物
41
    void GetEliteMonsters(float MinHealth,
42
                          TArray<FMonsterDataRow>& OutRows) const
43
    {
44
        TArray<FMonsterDataRow*> AllRows;
45
        MonsterTable->GetAllRows<FMonsterDataRow>(TEXT("GetElite"), AllRows);
46

47
        for (FMonsterDataRow* Row : AllRows)
48
        {
49
            if (Row && Row->Health >= MinHealth)
50
            {
51
                OutRows.Add(*Row);
52
            }
53
        }
54
    }
55

56
    // ---------- 运行时写入（不推荐——仅编辑器工具用） ----------
57
#if WITH_EDITOR
58
    void UpdateMonsterHealth(FName MonsterID, float NewHealth)
59
    {
60
        if (FMonsterDataRow* Row = GetMonsterData(MonsterID))
61
        {
62
            Row->Health = NewHealth;  // 运行时修改——不会自动保存到 CSV
63
            // 这只是改内存中的副本！重载关卡后会恢复为 CSV 中的值
64
        }
65
    }
66
#endif
67
};
68

69
// ===== FindRow 的注意事项 =====
70
// FindRow 返回的是 DataTable 内部存储的指针——不要缓存它！
71
//
72
// ✓ 正确做法：每次使用时 FindRow（查找是 O(1) 哈希查找，极快）
73
// ✗ 错误做法：在 BeginPlay 中存一个 Row*，之后一直用——
74
//    DataTable 可能在特定时机（热重载、编辑器刷新）重新加载，你的指针会悬空！

1
// ===== Composite DataTable：模块化配置的叠加 =====
2
//
3
// 场景：基础怪物表 + DLC 新怪物表 + 活动限定怪物表
4
// 问题：三张表分别维护——但我想在运行时"看到所有怪物"
5
// 解决：Composite DataTable 将多张表逻辑合并为一张虚拟大表
6

7
// 设置方式（编辑器中操作，或 C++ 构建）：
8
UCLASS()
9
class UMonsterDataManager_Composite : public UGameInstanceSubsystem
10
{
11
    GENERATED_BODY()
12

13
public:
14
    // 基础表——所有怪物都在这里
15
    UPROPERTY(EditDefaultsOnly, Category = "Data")
16
    TObjectPtr<UDataTable> BaseMonsterTable;
17

18
    // DLC 覆盖表——同名 Row 会覆盖基础表中的数据
19
    UPROPERTY(EditDefaultsOnly, Category = "Data")
20
    TObjectPtr<UDataTable> DLCOverrideTable;
21

22
    // 活动限定表——限时怪物的数据
23
    UPROPERTY(EditDefaultsOnly, Category = "Data")
24
    TObjectPtr<UDataTable> EventMonsterTable;
25

26
    // 手动实现 Composite 查找逻辑：
27
    FMonsterDataRow* FindMonster(FName MonsterID) const
28
    {
29
        // 优先级：活动表 > DLC 表 > 基础表
30
        // 活动限定怪会覆盖 DLC 的同名怪，DLC 覆盖基础怪
31

32
        if (EventMonsterTable)
33
        {
34
            if (auto* Row = EventMonsterTable->FindRow<FMonsterDataRow>(
35
                    MonsterID, TEXT("Event")))
36
                return Row;
37
        }
38

39
        if (DLCOverrideTable)
40
        {
41
            if (auto* Row = DLCOverrideTable->FindRow<FMonsterDataRow>(
42
                    MonsterID, TEXT("DLC")))
43
                return Row;
44
        }
45

46
        if (BaseMonsterTable)
47
        {
48
            return BaseMonsterTable->FindRow<FMonsterDataRow>(
49
                MonsterID, TEXT("Base"));
50
        }
51

52
        return nullptr;
53
    }
54
};

1
// ===== CurveTable：用曲线替代离散数值 =====
2
//
3
// 场景：经验值曲线——不是"每级 100 经验"，而是 1级→100 / 2级→250 / 3级→500
4
// 问题：离散公式难以表达设计师想要的"前快后慢"或"S 形曲线"
5
// 解决：CurveTable 存一条浮点曲线——X=等级, Y=所需经验
6

7
UCLASS()
8
class UExperienceManager : public UGameInstanceSubsystem
9
{
10
    GENERATED_BODY()
11

12
public:
13
    UPROPERTY(EditDefaultsOnly, Category = "Data")
14
    TObjectPtr<UCurveTable> ExperienceCurve;
15

16
    // 获取升到指定等级所需的总经验
17
    int32 GetExperienceForLevel(int32 Level) const
18
    {
19
        if (!ExperienceCurve) return 0;
20

21
        // CurveTable 中的曲线以 FName 为 Key
22
        static const FName CurveName = TEXT("ExpCurve");
23

24
        // 获取曲线
25
        FRealCurve* Curve = ExperienceCurve->FindCurve(
26
            CurveName,
27
            TEXT("GetExp"),     // 上下文
28
            false               // bLogErrors
29
        );
30

31
        if (!Curve) return 0;
32

33
        // 在曲线上求值
34
        return FMath::RoundToInt(Curve->Eval(static_cast<float>(Level)));
35
    }
36

37
    // 批量预计算——将所有等级的经验值缓存到 TArray
38
    void PreCacheExperienceCurve(int32 MaxLevel)
39
    {
40
        CachedExp.Empty(MaxLevel + 1);
41
        for (int32 Lv = 1; Lv <= MaxLevel; ++Lv)
42
        {
43
            CachedExp.Add(GetExperienceForLevel(Lv));
44
        }
45
    }
46

47
    // 快速查表
48
    int32 GetCachedExp(int32 Level) const
49
    {
50
        return CachedExp.IsValidIndex(Level - 1) ?
51
               CachedExp[Level - 1] : 0;
52
    }
53

54
private:
55
    TArray<int32> CachedExp;
56
};
57

58
// ===== CurveTable vs FRichCurve vs 公式 =====
59
//
60
// CurveTable：
61
//   ✓ 设计师在编辑器中可视化拖拽曲线（所见即所得）
62
//   ✓ 支持多种插值方式（Linear/Cubic/Constant）
63
//   ✓ 可以导入 CSV 批量编辑
64
//   ✗ 有 UObject 开销
65
//   适用：经验曲线、伤害衰减、难度缩放——设计师需要直观感受
66
//
67
// FRichCurve（内嵌在 UPROPERTY 中）：
68
//   ✓ 作为 DataAsset 或 Actor 的成员属性，直接在 Details Panel 中编辑
69
//   ✓ 零额外 UObject
70
//   适用：单个对象的简单曲线（飞行器的推力曲线、弹簧阻尼）
71
//
72
// 公式（FMath 表达式）：
73
//   ✓ 最精确、最可预测
74
//   ✗ 设计师不能拖拽调试
75
//   适用：物理模拟、数学上严格定义的曲线

1
// ===== 硬引用 vs 软引用：内存模型对比 =====
2
//
3
// 硬引用（TObjectPtr<T> / T*）：
4
//   LoadObject<UTexture2D>(Path) → 纹理被加载到内存
5
//   → 指针指向内存中的 UObject → 该纹理和它引用的所有资产全部驻留
6
//   → 哪怕玩家永远不打开背包——背包图标已经在内存里了！
7
//   等价于："把这个资产的指针给我，现在就加载它"
8
//
9
// 软引用（TSoftObjectPtr<T> / FSoftObjectPath）：
10
//   TSoftObjectPtr<UTexture2D> Icon;  // 这里存的只是一个 FString 路径
11
//   → 没有 UObject 被加载！内存占用 = sizeof(FSoftObjectPath) ≈ 几个指针
12
//   → 需要时异步加载：AssetManager.RequestAsyncLoad(Path, Callback)
13
//   等价于："记住这个资产在哪，以后需要时再加载"
14
//
15
// 硬引用 = 你朋友家的钥匙——你可以直接开门进去
16
// 软引用 = 你朋友家的地址——你知道在哪，但要去得先约时间（异步加载）
17

18
// ---------- 可视化：10,000 个武器的内存占用 ----------
19
// 硬引用加载全部资产：
20
//   10,000 × 纹理(2MB) + 10,000 × 模型(5MB) + 10,000 × 音效(0.5MB)
21
//   = 75GB 内存 → 直接爆炸！
22
//
23
// 软引用（只存路径）：
24
//   10,000 × FSoftObjectPath(≈80 bytes)
25
//   = 0.8MB 内存 → 约等于零！

1
// ===== 软引用类型选择 =====
2

3
// ① TSoftObjectPtr<T> —— 最常用（模板包装，类型安全）
4
UPROPERTY(EditAnywhere, BlueprintReadOnly)
5
TSoftObjectPtr<UTexture2D> Icon;
6

7
// 访问方式：
8
UTexture2D* LoadedIcon = Icon.LoadSynchronous();  // 同步（卡帧！仅用于已缓存的资产）
9
UTexture2D* CachedIcon = Icon.Get();               // 不加载——如果已经加载了返回指针，否则 null
10
bool bIsLoaded = Icon.IsValid();                   // 判断是否已加载到内存
11

12
// ② FSoftObjectPath —— 底层路径字符串（非模板）
13
UPROPERTY(EditAnywhere, BlueprintReadOnly)
14
FSoftObjectPath MeshPath;
15

16
// 可以指向任意类型的 UObject——不做类型检查
17
// 适用：运行时动态决定加载什么类型
18

19
// ③ TSoftClassPtr<T> —— 软引用蓝图/类
20
UPROPERTY(EditAnywhere, BlueprintReadOnly)
21
TSoftClassPtr<AActor> SpawnableActorClass;
22

23
// 访问：
24
UClass* LoadedClass = SpawnableActorClass.LoadSynchronous();
25
AActor* SpawnedActor = GetWorld()->SpawnActor<AActor>(LoadedClass);
26

27
// ④ FSoftObjectPath 与 TSoftObjectPtr 互转
28
TSoftObjectPtr<UTexture2D> SoftPtr(SomePath);
29
FSoftObjectPath Path = SoftPtr.ToSoftObjectPath();    // TSoftObjectPtr → FSoftObjectPath
30

31
TSoftObjectPtr<UTexture2D> BackToSoftPtr(Path);       // FSoftObjectPath → TSoftObjectPtr

1
// ===== 场景：10,000 种道具的背包系统 =====
2
// 内存要求：加载所有道具图标和模型 = 不可能
3
// 解决方案：只存 FSoftObjectPath，按需异步加载
4

5
// ---------- 道具定义（DataTable 行结构） ----------
6
USTRUCT(BlueprintType)
7
struct FItemRow : public FTableRowBase
8
{
9
    GENERATED_BODY()
10

11
    UPROPERTY(EditAnywhere, BlueprintReadOnly)
12
    FText DisplayName;
13

14
    UPROPERTY(EditAnywhere, BlueprintReadOnly)
15
    int32 MaxStackSize = 99;
16

17
    UPROPERTY(EditAnywhere, BlueprintReadOnly)
18
    TSoftObjectPtr<UTexture2D> Icon;        // 图标——打开背包时才加载
19

20
    UPROPERTY(EditAnywhere, BlueprintReadOnly)
21
    TSoftObjectPtr<UStaticMesh> WorldMesh;  // 模型——丢弃到地上时才加载
22

23
    UPROPERTY(EditAnywhere, BlueprintReadOnly)
24
    TSoftObjectPtr<USoundCue> PickupSound;  // 音效——拾取时才加载
25
};
26

27
// ---------- 背包管理器 ----------
28
UCLASS()
29
class UInventoryManager : public UGameInstanceSubsystem
30
{
31
    GENERATED_BODY()
32

33
public:
34
    UPROPERTY(EditDefaultsOnly)
35
    TObjectPtr<UDataTable> ItemTable;
36

37
    // 玩家的背包——只存 ItemID 和数量，不存任何资产引用
38
    UPROPERTY(SaveGame, BlueprintReadOnly)
39
    TMap<FName, int32> Inventory;  // ItemID → 持有数量
40

41
    // ---------- 异步加载道具图标（背包 UI 打开时） ----------
42
    void LoadItemIconAsync(FName ItemID, TFunction<void(UTexture2D*)> OnLoaded)
43
    {
44
        FItemRow* Row = ItemTable->FindRow<FItemRow>(ItemID, TEXT("Inventory"));
45
        if (!Row)
46
        {
47
            OnLoaded(nullptr);
48
            return;
49
        }
50

51
        // 如果已经加载了——直接返回（缓存命中）
52
        if (UTexture2D* Cached = Row->Icon.Get())
53
        {
54
            OnLoaded(Cached);
55
            return;
56
        }
57

58
        // 否则异步加载
59
        FStreamableManager& Manager = UAssetManager::GetStreamableManager();
60
        Manager.RequestAsyncLoad(
61
            Row->Icon.ToSoftObjectPath(),
62
            FStreamableDelegate::CreateLambda(
63
                [Row, OnLoaded]()
64
                {
65
                    OnLoaded(Row->Icon.Get());
66
                }
67
            )
68
        );
69
    }
70

71
    // ---------- 批量预加载（预见性加载——玩家打开背包前） ----------
72
    void PreloadVisibleIcons(const TArray<FName>& VisibleItemIDs)
73
    {
74
        TArray<FSoftObjectPath> PathsToLoad;
75

76
        for (FName ItemID : VisibleItemIDs)
77
        {
78
            if (FItemRow* Row = ItemTable->FindRow<FItemRow>(ItemID, TEXT("Preload")))
79
            {
80
                if (!Row->Icon.IsValid())  // 还没加载
81
                {
82
                    PathsToLoad.Add(Row->Icon.ToSoftObjectPath());
83
                }
84
            }
85
        }
86

87
        if (PathsToLoad.Num() > 0)
88
        {
89
            FStreamableManager& Manager = UAssetManager::GetStreamableManager();
90
            Manager.RequestAsyncLoad(
91
                PathsToLoad,
92
                FStreamableDelegate::CreateLambda(
93
                    [PathsToLoad]()
94
                    {
95
                        UE_LOG(LogTemp, Log, TEXT("预加载了 %d 个道具图标"),
96
                               PathsToLoad.Num());
97
                    }
98
                )
99
            );
100
        }
101
    }
102

103
    // ---------- 卸载不需要的资产（背包关闭时） ----------
104
    void UnloadUnusedItemAssets(const TArray<FName>& StillVisibleItemIDs)
105
    {
106
        // 构造"仍然需要"的资产路径集合
107
        TSet<FSoftObjectPath> KeepPaths;
108
        for (FName ItemID : StillVisibleItemIDs)
109
        {
110
            if (FItemRow* Row = ItemTable->FindRow<FItemRow>(ItemID, TEXT("Unload")))
111
            {
112
                KeepPaths.Add(Row->Icon.ToSoftObjectPath());
113
            }
114
        }
115

116
        // 遍历当前已加载的所有图标，不在 Keep 集合中的就卸载
117
        // ⚠️ 实际项目中通常依赖 Asset Manager 的引用计数 + GC 自动管理
118
        // 手动卸载资产边界的资产反而容易出悬空指针问题
119
        // 正确的卸载策略见 13.5.3
120
    }
121
};

1
// ===== UAssetManager：全局资产的"索引 + 生命周期管理器" =====
2
//
3
// UAssetManager 是 UE 的全局单例（继承自 UObject），负责：
4
//
5
// 1. Primary Asset 标签体系
6
//    → 每种资产类型定义一个 PrimaryAssetType（如 "Weapon", "Monster", "Quest"）
7
//    → 每个资产实例有一个 PrimaryAssetId（如 "Weapon:AK47"）
8
//    → 通过标签快速查找、批量操作
9
//
10
// 2. StreamableManager —— 异步加载引擎
11
//    → 按优先级排队加载资产
12
//    → 支持批量请求 + 完成回调
13
//    → 支持加载取消
14
//
15
// 3. Bundle 系统 —— 分组管理
16
//    → 一个 Primary Asset 可以有多个 Bundle（如 "Gameplay" / "UI" / "HD"）
17
//    → 按需加载不同 Bundle 中的子资产
18
//
19
// 4. 卸载策略
20
//    → 引用计数跟踪——不再被引用的资产可以被 GC 回收
21
//    → 主动 UnloadPrimaryAsset
22

23
// ---------- 注册 Primary Asset 类型 ----------
24
// 通常在 DefaultEngine.ini 或项目的 Asset Manager 子类中配置：
25
//
26
// [/Script/Engine.AssetManagerSettings]
27
// +PrimaryAssetTypesToScan=(PrimaryAssetType="Weapon",...)
28
// +PrimaryAssetTypesToScan=(PrimaryAssetType="Monster",...)
29
// +PrimaryAssetTypesToScan=(PrimaryAssetType="Quest",...)
30

31
// 或者——创建自定义 Asset Manager 子类（推荐）：
32
UCLASS()
33
class UMyAssetManager : public UAssetManager
34
{
35
    GENERATED_BODY()
36

37
public:
38
    virtual void StartInitialLoading() override
39
    {
40
        Super::StartInitialLoading();
41

42
        // 引擎启动时——预扫描所有 Primary Asset
43
        // 这是"知道游戏里有哪些资产"的步骤，不是加载它们
44
        ScanPrimaryAssetTypesFromConfig();
45
    }
46

47
    // 在 DefaultGame.ini 中配置 Asset Manager 类：
48
    // [/Script/Engine.Engine]
49
    // AssetManagerClassName=/Script/MyGame.MyAssetManager
50
};

1
// ===== StreamableManager 完整 API =====
2
UCLASS()
3
class UAssetLoader : public UGameInstanceSubsystem
4
{
5
    GENERATED_BODY()
6

7
public:
8
    // ---------- ① 单个资产异步加载 ----------
9
    void LoadWeaponAsync(FName WeaponID)
10
    {
11
        FSoftObjectPath Path = GetWeaponPath(WeaponID);
12

13
        FStreamableManager& Manager = UAssetManager::GetStreamableManager();
14
        // ⚠️ RequestAsyncLoad 返回 TSharedPtr<FStreamableHandle>——不是裸指针！
15
        //    这是智能指针包装，用于防止加载句柄悬空和内存泄漏
16
        TSharedPtr<FStreamableHandle> Handle = Manager.RequestAsyncLoad(
17
            Path,
18
            FStreamableDelegate::CreateUObject(this, &UAssetLoader::OnWeaponLoaded)
19
        );
20

21
        // 可以保存 Handle——用于后续取消加载或查询进度
22
        if (Handle.IsValid())
23
        {
24
            ActiveHandles.Add(Handle);
25
        }
26
    }
27

28
    UFUNCTION()
29
    void OnWeaponLoaded()
30
    {
31
        UE_LOG(LogTemp, Log, TEXT("武器资产加载完成！"));
32
    }
33

34
    // ---------- ② 批量异步加载 ----------
35
    void LoadMultipleAssets(const TArray<FSoftObjectPath>& Paths)
36
    {
37
        FStreamableManager& Manager = UAssetManager::GetStreamableManager();
38

39
        TSharedPtr<FStreamableHandle> Handle = Manager.RequestAsyncLoad(
40
            Paths,
41
            FStreamableDelegate::CreateLambda(
42
                [Paths]()
43
                {
44
                    UE_LOG(LogTemp, Log, TEXT("%d 个资产加载完成"), Paths.Num());
45
                }
46
            )
47
        );
48
    }
49

50
    // ---------- ③ 同步加载（⚠️ 仅用于极特殊场景） ----------
51
    void LoadSynchronously_LastResort(FSoftObjectPath Path)
52
    {
53
        FStreamableManager& Manager = UAssetManager::GetStreamableManager();
54

55
        // SynchronousLoad 会阻塞当前线程直到加载完成——可能卡数百毫秒！
56
        // 绝对不要在 Tick 或 BeginPlay 中调用！
57
        // 仅适用于：关卡加载阶段（已经有 Loading 画面了）
58
        Manager.SynchronousLoad(Path);
59
    }
60

61
    // ---------- ④ 加载进度查询 ----------
62
    float GetLoadProgress() const
63
    {
64
        float TotalProgress = 0.0f;
65
        int32 Count = 0;
66

67
        for (TSharedPtr<FStreamableHandle> Handle : ActiveHandles)
68
        {
69
            if (Handle.IsValid())
70
            {
71
                TotalProgress += Handle->GetLoadProgress();  // 0.0 ~ 1.0
72
                Count++;
73
            }
74
        }
75
        return Count > 0 ? TotalProgress / Count : 1.0f;
76
    }
77

78
    // ---------- ⑤ 取消加载 ----------
79
    void CancelAllLoading()
80
    {
81
        for (TSharedPtr<FStreamableHandle> Handle : ActiveHandles)
82
        {
83
            if (Handle.IsValid() && Handle->IsActive())
84
            {
85
                Handle->CancelHandle();  // 取消——已加载的不回滚，未加载的不再加载
86
            }
87
        }
88
        ActiveHandles.Empty();
89
    }
90

91
    // ---------- ⑥ 预加载——按标签加载一组资产 ----------
92
    void PreloadWeaponAssets()
93
    {
94
        UAssetManager& Manager = UAssetManager::Get();
95

96
        // 找出所有 PrimaryAssetType = "Weapon" 的资产 ID
97
        TArray<FPrimaryAssetId> WeaponIds;
98
        Manager.GetPrimaryAssetIdList(FPrimaryAssetType(TEXT("Weapon")), WeaponIds);
99

100
        // 异步批量预加载——启动时就发出请求
101
        Manager.LoadPrimaryAssets(
102
            WeaponIds,
103
            TArray<FName>(),  // 加载所有 Bundle
104
            FStreamableDelegate::CreateLambda(
105
                [WeaponIds]()
106
                {
107
                    UE_LOG(LogTemp, Log, TEXT("预加载了 %d 个武器"), WeaponIds.Num());
108
                }
109
            )
110
        );
111
    }
112

113
private:
114
    TArray<TSharedPtr<FStreamableHandle>> ActiveHandles;
115

116
    FSoftObjectPath GetWeaponPath(FName WeaponID) const
117
    {
118
        // 从 DataTable 或 Asset Registry 中查到路径
119
        return FSoftObjectPath(FString::Printf(
120
            TEXT("/Game/Weapons/%s.%s"), *WeaponID.ToString(), *WeaponID.ToString()));
121
    }
122
};

1
// ===== UE 的资产卸载机制 =====
2
//
3
// 本质上依赖 GC 的标记-清扫：
4
//   1. 一个资产（UTexture / UStaticMesh / etc.）是 UObject
5
//   2. 当没有任何硬引用指向它时 → GC 会回收它
6
//   3. 软引用（TSoftObjectPtr）不阻止 GC —— 只存路径字符串
7
//
8
// 卸载的三种方式：
9

10
// ① 被动卸载——最常见的正确方式
11
void ReleaseAssetReference()
12
{
13
    // 将硬引用置空
14
    MyLoadedTexture = nullptr;
15

16
    // 所有指向这个纹理的 TObjectPtr / TStrongObjectPtr 都释放后
17
    // 下一次 GC 周期会自动回收它——你不需要手动干预
18
}
19

20
// ② 主动卸载——StreamableManager::Unload
21
void UnloadAsset(FSoftObjectPath Path)
22
{
23
    FStreamableManager& Manager = UAssetManager::GetStreamableManager();
24
    Manager.Unload(Path);  // 减少 StreamableManager 持有的引用计数
25
    // 下一次 GC 时如果没有其他硬引用，会被回收
26
}
27

28
// ③ Primary Asset 卸载——通过 Asset Manager
29
void UnloadPrimaryAsset(FPrimaryAssetId AssetId)
30
{
31
    UAssetManager& Manager = UAssetManager::Get();
32
    Manager.UnloadPrimaryAsset(AssetId);
33
}
34

35
// ⚠️ 强制垃圾回收（GC）——谨慎使用！
36
void ForceGarbageCollection()
37
{
38
    // CollectGarbage 会遍历整个 UObject 图——耗时可能几百毫秒！
39
    // 只在明确的"关卡切换"或"主菜单"等大场景切换时调用
40
    GEngine->ForceGarbageCollection(true);  // true = 完全清扫
41

42
    // 或者用更轻量的增量式 GC（UE5）
43
    // 增量 GC 自动运行，每帧做一点——不需要手动调用
44
}
45

46
// ===== 常见错误：以为 TSoftObjectPtr::Get() 会"持有"资产 =====
47
void BadAssetLifecycle()
48
{
49
    TSoftObjectPtr<UTexture2D> SoftIcon = GetSoftIcon();
50

51
    // 加载资产
52
    UTexture2D* LoadedIcon = SoftIcon.LoadSynchronous();
53

54
    // ✗ 错误想法：SoftIcon 现在"拥有"这个纹理——GC 不会回收
55
    // ✓ 事实：SoftIcon 只是一条路径——它不对 LoadedIcon 增加任何引用！
56
    //         如果没有其他硬引用,GC 随时可能回收 LoadedIcon
57

58
    // ✓ 正确做法：用 TStrongObjectPtr 持有加载后的资产
59
    // ⚠️ 局部变量 TObjectPtr 对 GC 无保护作用——GC 只认 UPROPERTY() 标记的成员
60
    //    函数栈上的局部变量对 UHT/GC 完全不可见，必须用 TStrongObjectPtr
61
    TStrongObjectPtr<UTexture2D> HeldIcon(LoadedIcon);
62
    // HeldIcon 存在期间，LoadedIcon 不会被 GC 回收
63
}

1
// ===== Level Streaming 两种模式 =====
2
//
3
// ① World Partition（UE5 新一代）：
4
//    - 世界被自动划分为 Grid Cell
5
//    - 每个 Cell 独立成为一个 Streaming 单元
6
//    - 根据距离自动加载/卸载
7
//    - 支持 Data Layer（逻辑层——如"烧毁前/烧毁后"）
8
//    - 适合：大型开放世界（> 4km²）
9
//
10
// ② 传统 Level Streaming（UE4 继承）：
11
//    - 手动划分子关卡（Sub-Level）
12
//    - C++ 或蓝图控制加载/卸载
13
//    - 适合：室内场景、地牢、独立的战斗区域
14

15
// ---------- 传统 Level Streaming C++ API ----------
16
UCLASS()
17
class ULevelStreamingManager : public UWorldSubsystem
18
{
19
    GENERATED_BODY()
20

21
public:
22
    // ① 按路径加载子关卡
23
    void LoadSubLevel(FName LevelName)
24
    {
25
        // 构造关卡路径
26
        FString LevelPath = FString::Printf(
27
            TEXT("/Game/Maps/SubLevels/%s"), *LevelName.ToString());
28

29
        // 异步加载
30
        UGameplayStatics::LoadStreamLevel(
31
            GetWorld(),
32
            FName(*LevelPath),          // 关卡路径
33
            true,                        // bMakeVisibleAfterLoad——加载完就显示
34
            false,                       // bShouldBlockOnLoad——不阻塞主线程！
35
            FLatentActionInfo()          // Latent Action 信息（蓝图用）
36
        );
37
    }
38

39
    // ② 卸载子关卡
40
    void UnloadSubLevel(FName LevelName)
41
    {
42
        FString LevelPath = FString::Printf(
43
            TEXT("/Game/Maps/SubLevels/%s"), *LevelName.ToString());
44

45
        UGameplayStatics::UnloadStreamLevel(
46
            GetWorld(),
47
            FName(*LevelPath),
48
            FLatentActionInfo(),
49
            false  // bShouldBlockOnUnload
50
        );
51
    }
52

53
    // ③ 在玩家位置周围流式加载
54
    void StreamAroundPlayer()
55
    {
56
        if (!GetWorld()) return;
57

58
        APlayerController* PC = GetWorld()->GetFirstPlayerController();
59
        if (!PC) return;
60

61
        FVector PlayerLocation = PC->GetPawn() ?
62
                                 PC->GetPawn()->GetActorLocation() :
63
                                 FVector::ZeroVector;
64

65
        // 遍历所有已注册的 StreamingLevel
66
        for (ULevelStreaming* StreamingLevel :
67
             GetWorld()->GetStreamingLevels())
68
        {
69
            // 计算关卡包围盒与玩家的距离
70
            // ⚠️ ULevelStreaming 没有 LevelBounds 成员！关卡包围盒来自关卡内部的
71
            //    ALevelBounds Actor。如果关卡尚未加载，需通过 World Composition 或
72
            //    预先配置的 Bounds 数据获取。此处简化：从已加载关卡中查找 ALevelBounds
73
            FBox LevelBounds(ForceInit);
74
            if (ULevel* LoadedLevel = StreamingLevel->GetLoadedLevel())
75
            {
76
                // ALevelBounds 是引擎自动放置在每个关卡中的包围盒 Actor
77
                for (AActor* Actor : LoadedLevel->Actors)
78
                {
79
                    if (ALevelBounds* Bounds = Cast<ALevelBounds>(Actor))
80
                    {
81
                        LevelBounds = Bounds->GetComponentsBoundingBox();
82
                        break;
83
                    }
84
                }
85
            }
86

87
            float DistToPlayer = LevelBounds.IsValid ?
88
                FMath::Sqrt(LevelBounds.ComputeSquaredDistanceToPoint(PlayerLocation)) :
89
                StreamingDistance + 1.0f;  // 无包围盒数据时跳过
90

91
            if (DistToPlayer < StreamingDistance)
92
            {
93
                if (!StreamingLevel->IsLevelLoaded())
94
                {
95
                    StreamingLevel->SetShouldBeLoaded(true);
96
                }
97
                if (!StreamingLevel->IsLevelVisible())
98
                {
99
                    StreamingLevel->SetShouldBeVisible(true);
100
                }
101
            }
102
            else if (DistToPlayer > UnloadDistance)
103
            {
104
                StreamingLevel->SetShouldBeLoaded(false);
105
            }
106
        }
107
    }
108

109
    // ④ 检测关卡加载状态
110
    bool IsLevelLoaded(FName LevelName) const
111
    {
112
        FString LevelPath = FString::Printf(
113
            TEXT("/Game/Maps/SubLevels/%s"), *LevelName.ToString());
114

115
        ULevelStreaming* Level = UGameplayStatics::GetStreamingLevel(
116
            GetWorld(), FName(*LevelPath));
117

118
        return Level ? Level->IsLevelLoaded() : false;
119
    }
120

121
    UPROPERTY(EditDefaultsOnly)
122
    float StreamingDistance = 20000.0f;  // 200 米内加载
123

124
    UPROPERTY(EditDefaultsOnly)
125
    float UnloadDistance = 30000.0f;     // 300 米外卸载
126
};
127

128
// ---------- Data Layer（UE5 World Partition 专属） ----------
129
// Data Layer 不是通过 C++ API 直接控制，而是通过 World Partition 的
130
// DataLayerManager 在编辑器中配置。C++ 侧的典型用法：
131

132
#if WITH_EDITOR
133
void ConfigureDataLayers()
134
{
135
    // 在编辑器中：
136
    // 1. 创建 Data Layer Asset：Burned / Unburned
137
    // 2. 将关卡中的 Actor 分配到对应 Data Layer
138
    // 3. 在 GameMode 或 WorldSubsystem 中动态切换：
139

140
    // UE5 运行时通过 UDataLayerManager 切换
141
    // if (UDataLayerManager* DLManager = UDataLayerManager::Get(GetWorld()))
142
    // {
143
    //     DLManager->SetDataLayerState(BurnedLayer,
144
    //         EDataLayerState::Activated);
145
    // }
146
}
147
#endif

1
// ===== Level Streaming 中的资产引用陷阱 =====
2

3
// 陷阱 1：一个子关卡中硬引用了另一个子关卡的 Actor
4
UCLASS()
5
class ASubLevelActor : public AActor
6
{
7
public:
8
    UPROPERTY(EditAnywhere)
9
    TObjectPtr<AActor> ActorInAnotherLevel;  // ✗ 跨关卡硬引用！
10
    // 当另一个子关卡被卸载时——这个指针变成悬空指针！
11
    // 当另一个子关卡被重新加载时——这是另一个不同的 Actor 实例！
12
};
13
// ✓ 修复：用 FName 或 FGuid 标识 + 运行时查找
14
UPROPERTY(EditAnywhere)
15
FName OtherActorTag;  // 存储标签，运行时通过 TActorRange 查找
16

17
// 陷阱 2：子关卡卸载后——其中的 UObject 引用全部失效
18
// 如果你的背包 UI 引用了子关卡中的某个 Actor——
19
// 子关卡卸载后，UI 中的 TObjectPtr 变成 nullptr（GC 回收了旧实例）
20
// 重新加载子关卡后，新实例的地址与旧的不同——你的指针依然是 nullptr！
21
//
22
// ✓ 修复：用 Subsystem 或 GameInstance 持有跨关卡数据
23
//   子关卡卸载前将数据写入 Subsystem，加载后从 Subsystem 恢复