unreal-engine-cpp-pro

Unreal Engine C++ Pro

Expert-level guidelines for developing with Unreal Engine 5 using C++. Focuses on writing robust, performant, and standard-compliant code.

When to Use

• Developing C++ code for Unreal Engine 5.x projects
• Writing Actors, Components, or UObject-derived classes
• Optimizing performance-critical code
• Debugging memory leaks or garbage collection issues
• Implementing Blueprint-exposed functionality
• Working with Unreal's reflection system (UCLASS, USTRUCT, UFUNCTION)
• Managing asset loading and soft references

Pre-Flight：新建 C++ 类/文件时的上下文感知

仅在创建新 .h/.cpp 文件时执行（修改现有文件跳过此步骤）：

1. 读同目录现有头文件：读取目标目录下 1-2 个已有的 .h 文件，学习 include 模式、命名风格、UCLASS specifier 习惯。
2. 不做全项目扫描：项目结构已在项目上下文 Rule 中声明。
3. 不确定的 API 走验证流程：见下方白名单和 ue-mcp-workflow Rule。

C++ API 免查白名单

以下高频 API 可直接使用，无需 grep 或查文档：

• Actor: SetActorLocation, SetActorRotation, GetActorLocation, GetActorRotation, SetActorHiddenInGame, K2_SetActorLocation, SetActorTransform, GetTransform, DestroyActor, SetLifeSpan, GetInstigator, GetOwner
• Component: FindComponentByClass, GetComponentByClass, SetVisibility, SetHiddenInGame, SetRelativeLocation, SetWorldLocation, SetRelativeRotation, SetWorldRotation, RegisterComponent, DestroyComponent
• Player: GetPlayerController, GetPlayerPawn, GetPlayerCharacter, GetPlayerCameraManager
• Framework: GetWorld, GetGameMode, GetGameState, GetGameInstance, SpawnActor, SpawnActorDeferred, IsValid
• UI: SetText, AddToViewport, RemoveFromParent, GetDesiredSize
• Timer: SetTimer, SetTimerByFunctionName, ClearTimer, ClearAllTimersForObject, GetTimerElapsed
• Debug: PrintString, DrawDebugLine, DrawDebugSphere, FlushPersistentDebugLines, UE_LOG, AddOnScreenDebugMessage
• Math: FMath::Clamp, FMath::Lerp, FMath::RandRange, FMath::Abs, FRotator, FVector, FTransform

不在此表中的 API → grep <UE5_ENGINE_PATH>\Engine\Source\Runtime\ 确认签名，grep 无结果则 context7 查文档。

Core Principles

1. UObject & Garbage Collection

• Always use UPROPERTY() for UObject* member variables to ensure GC tracking
• Use TStrongObjectPtr<> for root references outside UObject graph
• Use IsValid() over raw nullptr — handles pending-kill safely
• Use TWeakObjectPtr for non-owning references that may become invalid