写 UE C++ 时如何正确使用反射宏、容器、委托、字符串…

在 Unreal Engine C++ 中编写涉及 UPROPERTY/UFUNCTION/UCLASS、TArray/TMap、委托、FString/FName/FText、GC 与智能指针、UE_LOG、子系统等代码时，提供符合 UE 反射与内存模型的正确写法。

适用场景

解决思路

1. 先阅读 `.agents/ue-project-context.md` 获取引擎版本、编码规范与项目规则；注意 UE5 用 `TObjectPtr<>` 替代 UE4 的裸 `UObject*`，结构体中用 `GENERATED_BODY()` 替代 `GENERATED_USTRUCT_BODY()`。
2. 若需求不明确，先确认用户需要哪一块：宏与反射、容器、委托、字符串、内存与 GC、日志、子系统。
3. 所有 UE 反射宏都必须在类/结构体内写 `GENERATED_BODY()` 并包含对应的 `.generated.h`。
4. UCLASS 按需使用说明符：`Blueprintable`（允许蓝图子类化）、`BlueprintType`（可作蓝图变量）、`Abstract`（不可实例化）、`NotBlueprintable`（禁止蓝图子类化）、`Config=<Name>`（从 `<Name>.ini` 加载 UPROPERTY(Config)）、`Transient`（不保存/序列化）、`Within=<OuterClass>`（限定 Outer 类型）。
5. UPROPERTY 按用途选择说明符：`EditAnywhere`/`VisibleAnywhere`/`EditDefaultsOnly` 控制编辑可见性，`BlueprintReadWrite`/`BlueprintReadOnly` 控制蓝图访问，`Category` 分组，`ReplicatedUsing=OnRep_X` 复制回调，`Transient` 不序列化但 GC 仍跟踪，`SaveGame` 持久化，`meta=(ClampMin=..., ClampMax=...)` 限制范围。
6. UFUNCTION 按用途选择：`BlueprintCallable`、`BlueprintPure`、`BlueprintNativeEvent`（C++ 提供 `_Implementation`）、`BlueprintImplementableEvent`（蓝图必须实现）、`Server`/`Client`/`NetMulticast` 配合 `Reliable`/`WithValidation` 定义 RPC（分别实现 `_Implementation` 与 `_Validate`）、`Exec` 定义控制台命令（可用于 PC、Pawn、HUD、GameMode、GameInstance、CheatManager）。
7. USTRUCT 使用 `USTRUCT(BlueprintType)` + `GENERATED_BODY()`；DataTable 行结构体继承 `FTableRowBase`。UENUM 使用 `UENUM(BlueprintType)` + `enum class : uint8`，枚举项用 `UMETA(DisplayName=...)`。
8. TArray 操作：`Add`/`Emplace`（原地构造避免拷贝）/`Reserve` 预分配；`Contains`、`Find`（缺失返回 `INDEX_NONE`）、`FindByPredicate`；`Sort` 传 lambda；`Remove` 保序 O(n)、`RemoveAtSwap` O(1) 但打乱顺序；不要在 ranged-for 中增删元素，倒序遍历删除。
9. TMap 操作：`Add`、`FindOrAdd`（缺失则插入默认值）、`Find`（缺失返回 nullptr）、`Contains`、`Remove`，用 `TPair` 遍历。TSet 操作：`Add`、`Contains`、`Intersect`、`Union`。
10. TOptional 用 `IsSet()`、`GetValue()`、`Get(默认值)`、`Reset()`。TVariant 用 `Set<T>`、`IsType<T>`、`Get<T>`，遍历时用 `Visit(TOverloaded{...})` 并提供显式重载（`LexToString(V)` 在 V 为 FString 时会失败）。
11. 委托按场景选择：`DECLARE_DELEGATE`（单播内部回调）、`DECLARE_MULTICAST_DELEGATE`（多播内部事件）、`DECLARE_DYNAMIC_DELEGATE`（蓝图可赋值的单播）、`DECLARE_DYNAMIC_MULTICAST_DELEGATE`（蓝图可绑定的多播，最常用）。
12. 委托声明放在 UCLASS 之前的文件作用域；动态多播委托作为 `UPROPERTY(BlueprintAssignable)` 成员。绑定用 `BindUObject`/`BindLambda`，单播用 `ExecuteIfBound`；多播用 `AddUObject` 返回 `FDelegateHandle`、`Broadcast`、`Remove(H)`；动态多播用 `AddDynamic`/`RemoveDynamic`/`Broadcast`。
13. 字符串类型选择：`FName` 用于标识符/资源名/标签（O(1) 整数比较、不可变）；`FString` 用于通用字符串/文件路径（O(n) 比较、可变）；`FText` 用于玩家可见文本（本地化）。
14. FString 用 `FString::Printf(TEXT("..."), ...)` 格式化，`UE_LOG` 中用 `*Msg` 解引用为 `TCHAR*`，`FCString::Atoi` 转整数。FText 用 `LOCTEXT`（需在同一翻译单元定义 `LOCTEXT_NAMESPACE` 并 `#undef`）或 `NSLOCTEXT`，格式化用 `FText::Format` + `FText::AsNumber`。转换：`Name.ToString()`、`FName(*Str)`、`FText::FromString(Str)`、`Text.ToString()`。
15. 内存与 GC：UPROPERTY 成员 UObject 指针在 UE5 用 `TObjectPtr<>`（GC 跟踪、支持延迟加载）；非 UObject 的普通 C++ 类型才用 `TSharedPtr`/`TWeakPtr`（用 `Weak.Pin()` 提升）；非拥有引用用 `TWeakObjectPtr`（GC 后变 null，用 `IsValid()` 检查）。
16. GC 根：`AddToRoot()`/`RemoveFromRoot()` 谨慎使用；非 UObject 的 C++ 类持有 UObject 引用时优先继承 `FGCObject`，实现 `AddReferencedObjects` 与 `GetReferencerName`，成员用 `TObjectPtr<>`（UE 5.3+ 增量 GC 下裸指针会崩溃）。
17. 日志：用 `DECLARE_LOG_CATEGORY_EXTERN` + `DEFINE_LOG_CATEGORY`（单文件可用 `DEFINE_LOG_CATEGORY_STATIC`），`UE_LOG(LogX, Log/Warning/Error, TEXT("..."), ...)`，条件日志用 `UE_CLOG`。Verbosity 从高到低：Fatal/Error/Warning 始终可见，Log 非 Shipping 可见，Verbose 需 `-LogCmds`。
18. 子系统：`UGameInstanceSubsystem`（跨关卡持久、非每玩家）、`UWorldSubsystem`（每世界重建）、`ULocalPlayerSubsystem`（跨关卡持久、每玩家）、`UEngineSubsystem`（整个会话持久）。重写 `Initialize`/`Deinitialize` 做初始化与清理；通过 `GetGameInstance()->GetSubsystem<T>()`、`GetWorld()->GetSubsystem<T>()`、`GetLocalPlayer()->GetSubsystem<T>()`、`GEngine->GetEngineSubsystem<T>()` 访问。
19. 复制属性：UPROPERTY 说明符与 `GetLifetimeReplicatedProps` 两者缺一不可；在 `GetLifetimeReplicatedProps` 中调用 `Super::` 后用 `DOREPLIFETIME` 或 `DOREPLIFETIME_CONDITION`（条件如 `COND_None`、`COND_OwnerOnly`、`COND_SkipOwner`、`COND_SimulatedOnly`、`COND_InitialOnly`）；`ReplicatedUsing=OnRep_X` 需配套 `UFUNCTION() void OnRep_X();`。
20. 条件编译：编辑器专用属性用 `#if WITH_EDITOR` 包裹（Shipping 构建剥离），开发期调试代码用 `#if !UE_BUILD_SHIPPING` 包裹。
21. 避免常见错误：裸 `UObject*` 成员必须加 `UPROPERTY()` 并用 `TObjectPtr<>`；不要在 ranged-for 中增删 TArray，倒序遍历删除；不要对 UObject 用 `TSharedPtr`（GC 与引用计数冲突）；不要漏写 `GetLifetimeReplicatedProps`；UE5 结构体不要用 `GENERATED_USTRUCT_BODY()`；`AddDynamic` 绑定的函数必须是 `UFUNCTION`。

适用边界 · 注意事项

• 模块构建配置（Build.cs、模块依赖、include 路径、PCH）请参考 ue-module-build-system。
• Actor/Component 架构（生命周期、生成、Tick 组、组件设置）请参考 ue-actor-component-architecture。