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 / FTransformUE.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++