虚幻引擎C++游戏框架指南

为什么要为 UE5 游戏逻辑写对 C++

在 Unreal Engine 5 (UE 5.4+) 中为游戏编写 C++ 时，仅写出能编译的类并不够。为了让类型进入引擎的反射系统，属性能暴露给编辑器与蓝图，行为能跨模块调用，我们需要严格遵守反射宏规则、类命名约定、Gameplay 框架角色划分以及模块依赖声明。任何遗漏——例如忘记包含生成的头文件、遗漏 GC 追踪宏，或者在 Build.cs 中缺少模块依赖——都会导致编辑器中无法识别类型、垃圾回收误删对象，或在链接阶段直接报错。

这个技能的核心工作流

该技能围绕 UE5 原生游戏框架，帮你正确编写和验证 C++ 代码：

• 按类型前缀命名：A 表示 Actor 派生，U 表示 UObject/组件派生，F 为普通结构体，E 为枚举，I 为接口。前缀必须与基类匹配。
• 声明反射宏：在类上方使用 UCLASS()，类体第一行写 GENERATED_BODY()，并在头文件的最后一行 #include "ClassName.generated.h"。
• 暴露数据与行为：使用 UPROPERTY 暴露给编辑器和蓝图（并用于 GC 追踪），使用 UFUNCTION 暴露可调用的行为。
• 构造函数中创建组件：使用 CreateDefaultSubobject 创建子对象，并设置 RootComponent。
• 明确框架角色：AGameModeBase 负责规则和默认类；APawn / ACharacter 是可控身体；APlayerController 是玩家意志；UActorComponent 是可复用行为。
• 声明模块依赖：在 *.Build.cs 中添加所需的模块依赖（例如 EnhancedInput），否则会出现链接错误。

适用边界与注意点

该技能专注于 C++ 类与反射的基础。它不负责处理面向设计师的可视化逻辑（应由蓝图相关技能处理）、玩家输入绑定细节，或 AI 逻辑（应由行为树相关技能处理）。

需要注意的常见坑包括：generated.h 必须放在 include 列表最后；GENERATED_BODY() 必须放在类体第一行；原生 UObject* 必须用 UPROPERTY 或 UE5 的 TObjectPtr 管理，否则 GC 可能销毁对象；Live Coding 仅处理函数体，对头文件和宏的修改需要完整重启并重编译；类前缀写错会破坏 UHT；重写 BeginPlay / Tick 等函数时必须调用 Super::。