UObject
自动关联目录:UObject
UObject 是 UE 里几乎所有引擎对象的基类。它带来的不是"继承一个基类"这么简单,而是一整套运行时服务:反射、GC、序列化、网络复制、编辑器集成。
一句话定位:继承 UObject 本质上是把对象的生命周期与类型信息交给引擎代管。你换来编辑器可见、蓝图可调、自动 GC、自动复制;代价是必须遵守一套 C++ 之外的规则。
本页是 Core 的第一篇,讲"对象本身";反射细节见 反射与 UHT,回收细节见 GC 与对象生命周期,存档见 序列化与存档。
反射
反射信息由 UHT(Unreal Header Tool) 在编译前扫描头文件生成 *.generated.h 与 *.gen.cpp。
| 宏 | 作用 |
|---|---|
UCLASS() | 类参与反射,可被蓝图继承、可被 GC |
USTRUCT() | 结构体参与反射,可用于蓝图与复制 |
UPROPERTY() | 字段可被序列化、复制、编辑器显示、且计入 GC 引用 |
UFUNCTION() | 函数可被蓝图调用、可作为 RPC、可绑定到委托 |
常见说明符:
| 说明符 | 含义 |
|---|---|
EditAnywhere / VisibleAnywhere | 编辑器可改 / 仅可见 |
BlueprintReadWrite / BlueprintReadOnly | 蓝图读写权限 |
Replicated / ReplicatedUsing=OnRep_X | 网络复制与回调 |
Transient | 不序列化 |
Instanced | 作为对象实例而非引用 |
Category="..." | 编辑器分组 |
没有 UPROPERTY() 的成员对引擎是"不存在"的:不会被 GC 追踪、不会序列化、不会复制。
GC
UE 的 GC 是追踪式、可达性分析,从"根集合"出发扫描引用链。
根集合(Root Set)
├── 被 AddToRoot 的对象
├── 被引擎持有的(World、GameInstance…)
└── 通过 UPROPERTY 引用链可达的对象| 要点 | 说明 |
|---|---|
| 判定依据 | 从根出发是否可达 |
引用必须标 UPROPERTY | 裸指针不参与引用图 |
| 容器也支持 | TArray<UObject*> 作为 UPROPERTY 会被追踪 |
| 手动保活 | AddToRoot / RemoveFromRoot、TStrongObjectPtr |
| 手动销毁 | MarkAsGarbage、Actor 用 Destroy() |
| 强制回收 | CollectGarbage / TryCollectGarbage(有卡顿,慎在运行时调用) |
经典崩溃:UObject* 存在非 UPROPERTY 成员里 → 被回收 → 访问野指针。判据是 IsValid()(UE5 里它同时检查非空与未被标记为垃圾)。
序列化
- 对象的
UPROPERTY字段会被自动序列化(存档、资源、复制) - 自定义序列化:
Serialize(FArchive&),但要自己处理版本 - 版本兼容:
FArchive的ArVer与自定义CustomVersion
详见 序列化与存档。
对象树:Outer 与 Package
每个 UObject 都有一个 Outer(外层对象),串起来构成一棵树。这棵树不是装饰,它决定了序列化单位与 GC 作用域。
Package(/Game/Blueprints/BP_Test)
└── BP_Test(UBlueprint)
└── GeneratedClass
└── DefaultObject(CDO)| 概念 | 说明 |
|---|---|
GetOuter() | 直接外层 |
GetOutermost() | 最外层(通常是 Package) |
Package | 序列化的单位,也是加载/卸载的粒度 |
GetFName() | 对象名(FName,哈希后) |
GetPathName() | 完整路径,如 /Game/Blueprints/BP_Test.BP_Test |
StaticClass() / GetClass() | 类信息(UClass*) |
FindObject / LoadObject / StaticLoadObject | 按路径查找/加载 |
Outer 选错最常见的后果是"对象跟着 Package 一起被卸载"。比如把运行时创建的对象 Outer 设成某个资源包,资源包一卸载对象就没了——运行时对象应该挂在 GameInstance、World 或一个稳定的 Subsystem 上。
创建
| 方式 | 适用 | 时机限制 |
|---|---|---|
NewObject<T>(Outer) | 创建普通 UObject | 任意(构造完成后) |
CreateDefaultSubobject<T>(Name) | 创建默认子对象(组件) | 只能在构造函数里 |
SpawnActor<T>() | 生成 Actor | 需要有效的 World |
DuplicateObject | 复制已有对象 | 任意 |
NewNamedObject / StaticConstructObject_Internal | 高级用法 | 一般不用 |
// 构造函数里
AMyActor::AMyActor()
{
PrimaryActorTick.bCanEverTick = false;
Mesh = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("Mesh"));
RootComponent = Mesh;
}
// 运行时
UMyObj* Obj = NewObject<UMyObj>(GetTransientPackage()); // 临时对象
UMyObj* Owned = NewObject<UMyObj>(this); // 挂在当前对象下CreateDefaultSubobject 的名字参数在同一个类里必须唯一,重复会断言。
构造流程
StaticConstructObject_Internal
→ 分配内存(走引擎分配器)
→ 构造 C++ 对象(构造函数跑在这里)
→ 属性初始化(从 CDO 拷贝默认值)
→ PostInitProperties()
→ (从磁盘加载时)Serialize 覆盖属性
→ PostLoad()| 回调 | 时机 | 常见用途 |
|---|---|---|
| 构造函数 | 对象创建 | 只设默认值 |
PostInitProperties | 属性初始化后 | 依赖默认值的初始化 |
PostLoad | 从磁盘反序列化后 | 数据迁移、旧资产修正 |
BeginPlay(Actor) | 进入游戏 | 游戏逻辑 |
BeginDestroy | GC 确定销毁 | 释放外部资源 |
FinishDestroy | 释放前最后一刻 | 一般不动 |
构造函数会在这些时刻被跑:引擎启动时建 CDO、编辑器打开类、运行时 NewObject、PIE 启动、热重载。所以它必须无副作用——不访问 World、不访问 Subsystem、不注册到全局容器。
CDO
每个 UCLASS 都有一个 Class Default Object(CDO):类的一份默认实例,作为所有实例的"默认值来源"。
GetDefault<T>()取 CDO- 构造函数里设的值就是 CDO 的值
- 蓝图类的默认值覆盖 C++ 的 CDO
- 序列化只存"与 CDO 的差异",所以 CDO 变了,已存资产/存档的读取结果也会变
理解 CDO 能解释很多现象:为什么改了构造函数默认值,已有蓝图实例不一定跟着变;为什么 UPROPERTY 的默认值要写在构造函数而不是 BeginPlay;为什么改默认值后要重新保存资产。
对象标记(Object Flags)
| 标记 | 含义 |
|---|---|
RF_Transient | 不存盘(对应 Transient 说明符) |
RF_Public | 可从包外引用(蓝图可见) |
RF_Standalone | 即使无人引用也不被 GC |
RF_MarkAsNative | 引擎原生对象 |
RF_ClassDefaultObject | 这是 CDO |
RF_ArchetypeObject | 蓝图模板对象 |
RF_NeedLoad / RF_NeedPostLoad | 加载流程内部标记 |
Obj->SetFlags(RF_Transient); // 运行时临时对象,不参与存档
Obj->ClearFlags(RF_Standalone);调试时打印标记能快速定位"为什么这个对象没被回收":RF_Standalone 或 AddToRoot 是最常见的两个原因。
常用 API 速查
| API | 作用 |
|---|---|
Cast<T>(Obj) / CastChecked<T> | 安全向下转换(CastChecked 失败即断言) |
Obj->IsA<UMyClass>() | 类型判断 |
IsValid(Obj) | 非空且未被标记待销毁 |
Obj->GetName() / GetPathName() | 名称与路径 |
Obj->GetWorld() | 所属 World(UObject 上是虚函数,非 Actor 可能为 null) |
StaticFindObject / FindObjectFast | 按名字查找 |
Obj->Rename(NewName, NewOuter) | 改名或换 Outer |
Obj->Modify() | 标记被修改(编辑器撤销系统) |
代价
| 收益 | 代价 |
|---|---|
| 自动 GC | 必须理解引用规则,否则对象凭空消失 |
| 反射与编辑器集成 | 每个类有 UClass 元数据;构造更慢 |
| 序列化与复制 | 属性遍历开销,字段越多越贵 |
| 蓝图互操作 | 头文件写法受限(见 反射与 UHT) |
不要为了"统一管理"把什么都做成 UObject。纯数据、高频临时对象用 USTRUCT 或普通 C++ 类,留给 UObject 的应该是"引擎需要认识它"的那些。
常见坑
| 坑 | 说明 |
|---|---|
| 裸指针持有 UObject | 无引用边,随机被回收 |
| 构造函数里做游戏逻辑 | 会被跑很多次,且此时 World 未就绪 |
构造函数里 NewObject | 应用 CreateDefaultSubobject |
| 运行时对象 Outer 设成了资源包 | 资源卸载时对象一起没 |
用 != nullptr 代替 IsValid | 待销毁对象指针非空但不可用 |
| 改默认值没重新保存资产 | 编辑器与磁盘不一致 |
在 BeginDestroy 里访问其它 UObject | 销毁顺序无保证 |
把 UObject 放进 TSharedPtr | 两套生命周期打架 |
DuplicateObject 忘记指定 Outer | 复制出来的对象无人持有,随即被回收 |