Unlua源码解析
自动关联目录:Unlua源码解析
UnLua 要解决的核心问题是:如何在不手写绑定代码的前提下,让 Lua 访问 UE 的一切。答案是用反射——引擎已经有一套完整的类型信息(UClass/UFunction/UProperty),用它自动生成访问入口。
使用方式见 UnLua 指南。
层次
Lua 虚拟机(lua_State)
↑
绑定层(UnLua):UObject ↔ userdata,UFunction ↔ 可调用函数
↑
UE 反射(UClass / UFunction / FProperty)关键机制
| 机制 | 作用 |
|---|---|
| UObject → userdata | Lua 里用 userdata 表示 UObject,元表按 UClass 生成 |
| 反射驱动的元方法 | __index 查 UProperty / UFunction,找不到就报 nil |
| UFunction 调用封装 | 从 Lua 栈取值 → 填参数缓冲区 → ProcessEvent |
| 容器绑定 | TArray / TMap / TSet 绑定成带方法的 userdata |
| 结构体绑定 | UScriptStruct 同样用反射访问字段 |
| 委托绑定 | 多播委托转成可 Add/Remove 的对象 |
| GC 联动 | Lua 侧引用与 UObject 生命周期的协调 |
一次 Lua 调 UFUNCTION 的过程
Lua: self:SetHealth(50)
→ 元表 __index 找到 "SetHealth" → 生成一个可调用的闭包
→ 调用时:
1. 根据 UFunction 的 FProperty 列表,从 Lua 栈取参并转换
2. 申请参数缓冲区(FMemory / FFrame 的 Parms)
3. UObject::ProcessEvent(Function, Parms)
4. 有返回值则压回 Lua 栈性能开销主要在第 2、3 步:每次调用都要按反射元数据逐个字段做类型转换并准备参数缓冲区。这就是为什么"循环里逐次调用"很贵。
UObject 生命周期的处理
这是最容易出问题的地方:
| 情况 | 处理 |
|---|---|
| Lua 持有 UObject | userdata 存弱引用或指针,需判断有效性 |
| UObject 被 GC 回收 | Lua 侧再访问就是野指针 |
| Lua 侧持有导致无法回收 | 需要避免强引用滞留 |
工程上的对策:
- Lua 侧用
IsValid(obj)判断后再用 - 不要把 UObject 存进长期存活的 Lua 全局表
- 对象销毁时(
Destruct)主动清理
热更新
| 环节 | 说明 |
|---|---|
| 模块重载 | 重新 require(清 package.loaded) |
| 状态迁移 | 旧模块里的运行时状态需要显式迁移 |
| 函数替换 | 元表里的函数更新即生效 |
| 旧引用 | 已注册的委托/定时器仍指向旧函数,必须先反注册 |
热更最难的部分不是替换代码,而是处理"已注册的回调"和"已有的运行时状态"。这也是为什么 Destruct 必须成对清理。
阅读源码的建议顺序
| 顺序 | 模块 |
|---|---|
| 1 | Lua 环境创建与 lua_State 管理 |
| 2 | UObject 与 userdata 的绑定(FUObjectToLua 一类结构) |
| 3 | UFunction 调用的参数编组(marshalling) |
| 4 | 容器与结构体的绑定 |
| 5 | 委托与事件 |
| 6 | 热更新与模块管理 |
常见坑(实现视角)
| 坑 | 说明 |
|---|---|
| 反射信息滞后 | 蓝图/热重载后元表可能未刷新 |
| 参数编组的类型不匹配 | 运行时报错或静默出错 |
| 容器元素为 UObject 时的生命周期 | 容易悬挂 |
| 大量创建临时 FName/FString | 转换开销 |
| 委托反注册遗漏 | 热更后重复绑定 |
许可协议:CC BY
作者:Davids
本文链接:https://hustjjd.github.io/c7be2e.html
更新于:2026年11月16日