Unlua指南
自动关联目录:Unlua指南
面向使用的速查:怎么绑、怎么调、怎么覆写,以及哪些写法会踩坑。实现原理见 UnLua 源码解析。
绑定方式
| 方式 | 做法 |
|---|---|
| 蓝图绑定 | 蓝图里实现 UnLua Interface,填 GetModuleName 返回 Lua 文件路径 |
| C++ 绑定 | 类实现 IUnLuaInterface::GetModuleName() |
| 静态绑定 | 用 UnLua.Class("路径") 显式指定 |
命名约定:Content/Script/XXX.lua 对应模块名 XXX。
生命周期回调
local M = UnLua.Class()
function M:Initialize() -- 初始化(构造后)
end
function M:ReceiveBeginPlay() -- 覆写蓝图事件
end
function M:ReceiveTick(DeltaSeconds)
end
function M:ReceiveEndPlay()
end
function M:Destruct() -- 销毁前清理
-- 解绑委托、清定时器
end| 回调 | 时机 |
|---|---|
Initialize | 绑定完成 |
ReceiveBeginPlay / ReceiveTick / ReceiveEndPlay | 对应蓝图事件 |
Destruct | 对象销毁前 |
Destruct 里必须做清理:定时器、委托、协程,否则会回调到已销毁对象。
调用 UE API
-- 引擎静态函数
UE.UKismetSystemLibrary.PrintString(nil, "hello", true, false, FColor.Red, 2)
-- 构造函数
local Loc = UE.FVector(0, 0, 100)
local Rot = UE.FRotator(0, 0, 0)
-- 生成 Actor
local Actor = UE.UWorld.SpawnActor(self:GetWorld(), Class, Loc, Rot)
-- 容器
local Arr = UE.TArray(UE.FVector)
Arr:Add(UE.FVector(1,0,0))| 类型 | Lua 侧写法 |
|---|---|
FVector / FRotator / FTransform | UE.FVector(...) |
FName / FString / FText | 字符串通常可自动转换 |
UClass* | UE.UClassName 或 UE.LoadClass(...) |
| 枚举 | UE.EEnumName.Value |
| 结构体 | UE.FStructName() |
覆写蓝图函数
在 Lua 里实现同名函数即可覆写蓝图实现,需要调用原实现时用 self.Overridden.xxx(self, ...)。
function M:ReceiveBeginPlay()
self.Overridden.ReceiveBeginPlay(self) -- 调用蓝图原实现
self:InitFromConfig()
end委托与事件
self.Button.OnClicked:Add(self, M.OnClicked)
-- 记得在 Destruct 里 Remove
self.Button.OnClicked:Remove(self, M.OnClicked)多播委托的 Remove 非常容易忘,是热更后最常见的泄漏来源。
定时器
self.TimerHandle = UE.UKismetSystemLibrary.K2_SetTimerDelegate(
{self, M.OnTimer}, 1.0, true)
-- 销毁时
UE.UKismetSystemLibrary.K2_ClearTimerDelegate(self, {self, M.OnTimer})实践建议
| 建议 | 说明 |
|---|---|
| 用模块化的写法 | 一个 Lua 文件一个类,配套 require |
| 逻辑分层 | Lua 只做玩法,底层能力由 C++ 暴露成函数 |
| 批量传数据 | 减少跨语言调用次数 |
| 所有回调都要有反注册 | 定时器、委托、事件 |
| 加日志与断言 | Lua 出错常常静默失败 |
常见坑
| 坑 | 说明 |
|---|---|
| 函数名写错 | 不会报错,只是不生效(最难查的一类) |
忘记 self.Overridden | 蓝图原有逻辑被覆盖丢失 |
| 委托没反注册 | 热更后重复触发 |
| 每帧调用大量 UE API | 边界开销累积 |
| 在 Lua 里做重循环 | 应下移到 C++ |
许可协议:CC BY
作者:Davids
本文链接:https://hustjjd.github.io/558c8778.html
更新于:2026年11月16日