1
// ===== .uproject：UE 项目的 JSON 描述文件 =====
2
//
3
// 位置：项目根目录 / MyProject.uproject
4
// 作用：告诉引擎——这个项目叫什么、依赖哪些模块和插件、关联哪个引擎版本
5
// 类型：纯 JSON——不需要编译，引擎启动时解析
6

7
// ---------- 完整的 .uproject 示例 ----------
8
/*
9
{
10
    "FileVersion": 3,
11
    "EngineAssociation": "5.4",            // 引擎版本——或 "{GUID}" 使用自定义引擎构建
12
    "Category": "Game",                     // 项目类别
13
    "Description": "My UE5 Game",
14

15
    // ★ 模块列表——项目的 C++ 模块（不含插件）
16
    "Modules": [
17
        {
18
            "Name": "MyProject",            // 模块名——必须与 .Build.cs / 目录名一致
19
            "Type": "Runtime",              // 模块类型（Runtime / Editor / Developer）
20
            "LoadingPhase": "Default"       // 加载时机（Default / PostConfigInit / PostEngineInit）
21
        },
22
        {
23
            "Name": "MyProjectEditor",
24
            "Type": "Editor",
25
            "LoadingPhase": "Default"
26
        }
27
    ],
28

29
    // ★ 插件列表——启用的插件
30
    "Plugins": [
31
        {
32
            "Name": "EnhancedInput",
33
            "Enabled": true
34
        },
35
        {
36
            "Name": "Niagara",
37
            "Enabled": true
38
        },
39
        {
40
            "Name": "ModelingToolsEditorMode",
41
            "Enabled": true,
42
            "SupportedTargetPlatforms": ["Win64"]   // 可选：限制目标平台
43
        }
44
    ]
45
}
46
*/
47

48
// ===== .uproject 关键字段 =====
49
//
50
// FileVersion：目前固定为 3
51
//
52
// EngineAssociation：
53
//   "5.4"           → 使用 Launcher 安装的 5.4 版本
54
//   "{1234-5678}"   → 使用注册表中对应的自定义源码构建
55
//   ""              → 空白——必须由外部指定（如命令行 -EngineDir=）
56
//
57
// Modules[].Type：
58
//   Runtime              → 随游戏包发布（最常用）
59
//   RuntimeNoCommandlet  → 运行时加载但不随 Commandlet 加载
60
//   UncookedOnly         → 仅未烘焙（Uncooked）状态下可用——打包烘焙时自动剥离（最常用的开发期类型）
61
//   DeveloperTool        → 命令行工具或非编辑器的独立开发期工具
62
//   Editor               → 仅编辑器加载
63
//   EditorNoCommandlet   → 编辑器中加载但 Commandlet 不加载
64
//
65
// Modules[].LoadingPhase：
66
//   Default              → 引擎初始化阶段加载（最常用）
67
//   PostConfigInit       → 配置系统初始化后加载
68
//   PostSplashScreen     → 启动画面显示后加载
69
//   PreEarlyLoadingScreen → 早期加载画面之前
70
//   PostEngineInit       → 引擎完全初始化后加载（适用于依赖引擎服务的模块）

1
// ===== Public vs Private 依赖的传播机制 =====
2
//
3
// 这是面试中考察"模块化理解"的核心考点。
4
//
5
// 场景：模块 A → 模块 B → 模块 C（B 依赖 C）
6
//
7
//   PublicDependency（B 公开依赖 C）：
8
//     B 的 Public 头文件中 include 了 C 的头文件
9
//     → A 需要能访问 C 的类型才能编译通过
10
//     → B 必须把 C 放在 PublicDependencyModuleNames 中
11
//     → UBT 会自动将 C 的 Public 路径和链接传递给 A
12
//
13
//   PrivateDependency（B 私有依赖 C）：
14
//     B 只在 Private/ 目录中使用 C
15
//     → A 不需要知道 C 的存在
16
//     → B 把 C 放在 PrivateDependencyModuleNames 中
17
//     → UBT 不会将 C 暴露给 A——A 编译时看不到 C 的头文件
18
//
19
// 经验法则（面试标准答案）：
20
//   "如果你的 Public 头文件 include 了某个模块的头文件 → 公开依赖它。
21
//    如果某个模块只在你 Private 实现中用 → 私有依赖它。
22
//    如果某个模块运行时可选加载 → DynamicallyLoaded。"
23

24
// ---------- 依赖传递示意图 ----------
25
//
26
//   A.Build.cs:
27
//     PublicDependencyModuleNames.Add("B");
28
//
29
//   B.Build.cs:
30
//     PublicDependencyModuleNames.Add("C");    // ← 公开依赖
31
//     PrivateDependencyModuleNames.Add("D");   // ← 私有依赖
32
//
33
//   编译 A 时：
34
//     A 可以看到：B（公开依赖）、C（B 的公开依赖传递）
35
//     A 看不到：D（B 的私有依赖——不透传）

1
// ===== .Target.cs：定义"构建什么产物" =====
2
//
3
// 位置：Source/MyProject.Target.cs（Game） / Source/MyProjectEditor.Target.cs（Editor）
4
// 继承：TargetRules
5
// 每个 .Target.cs 对应一个输出——一个游戏项目通常有至少两个 Target
6

7
// ---------- Game Target（游戏客户端 + 独立服务器）----------
8
/*
9
using UnrealBuildTool;
10
using System.Collections.Generic;
11

12
public class MyProjectTarget : TargetRules
13
{
14
    public MyProjectTarget(ReadOnlyTargetRules Target) : base(Target)
15
    {
16
        Type = TargetType.Game;              // ★ 核心：定义产物类型
17

18
        DefaultBuildSettings = BuildSettingsVersion.V4;  // UE5 推荐 V4
19
        IncludeOrderVersion = EngineIncludeOrderVersion.Unreal5_4;
20

21
        // ★ 列出这个 Target 包含的模块——通常是项目主模块
22
        ExtraModuleNames.AddRange(new string[] {
23
            "MyProject"                      // 主游戏模块
24
        });
25
    }
26
}
27
*/
28

29
// ---------- Editor Target（编辑器）----------
30
/*
31
public class MyProjectEditorTarget : TargetRules
32
{
33
    public MyProjectEditorTarget(ReadOnlyTargetRules Target) : base(Target)
34
    {
35
        Type = TargetType.Editor;            // ★ 编辑器构建
36
        DefaultBuildSettings = BuildSettingsVersion.V4;
37

38
        ExtraModuleNames.AddRange(new string[] {
39
            "MyProject",                     // 主游戏模块
40
            "MyProjectEditor"                // 编辑器专用扩展模块
41
        });
42
    }
43
}
44
*/
45

46
// ---------- Server Target（专用服务器——不渲染、无客户端逻辑）----------
47
/*
48
public class MyProjectServerTarget : TargetRules
49
{
50
    public MyProjectServerTarget(ReadOnlyTargetRules Target) : base(Target)
51
    {
52
        Type = TargetType.Server;
53
        DefaultBuildSettings = BuildSettingsVersion.V4;
54
        bUsesSteam = true;                   // 使用 Steam 网络
55

56
        ExtraModuleNames.AddRange(new string[] {
57
            "MyProject"
58
        });
59
    }
60
}
61
*/
62

63
// ---------- Client Target（纯客户端——不含服务器代码）----------
64
/*
65
public class MyProjectClientTarget : TargetRules
66
{
67
    public MyProjectClientTarget(ReadOnlyTargetRules Target) : base(Target)
68
    {
69
        Type = TargetType.Client;
70
        DefaultBuildSettings = BuildSettingsVersion.V4;
71

72
        ExtraModuleNames.AddRange(new string[] {
73
            "MyProject"
74
        });
75
    }
76
}
77
*/

1
// ===== TargetType：五种构建产物 =====
2
//
3
// ┌──────────────┬──────────────────────────────────┬──────────────────────┐
4
// │ TargetType    │ 用途                              │ 包含内容               │
5
// ├──────────────┼──────────────────────────────────┼──────────────────────┤
6
// │ Game          │ 打包发布的游戏 + 独立服务器模式       │ 全部——渲染 + 服务器逻辑  │
7
// │ Editor        │ 编辑器中开发                      │ 全部 + 编辑器工具       │
8
// │ Server        │ 专用服务器（Dedicated Server）      │ 仅服务器逻辑——无渲染     │
9
// │ Client        │ 纯客户端（配合专用服务器使用）         │ 仅客户端——无服务器逻辑   │
10
// │ Program       │ 独立命令行工具                     │ 精简引擎——无渲染        │
11
// └──────────────┴──────────────────────────────────┴──────────────────────┘
12
//
13
// 面试常见追问："Game vs Server 的区别？"
14
// 标准答案：
15
//   Game = 同时包含客户端 + 服务器代码，可以作为 Listen Server。
16
//   Server = 剥离了所有渲染和客户端逻辑——只保留网络权威代码。
17
//   专用服务器的二进制体积可以比 Game 小 40%~60%。
18
//   云部署用 Server Target：更小的磁盘占用、更少的内存开销、更少的攻击面。
19

20
// ===== DefaultBuildSettings 版本速查 =====
21
//
22
// BuildSettingsVersion.V2 → UE4 遗留行为
23
// BuildSettingsVersion.V3 → UE5.0~5.2 默认
24
// BuildSettingsVersion.V4 → UE5.3+ 推荐——包含更多弃用 API 警告和严格检查
25
//
26
// 经验法则：新项目一律使用 V4。

1
// ===== UBT（Unreal Build Tool）：编译的总指挥 =====
2
//
3
// UBT 是一个 C# 程序（位于 Engine/Binaries/DotNET/UnrealBuildTool/）
4
// 每次你在 VS/Rider 中编译或运行 Build.bat 时，实际上是在调用 UBT。
5
//
6
// 编译全流程（6 步）：
7
//
8
// ① 收集 Target：
9
//    UBT 读取命令行指定的 Target 文件（如 MyProjectEditor.Target.cs）
10
//    → 确定构建产物类型（Game / Editor / Server / Client / Program）
11
//
12
// ② 解析模块依赖图：
13
//    UBT 递归读取所有 .Build.cs 文件
14
//    → 构建完整的模块依赖有向无环图（DAG）
15
//    → 检测循环依赖——报错退出
16
//
17
// ③ 调用 UHT（Unreal Header Tool）：
18
//    UHT 扫描所有头文件中的 UCLASS / USTRUCT / UFUNCTION / UPROPERTY 宏
19
//    → 为每个带反射的类型生成 .generated.h 和 .gen.cpp
20
//    → 这是 "UE C++ 平行宇宙" 的入口——见 Ch2
21
//
22
// ④ 平台适配：
23
//    UBT 根据目标平台选择对应的工具链：
24
//      Windows → Visual C++ (MSVC)
25
//      Mac/iOS → Xcode / Apple Clang
26
//      Linux   → Clang
27
//      Android → NDK（Clang）
28
//      Console → 对应 SDK 编译器
29
//
30
// ⑤ 并行编译：
31
//    UBT 将编译任务分发到多个工作线程
32
//    → Unity Build：多个 .cpp 合并成一个大文件编译（减少重复解析头文件）
33
//    → 增量编译：只重编译修改过的 .cpp 和依赖它的翻译单元
34
//
35
// ⑥ 链接：
36
//    链接器将所有 .obj 和 .lib 合并为最终的二进制文件
37
//      Game   → MyProject.exe（Windows）/ MyProject（Linux/Mac）
38
//      Editor → UnrealEditor.dll（模块化——引擎是 DLL）
39
//      Server → MyProjectServer.exe
40

41
// ---------- UBT 关键概念 ----------
42
//
43
// Unity Build（加速编译）：
44
//   将 N 个 .cpp 合并成一个翻译单元 → 只解析一次公共头文件 → 显著加速
45
//   缺点：修改一个 .cpp → 整个 Unity Bundle 全部重编译
46
//   关闭：.Build.cs 中 bUseUnity = false
47
//
48
// Adaptive Unity Build（自适应联合编译）：
49
//   只把"不常修改"的 .cpp 打包进 Unity Build
50
//   "频繁修改"的 .cpp 单独编译——既享受加速，又不增加增量编译成本
51
//   这是 UE5 的默认行为——通常不需要手动干预
52
//
53
// PCH（Precompiled Header——预编译头）：
54
//   将常用的稳定头文件（CoreMinimal.h 等）预编译为二进制缓存
55
//   每个 .cpp 编译时直接加载 PCH——跳过解析数十万行稳定代码
56
//   UE5 推荐 PCHUsageMode.UseExplicitOrSharedPCHs

1
// ===== 编译错误排查速查 =====
2
//
3
// ① "fatal error C1083: 无法打开包括文件: 'MyModule/MyClass.generated.h'"
4
//    原因：UHT 未生成 .generated.h——检查 UCLASS/USTRUCT 宏是否正确
5
//    解决：确保 #include "MyClass.generated.h" 是头文件的最后一个 include
6
//
7
// ② "unresolved external symbol"
8
//    原因：缺少模块依赖——你使用了某个模块的类型但未在 .Build.cs 中声明
9
//    解决：添加 PublicDependencyModuleNames 或 PrivateDependencyModuleNames
10
//
11
// ③ "module 'X' could not be found"
12
//    原因：模块未在 .uproject / .uplugin 的 Modules 列表中注册
13
//    解决：在 .uproject 或 .uplugin 中声明该模块
14
//
15
// ④ "circular dependency detected"
16
//    原因：两个模块互相依赖（A→B 且 B→A）
17
//    解决：重新设计模块边界——提取公共接口到第三个模块 C（A→C, B→C）
18
//
19
// ⑤ "PCH file not found"
20
//    原因：预编译头策略与项目配置不匹配
21
//    解决：检查 .Build.cs 中 PCHUsage 的值——新建模块用 UseExplicitOrSharedPCHs

1
// ===== UE 模块的目录约定 =====
2
//
3
// 标准结构（以 MyModule 为例）：
4
//
5
// Source/MyModule/
6
// ├── MyModule.Build.cs          ← 编译规则（C#）
7
// ├── Public/                    ← ★ 公开头文件——外部模块可以 include
8
// │   ├── MyModule.h             ← 模块接口（IModuleInterface 实现）
9
// │   ├── MyPublicActor.h        ← 对外暴露的类
10
// │   └── MyPublicTypes.h        ← 对外暴露的类型定义（USTRUCT / UENUM）
11
// ├── Private/                   ← ★ 私有实现——仅本模块可见
12
// │   ├── MyModule.cpp           ← IMPLEMENT_MODULE 所在位置
13
// │   ├── MyPrivateActor.cpp     ← 内部实现
14
// │   └── Internal/              ← 子目录——进一步组织私有代码
15
// │       └── DetailHelper.h
16
//
17
// UBT 强制执行：
18
//   - Public/ 目录下的头文件 → 自动加入公开包含路径 → 下游模块可 include
19
//   - Private/ 目录下的头文件 → 只有本模块可 include → 下游模块无法访问
20
//   - 根目录（Source/MyModule/）下的文件 → 视同 Private（不推荐在此放头文件）
21

22
// ---------- 正确的跨模块 include 方式 ----------
23
//
24
// 模块 A 依赖模块 B（B 在模块 A 的 PublicDependencyModuleNames 中）
25
//
26
// A 的 Public 头文件中：
27
//   #include "BModule/SomePublicClass.h"  // ✓ 正确——B 的 Public 头文件
28
//   // 不需要写完整路径——UBT 已将 B/Public 加入 A 的包含路径
29
//
30
// A 的 Private 实现中：
31
//   #include "BModule/SomePublicClass.h"  // ✓ 同 Public 规则
32
//   // 你无法 include B 的 Private 头文件——编译器会报"找不到文件"

1
// ===== 什么时候应该创建新模块？ =====
2
//
3
// 一个游戏项目的代码全部放在主模块中 = 灾难：
4
//   - 编译时间随代码量线性增长——改一行等 60 秒
5
//   - 命名空间污染——所有类型在一个模块中
6
//   - 不能在运行时按需加载/卸载
7
//
8
// 模块拆分信号（满足任一即考虑拆分）：
9
//
10
//   ① 独立功能集 —— GAS 技能系统 / 背包系统 / 对话系统
11
//     → 拆分为独立模块：MyGame_AbilitySystem / MyGame_Inventory / MyGame_Dialogue
12
//
13
//   ② 不同加载时机 —— 一部分代码在 PostEngineInit 后才需要
14
//     → 后置模块可以延迟初始化——加速引擎启动
15
//
16
//   ③ 独立团队维护 —— 技能组和 UI 组各自维护自己的模块
17
//     → 模块边界 = 团队边界——减少合并冲突
18
//
19
//   ④ 可选功能 —— 某些功能在特定平台/版本中关闭
20
//     → 独立模块可以在运行时按需加载 (FModuleManager::LoadModule)
21
//
22
//   ⑤ 编辑器专用逻辑 —— 编辑器扩展不应该随游戏打包
23
//     → 拆分为 Editor 类型模块——Shipping 包中不存在
24

25
// ---------- 模块拆分实战：MyGame 项目架构 ----------
26
/*
27
Source/
28
├── MyGame.Target.cs                    ← Game Target
29
├── MyGameEditor.Target.cs              ← Editor Target
30
│
31
├── MyGame/                             ← ★ 主模块（Runtime）
32
│   ├── MyGame.Build.cs
33
│   ├── Public/
34
│   │   └── MyGame.h                   ← IMPLEMENT_PRIMARY_GAME_MODULE
35
│   └── Private/
36
│       └── MyGame.cpp
37
│
38
├── MyGame_AbilitySystem/               ← ★ 能力系统模块（Runtime）
39
│   ├── MyGame_AbilitySystem.Build.cs
40
│   │     PublicDependency:  MyGame_Core, GameplayAbilities
41
│   │     PrivateDependency: GameplayTags, GameplayTasks
42
│   ├── Public/
43
│   │   ├── MyGameAbilitySystem.h
44
│   │   ├── Abilities/                 ← 公开的能力基类
45
│   │   └── Attributes/                ← 公开的属性集
46
│   └── Private/
47
│       ├── MyGameAbilitySystem.cpp
48
│       └── Abilities/                 ← 具体能力实现
49
│
50
├── MyGame_Inventory/                   ← ★ 背包系统模块（Runtime）
51
│   ├── MyGame_Inventory.Build.cs
52
│   │     PrivateDependency: MyGame_Core
53
│   ├── Public/
54
│   │   ├── MyGameInventory.h
55
│   │   └── InventoryItem.h
56
│   └── Private/
57
│       └── ...
58
│
59
├── MyGame_Core/                        ← ★ 共享核心模块（Runtime）
60
│   ├── MyGame_Core.Build.cs
61
│   │     PublicDependency: Core, CoreUObject, Engine
62
│   ├── Public/
63
│   │   ├── MyGameCore.h
64
│   │   └── MyGameTypes.h              ← 跨模块共享的类型定义
65
│   └── Private/
66
│       └── ...
67
│
68
└── MyGameEditor/                       ← ★ 编辑器扩展模块（Editor）
69
    ├── MyGameEditor.Build.cs
70
    │     PrivateDependency: MyGame_Core, UnrealEd
71
    ├── Public/
72
    │   └── MyGameEditor.h
73
    └── Private/
74
        └── ...
75
*/

1
// ===== IModuleInterface：每个模块的 C++ 入口 =====
2
//
3
// 每个模块必须有一个实现 IModuleInterface 的类
4
// 这个类是模块的"生命周期管理者"——引擎在加载/卸载模块时调用它
5

6
#include "Modules/ModuleManager.h"
7

8
// ---------- 标准模块实现 ----------
9
// 位置：Source/MyModule/Private/MyModule.cpp
10

11
#include "MyModule.h"
12
#include "Modules/ModuleManager.h"
13

14
// ★ 将 FMyModule 注册为模块 "MyModuleName" 的实现类
15
//   模块名必须与 .uproject / .uplugin 中声明的 Name 一致
16
IMPLEMENT_MODULE(FMyModule, MyModuleName)
17

18
void FMyModule::StartupModule()
19
{
20
    // 模块加载时调用——引擎初始化阶段
21
    // 典型操作：
22
    //   - 注册全局资产类型（Asset Type）
23
    //   - 注册控制台命令（IConsoleManager::RegisterConsoleCommand）
24
    //   - 注册细节面板自定义（FPropertyEditorModule::RegisterCustomClassLayout）
25
    //   - 初始化模块级单例
26
    UE_LOG(LogTemp, Log, TEXT("MyModule: StartupModule"));
27
}
28

29
void FMyModule::ShutdownModule()
30
{
31
    // 模块卸载时调用——引擎关闭或手动 UnloadModule
32
    // 典型操作：
33
    //   - 注销控制台命令
34
    //   - 注销编辑器扩展
35
    //   - 销毁模块级单例
36
    UE_LOG(LogTemp, Log, TEXT("MyModule: ShutdownModule"));
37
}

1
// ===== FModuleManager：运行时模块管理 =====
2
//
3
// FModuleManager 是全局的模块注册表和加载器
4
// 它在引擎启动时读取所有 .uproject / .uplugin 的 Modules 列表
5
// 按 LoadingPhase 和依赖图决定加载顺序
6

7
#include "Modules/ModuleManager.h"
8

9
class FMyModuleUser
10
{
11
public:
12
    void DynamicModuleAccess()
13
    {
14
        // ---------- ① 检查模块是否已加载 ----------
15
        if (FModuleManager::Get().IsModuleLoaded("MyModule"))
16
        {
17
            UE_LOG(LogTemp, Log, TEXT("MyModule 已加载"));
18
        }
19

20
        // ---------- ② 强制加载模块 ----------
21
        // 如果模块尚未加载——触发加载（调用 StartupModule）
22
        // 如果已加载——直接返回
23
        // 如果模块不存在——触发断言（在 Development/Debug 构建中）
24
        IModuleInterface* Module = FModuleManager::Get().LoadModuleChecked("MyModule");
25

26
        // ---------- ③ 安全加载——返回 nullptr 而非崩溃 ----------
27
        IModuleInterface* ModulePtr = FModuleManager::Get().LoadModule("MyModule");
28
        if (ModulePtr)
29
        {
30
            // 模块存在并加载成功
31
        }
32

33
        // ---------- ④ 按接口获取模块指针 ----------
34
        // 典型模式：你的模块实现了一个自定义接口
35
        // 其他模块通过接口访问——不依赖具体类型
36
        IMyModuleInterface* MyInterface =
37
            FModuleManager::Get().LoadModuleChecked<IMyModuleInterface>("MyModule");
38
        MyInterface->DoSomething();
39
    }
40
};
41

42
// ===== 模块接口模式：对外暴露 API =====
43
// 位置：Source/MyModule/Public/IMyModuleInterface.h
44

45
#include "Modules/ModuleInterface.h"
46

47
class IMyModuleInterface : public IModuleInterface
48
{
49
public:
50
    // 纯虚接口——供外部模块调用
51
    virtual void DoSomething() = 0;
52
    virtual int32 GetSomeValue() const = 0;
53
};
54

55
// 在 MyModule.cpp 中实现：
56
#include "IMyModuleInterface.h"
57

58
class FMyModule : public IMyModuleInterface
59
{
60
public:
61
    virtual void StartupModule() override { /* ... */ }
62
    virtual void ShutdownModule() override { /* ... */ }
63

64
    // 实现自定义接口
65
    virtual void DoSomething() override
66
    {
67
        UE_LOG(LogTemp, Log, TEXT("Module API called"));
68
    }
69

70
    virtual int32 GetSomeValue() const override { return 42; }
71
};
72

73
// 注意：IMPLEMENT_MODULE 不直接支持接口类型检查
74
// 外部模块通过 GetModulePtr 获取指针后 static_cast 或使用 LoadModuleChecked

1
// ===== LoadingPhase：控制模块的初始化时机 =====
2
//
3
// 加载顺序（由早到晚）：
4
//
5
//   EarliestPossible    → 尽可能早——引擎最基础的设施
6
//   PostConfigInit      → 配置系统初始化后（可读取 .ini 配置）
7
//   PostSplashScreen    → 启动画面显示后（UI 模块可以开始初始化）
8
//   PreEarlyLoadingScreen
9
//   PreLoadingScreen    → 加载画面之前
10
//   PreDefault          → Default 之前——确保依赖链上前置模块先初始化
11
//   Default             → 默认加载阶段（80% 的模块用这个）
12
//   PostDefault         → Default 之后
13
//   PostEngineInit      → 引擎完全初始化后（所有引擎服务已就绪）
14
//
15
// 经验法则：
16
//   - Runtime 模块 99% 使用 Default
17
//   - 依赖 GameInstance 的模块 → PostEngineInit
18
//   - UI 模块在编辑器启动时就需要 → PostSplashScreen 或 Default
19
//   - 控制台命令注册 → PostConfigInit（尽早可用）

1
// ===== 陷阱 #1：Public 头文件中 include 了未声明为 PublicDependency 的模块 =====
2
// ✗ 模块 A 的 Public 头文件中 #include "SomeModule/SomeClass.h"
3
//   但 SomeModule 只写在 PrivateDependencyModuleNames 中
4
//   → 下游模块编译时报 "fatal error: 无法打开包括文件"
5
// ✓ 规则：任何在 Public 头文件中被 include 的模块 → 必须放在 PublicDependencyModuleNames
6

7
// ===== 陷阱 #2：循环模块依赖 =====
8
// ✗ 模块 A 的 .Build.cs：PublicDependencyModuleNames.Add("B")
9
//   模块 B 的 .Build.cs：PublicDependencyModuleNames.Add("A")
10
//   → UBT 直接报错——"circular dependency detected"
11
// ✓ 创建第三个模块 C：
12
//   A 和 B 都依赖 C（A→C, B→C）
13
//   把 A 和 B 共享的类型/接口下沉到 C
14

15
// ===== 陷阱 #3：模块未在 .uproject 中注册 =====
16
// ✗ 创建了新模块 MyNewModule（有 .Build.cs + IMPLEMENT_MODULE）
17
//   但忘记在 .uproject 的 Modules 数组中添加
18
//   → UBT 不编译这个模块——运行时 FModuleManager::LoadModule 返回 nullptr
19
// ✓ 在 .uproject 中添加：{ "Name": "MyNewModule", "Type": "Runtime", "LoadingPhase": "Default" }
20

21
// ===== 陷阱 #4：Public/Private 目录不存在 =====
22
// ✗ 创建了模块但未创建 Public/ 和 Private/ 目录
23
//   → UBT 能编译，但下游模块 include 头文件时需要写完整相对路径
24
//   → 破坏了 UE 的模块化约定——其他开发者找不到你的 API
25
// ✓ 始终创建 Public/（对外 API）和 Private/（内部实现）目录
26

27
// ===== 陷阱 #5：滥用 DynamicallyLoadedModuleNames =====
28
// ✗ 把所有"可能用到"的模块都放 DynamicallyLoaded → 运行时到处 LoadModule
29
//   → 启动时模块未加载 → 第一次访问时卡顿（加载 DLL + StartupModule）
30
//   → 模块可能被多次意外加载 —— 线程安全问题
31
// ✓ 只在真正"可选"且"不频繁使用"的模块上用 Dynamic 加载
32
//   大多数依赖直接用 PublicDependency 或 PrivateDependency
33

34
// ===== 陷阱 #6：Shipping 包中包含了 Editor 模块 =====
35
// ✗ 打包 Shipping 时 Editor 类型模块仍然被编译和链接
36
//   → 包体积膨胀 + 不必要的代码暴露 + 潜在的编辑器功能在客户端可用（作弊风险）
37
// ✓ Editor 模块的 Type 必须设为 "Editor"——UBT 自动排除
38
//   如果 Editor 逻辑混在 Runtime 模块中 → 用 #if WITH_EDITOR 条件编译隔离

1
Q: ".Build.cs 和 .Target.cs 的区别是什么？"
2
A: .Target.cs 定义"构建什么产物"——一个 .Target.cs 对应一个可执行文件或 DLL
3
   （Game / Editor / Server / Client / Program）。它描述的是整个构建产物的属性。
4
   .Build.cs 定义"一个模块怎么编译"——每个模块一个 .Build.cs，描述依赖关系、
5
   预编译头策略、编译宏等。关系：一个 Target 包含多个 Module，
6
   Module 通过 .Build.cs 声明"我需要哪些其他模块的头文件和链接库"。
7

8
Q: "PublicDependency 和 PrivateDependency 的区别？什么时候用哪个？"
9
A: PublicDependency：你的 Public 头文件中 include 了该模块的头文件
10
   → 下游模块也需要能访问该模块才能编译通过 → 必须声明为公开依赖。
11
   PrivateDependency：该模块只在你的 Private/ 实现中使用
12
   → 下游模块不需要知道 → 声明为私有依赖即可。
13
   判断标准：运行"下游模块能否只包含你的 Public 头文件就编译通过？"
14
   能 → 你的 Public 依赖配置正确。不能 → 缺少 PublicDependency。
15

16
Q: "UE 编译为什么这么慢？怎么加速？"
17
A: UE 编译慢的核心原因：① 巨型头文件链——CoreMinimal.h 展开后数十万行；
18
   ② 模板——TArray/TMap 等大量模板导致翻译单元膨胀；③ 宏——UHT 宏展开 +
19
   反射代码生成。加速手段：① Unity Build（多个 .cpp 合并编译）——减少重复解析；
20
   ② PCH（预编译头）——稳定头文件预编译；③ Incredibuild/FastBuild 分布式编译；
21
   ④ 合理模块拆分——只重编译修改到的模块；
22
   ⑤ 关闭不必要的模块依赖——Private 依赖不透传减少包含路径；
23
   ⑥ LiveCoding（Ctrl+Alt+F11）——运行时热重载 .cpp 修改，无需重启编辑器。