---

name: unreal-engine-cpp-pro description: "Unreal Engine 5.x C++ 开发专家指南，涵盖 UObject 管理、性能模式和最佳实践。" risk: safe source: self date_added: "2026-02-27"

Unreal Engine C++ 专家

此技能提供使用 C++ 开发 Unreal Engine 5 的专家级指南。专注于编写健壮、高性能且符合标准的代码。

使用场景

在以下情况使用此技能：

• 为 Unreal Engine 5.x 项目开发 C++ 代码
• 编写 Actor、Component 或 UObject 派生类
• 优化 Unreal Engine 中性能关键代码
• 调试内存泄漏或垃圾回收问题
• 实现蓝图暴露功能
• 遵循 Epic Games 编码标准和约定
• 使用 Unreal 反射系统（UCLASS、USTRUCT、UFUNCTION）
• 管理资产加载和软引用

不适用场景：

• 纯蓝图项目（无 C++ 代码）
• 为 5.x 之前的 Unreal Engine 版本开发
• 使用非 Unreal 游戏引擎
• 任务与 Unreal Engine 开发无关

核心原则

1. UObject 与垃圾回收：

   • 始终对 UObject* 成员变量使用 UPROPERTY() 以确保被垃圾回收器 (GC) 跟踪。
   • 如果需要在 UObject 图之外保持根引用，使用 TStrongObjectPtr<>，但通常优先使用 addToRoot()。
   • 理解 IsValid() 检查与 nullptr 的区别。IsValid() 安全处理待销毁状态。

2. Unreal 反射系统：

   • 使用 UCLASS()、USTRUCT()、UENUM()、UFUNCTION() 将类型暴露给反射系统和蓝图。
   • 尽可能减少 BlueprintReadWrite；对不应被 UI/关卡蓝图逻辑覆盖的状态优先使用 BlueprintReadOnly。

3. 性能优先：

   • Tick：默认禁用 Tick（bCanEverTick = false）。仅在绝对必要时启用。优先使用定时器（GetWorldTimerManager()）或事件驱动逻辑。
   • 类型转换：避免在热循环中使用 Cast<T>()。在 BeginPlay 中缓存引用。
   • 结构体 vs 类：对数据密集的非 UObject 类型使用 F 结构体以减少开销。

命名约定（严格）

遵循 Epic Games 编码标准：

• 模板：前缀 T（如 TArray、TMap）。
• UObject：前缀 U（如 UCharacterMovementComponent）。
• AActor：前缀 A（如 AMyGameMode）。
• SWidget：前缀 S（Slate 控件）。
• 结构体：前缀 F（如 FVector）。
• 枚举：前缀 E（如 EWeaponState）。
• 接口：前缀 I（如 IInteractable）。
• 布尔值：前缀 b（如 bIsDead）。

常见模式

1. 健壮的组件查找

避免在 Tick 中使用 GetComponentByClass。在 PostInitializeComponents 或 BeginPlay 中执行。

void AMyCharacter::PostInitializeComponents() {
    Super::PostInitializeComponents();
    HealthComp = FindComponentByClass<UHealthComponent>();
    check(HealthComp); // Fail hard in dev if missing
}

2. 接口实现

使用接口解耦系统（如交互系统）。

// Interface call check
if (TargetActor->Implements<UInteractable>()) {
    IInteractable::Execute_OnInteract(TargetActor, this);
}

3. 异步加载（软引用）

避免对大型资产使用硬引用（UPROPERTY(EditDefaultsOnly) TSubclassOf<AActor>），它们会强制加载顺序。使用 TSoftClassPtr 或 TSoftObjectPtr。

UPROPERTY(EditAnywhere, BlueprintReadWrite)
TSoftClassPtr<AWeapon> WeaponClassToLoad;

void AMyCharacter::Equip() {
    if (WeaponClassToLoad.IsPending()) {
        WeaponClassToLoad.LoadSynchronous(); // Or use StreamableManager for async
    }
}

调试

• 日志：使用带自定义类别的 UE_LOG。

DEFINE_LOG_CATEGORY_STATIC(LogMyGame, Log, All);
UE_LOG(LogMyGame, Warning, TEXT("Health is low: %f"), CurrentHealth);

• 可视化调试：使用 DrawDebugLine、DrawDebugSphere 进行运行时可视化。
• 崩溃报告：使用 check()、ensure()、verify() 宏进行断言。

限制

• 此技能假设 Unreal Engine 5.x；旧版本 API 可能不同。
• 不涵盖蓝图可视化脚本。
• 不涵盖 Unreal 编辑器插件开发。
• 不涵盖网络复制的高级主题（需要专门的网络技能）。