UObject 与反射系统

原理：宏 + 代码生成

C++ 本身没有完整的运行时反射。UE 的做法是：

1. 开发者用宏给需要暴露的类型和成员打标记，并附加说明符 (Specifier) 和元数据 (Metadata)。
2. 编译前 UHT 解析头文件，收集这些信息，生成 *.generated.h 等胶水代码。
3. 运行时每个对象都能通过 GetClass() 拿到描述自己类型的 UClass，其中列出被标记的属性 (UProperty) 和函数 (UFunction)。

下图表示一个带反射的头文件从编写到运行时被各系统使用的流程。

flowchart LR
  H["MyObject.h<br/>UCLASS / UPROPERTY / UFUNCTION"] --> UHT["UHT 预处理"]
  UHT --> G["MyObject.generated.h<br/>生成代码"]
  H --> C["C++ 编译器"]
  G --> C
  C --> RT["运行时 UClass<br/>+ 类默认对象 CDO"]
  RT --> GC["垃圾回收"]
  RT --> SER["序列化"]
  RT --> ED["编辑器细节面板"]
  RT --> BP["蓝图"]
  RT --> NET["网络复制"]

只有加了说明符宏的属性和函数会出现在 UClass 中；类里仍可以有不参与反射的纯原生成员。

头文件格式要求

#pragma once
#include "CoreMinimal.h"
#include "MyObject.generated.h"   // 必须是最后一个 #include

UCLASS()
class MYPROJECT_API UMyObject : public UObject
{
    GENERATED_BODY()               // UCLASS 与 USTRUCT 都必需
};

坑：UHT 只支持 C++ 的一个最小子集。用自定义 #ifdef 包裹 UCLASS 内容时，UHT 会忽略不含 WITH_EDITOR 或 WITHEDITORONLY_DATA 的宏——条件编译的反射成员容易出错。

类默认对象 (Class Default Object, CDO)

每个 UClass 维护一个 CDO：由类构造函数生成、之后不再修改的“默认模板”。CDO 应视为只读。它带来一个实用特性——默认值变更的自动传播：若关卡里已放置的实例某属性值等于旧 CDO 的值，加载时会被更新为新 CDO 的值；若实例改过该值，则保留。官方例子：AEnemy 默认 Health 由 100 改为 150，所有仍为 100 的敌人变为 150，而单独设为 500 的 Enemy_3 保持 500。

对象创建规则

• UObject 不支持带参构造函数，引擎启动时调用默认构造函数；没有默认构造函数将无法编译。
• 构造函数应很轻量，只设默认值和子对象；Actor 与组件的初始化逻辑放到 BeginPlay()。
• 运行时用 NewObject 创建，构造函数里用 CreateDefaultSubobject 创建组件/子对象。
• 永远不要用 new/delete：UObject 由引擎内存管理和垃圾回收，手动管理会破坏内存。
• 对象在构造函数调用前已被整体清零（包括非 UProperty 的原生成员）。

UObject 带来的功能

USTRUCT 具有同样的反射和序列化能力，但是值类型，不参与垃圾回收。

UPROPERTY 常用说明符

语法：UPROPERTY([说明符...], [meta(键=值...)]) 类型 变量名;

元数据（如 ClampMin、EditCondition、ExposeOnSpawn、DisplayName）只存在于编辑器，游戏逻辑不得读取元数据。字符串有三种：FString（可变字符数组）、FName（全局字符串表中不可变、大小写不敏感的引用，传递更高效但难操作）、FText（本地化）。

UFUNCTION 常用说明符

其他反射工具

• TSubclassOf<T>：类型安全的 UClass 引用，常用来让策划在蓝图里选择要生成的武器类。
• 接口 (Interface)：让不相关的类实现同一组行为。
• UE 智能指针库 (TSharedPtr/TWeakPtr/TUniquePtr/TSharedRef) 用于非 UObject 的普通 C++ 对象；文档明确智能指针不用于 UObject。
• 构建目标可通过 NativePointerMemberBehaviorOverride 禁止 UCLASS/USTRUCT 使用原生指针成员，此时 UHT 报错，应改用 TObjectPtr。

取舍与常见坑

• 代价：每个反射类型都要经过 UHT 和生成代码，头文件写法受限；反射只覆盖被标记的成员。
• 不需要这些功能的纯数据或算法类，不必也不应继承 UObject（文档："并非所有情况都需要或适合"）。
• 修改默认值传播依赖“值是否等于旧默认值”：若实例碰巧手动设成了与旧默认值相同的值，也会被当作“未修改”而更新。

GEA 的视角：为什么 C++ 引擎需要自己做反射（卷 II 17.1、17.3.2、17.9.2）

GEA 列出运行时对象模型通常要提供的能力，其中存档与持久化需要 RTTI、反射和抽象构造（不硬编码类名就能创建实例），而 C++ 原生不支持反射（GEA 把 C# 作为反射语言、C/C++ 作为非反射语言的例子），所以引擎必须自己加：

• 反射数据是类内容的运行时描述：类名、数据成员及其类型和偏移、成员函数。有了它就能写通用的序列化系统，而不必让每个类手写 SerializeIn/Out。
• GEA 列举的生成方式包括：用 #define 宏包裹数据成员提取信息、由派生类重写返回反射数据的虚函数、为每个类手写反射结构，或其他巧妙办法。本页的 UCLASS/UPROPERTY + UHT 代码生成属于"宏 + 工具生成"这一路（对比归纳）。
• 类工厂：C++ 不能凭名字或 id 实例化类，序列化系统总要有一张"类名/id → 创建函数"的表。UE 中由 UClass 承担这一角色（对比归纳）。
• 默认值与健壮性：GEA 推荐的生成器格式是键值对：只存与默认值不同的属性，不认识的键忽略，缺少的键用默认值。本页记录的 UProperty 序列化规则（等于默认值的不写出、新增属性取新 CDO 默认值、删除的属性被静默忽略）与之一致，CDO 默认值的传播也对应 GEA 的兽人生命值例子。详见 世界块数据格式与生成器。