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)进入游戏游戏逻辑
BeginDestroyGC 确定销毁释放外部资源
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复制出来的对象无人持有,随即被回收