用途:为 Unreal Engine 5.x 的 C++ 开发提供专家级规范与最佳实践,帮助编写健壮、高性能且符合 Epic 编码标准的代码。适用场景包括编写 Actor、Component 或 UObject 派生类,优化性能关键代码,排查内存泄漏与垃圾回收问题,实现暴露给蓝图的功能,使用反射系统(UCLASS、USTRUCT、UFUNCTION),以及管理资源加载与软引用。不适用于纯蓝图项目、5.x 之前的版本、非 Unreal 引擎或与 Unreal 开发无关的任务。
主要能力与要点:UObject 与 GC 方面,UObject* 成员变量必须用 UPROPERTY() 以便被垃圾回收器追踪;需要在 UObject 图之外保持根引用时可用 TStrongObjectPtr<>,但一般更推荐 addToRoot();理解 IsValid() 与 nullptr 的区别,IsValid() 能安全处理 pending kill 状态。反射系统方面,用 UCLASS()、USTRUCT()、UENUM()、UFUNCTION() 将类型暴露给反射与蓝图;尽量少用 BlueprintReadWrite,对不应被 UI/关卡蓝图逻辑改写的状态优先用 BlueprintReadOnly。性能方面,默认关闭 Tick(bCanEverTick = false),仅在必要时启用,优先使用定时器(GetWorldTimerManager())或事件驱动逻辑;避免在热循环中使用 Cast<T>(),在 BeginPlay 中缓存引用;数据密集的非 UObject 类型使用 F 结构体以减少开销。
命名约定(严格):模板前缀 T(如 TArray、TMap),UObject 前缀 U,AActor 前缀 A,Slate 控件前缀 S,结构体前缀 F,枚举前缀 E,接口前缀 I,布尔变量前缀 b。
常见模式:组件查找避免在 Tick 中调用 GetComponentByClass,应在 PostInitializeComponents 或 BeginPlay 中完成并用 check() 在开发期快速失败;用接口解耦系统,调用前用 Implements<UInteractable>() 检查,再通过 IInteractable::Execute_OnInteract 执行;大型资源避免硬引用(如 TSubclassOf),改用 TSoftClassPtr 或 TSoftObjectPtr,必要时用 LoadSynchronous() 或 StreamableManager 异步加载。
调试:使用 UE_LOG 配合自定义日志类别(DEFINE_LOG_CATEGORY_STATIC),用 GEngine->AddOnScreenDebugMessage 输出屏幕消息,Visual Logger 对 AI 调试很有用,可实现 IVisualLoggerDebugSnapshotInterface。
提交前检查清单:该 Actor 是否真的需要 Tick,能否改为定时器;所有 UObject* 成员是否都用 UPROPERTY 包裹;硬引用是否造成加载链,能否改为软指针;是否在 EndPlay 中清理了已绑定的委托。
限制:仅在任务明确匹配上述范围时使用;输出不能替代针对具体环境的验证、测试或专家评审;若缺少必要输入、权限、安全边界或成功标准,应停止并请求澄清。