工坊手册

主题

BindableEvent ​

概览 ​

字段值
KindUnit · 单位 Unit
Realmcommon

继承关系 ​

  • Unit（4 属性 / 25 函数 / 6 事件）
    • [BindableEvent]（1 属性 / 4 函数）

继承成员 ​

1 个来源 / 4 属性 / 25 函数 / 6 事件

BindableEvent 是纯逻辑的本地事件容器，自身不参与渲染与物理模拟。它通过 Event 信号暴露 Connect、Once、Wait 等监听方式，配合 Fire 可携带任意数量参数触发回调，常用于模块之间或同一单位层级内部的解耦通信。事件的生命周期随实例存在，监听与触发均在本地逻辑环境中完成。

适用场景 ​

当需要在场景内让多个系统订阅同一自定义通知，或在单位实例下组织内部信号时，可创建 BindableEvent 作为事件枢纽。例如技能管理器中为不同状态结果建立本地信号，供各能力逻辑挂接回调并派发触发。

使用要点 ​

通过 game:CreateUnit("BindableEvent", {}) 或 World:CreateUnit("BindableEvent", {}) 创建事件实例，随后在其上调用 Connect 方法注册监听函数，需要时用 Fire 携带任意参数触发；若只需响应一次可改用 Once，Wait 则用于挂起当前协程等待下一次触发并取得载荷。Connect 返回的 Connection 可在不再需要时调用 Disconnect 解除监听。

注意事项 ​

BindableEvent 只在本地逻辑层传播，不提供跨客户端或跨进程的通信能力。实例创建后应妥善持有，销毁后将无法再触发或监听。注意同一回调可能被重复注册，且 Wait 会阻塞当前协程，需避免在不可挂起的上下文中使用。

代码示例 ​

创建 BindableEvent 并用 Connect 监听消息 ​

lua
-- @runtime client
-- BindableEvent 是本地纯逻辑事件容器，不涉及渲染与物理，常用于模块间解耦通信
local notifyEvent = game:CreateUnit('BindableEvent', {})

-- Connect 注册长期监听：每次 Fire 都会同步触发回调，参数原样透传
local connection = notifyEvent:Connect(function(message)
    print('收到事件消息:', message)
end)

-- 触发事件，唤醒上方注册的监听器
notifyEvent:Fire('hello bindable event')

-- 使用完毕后主动断开连接，避免事件监听泄漏
connection:Disconnect()

使用 Once 注册一次性通知 ​

lua
-- @runtime client
-- 使用 Once 注册一次性监听：事件首次被 Fire 后自动断开，适合初始化或一次性通知
local oneShotEvent = game:CreateUnit('BindableEvent', {})

oneShotEvent:Once(function(payload)
    print('OnlyOnce 回调收到:', payload)
end)

-- 第一次触发会执行 Once 回调
oneShotEvent:Fire('first-payload')

-- 第二次触发时 Once 已自动断开，因此不会输出重复内容
oneShotEvent:Fire('second-payload')

属性 (1) ​

Name类型默认值说明
EventSignal-只读属性。表示 BindableEvent 对外暴露的事件信号对象，属于 Signal 类型，可用来查看或传递该事件对应的信号实例。

关联类型 ​

函数 (4) ​

Fire ​

签名：Fire(args?: Any) -> void

触发 BindableEvent 表示的事件。触发时传入的参数会按顺序传递给当前已注册的监听函数；不传参数时也可以直接调用。Fire 没有返回值。

参数类型说明
args?Any事件参数

返回值 void

示例代码

注册一次性监听并触发本地事件

lua
-- @runtime client
local notifyEvent = game:CreateUnit("BindableEvent", { Name = "关卡完成事件" })
notifyEvent:Once(function(message)
    print("收到本地事件:", message)
end)
notifyEvent:Fire("第一关已完成")

Connect ​

签名：Connect(func: Function) -> Connection (可用于断开监听的连接句柄)

为 BindableEvent 注册一个监听回调函数。当事件被触发时，func 会被调用，并接收触发时传入的参数。Connect 返回一个 Connection 类型句柄，可用来管理该监听。

参数类型说明
funcFunction事件触发时调用的监听函数

返回值 Connection (可用于断开监听的连接句柄)

示例代码

连接监听并在触发后断开

lua
-- @runtime client
-- 创建本地 BindableEvent，用于脚本内的事件广播
local evt = game:CreateUnit("BindableEvent", { Name = "任务完成事件" })
-- 使用 Connect 注册回调，事件触发时打印提示
local conn = evt:Connect(function()
    print("收到事件：任务完成")
end)
-- 触发一次事件，验证刚注册的回调已被执行
evt:Fire()
conn:Disconnect()

Once ​

签名：Once(func: Function) -> Connection (可用于提前断开监听的连接句柄)

注册一个只会在事件首次触发时执行一次的监听函数。执行过后该监听不会再响应后续触发；若在事件触发前希望不再等待，可以使用返回的连接句柄管理该监听。

参数类型说明
funcFunction第一次事件触发时调用的监听函数

返回值 Connection (可用于提前断开监听的连接句柄)

示例代码

先注册一次性监听，再使用 Fire 触发

lua
-- @runtime client
-- 创建本地事件对象，用于逻辑模块间单向通信
local onceEvent = game:CreateUnit("BindableEvent", { Name = "副本结束信号" })

-- 注册一次性监听：首次收到触发后连接自动失效
local conn = onceEvent:Once(function(reward)
    print("Once 回调收到奖励：" .. tostring(reward))
end)

-- 连接句柄仍可用于提前断开，这里先确认注册成功
print("返回的断连句柄：" .. tostring(conn))

-- 多次触发只会唤醒第一次监听
onceEvent:Fire("金币 x100")
onceEvent:Fire("金币 x100")
onceEvent:Fire("金币 x100")

Wait ​

签名：Wait(duration?: Float) -> Any (事件参数)

将当前协程挂起，直到该 BindableEvent 事件被触发。事件触发后协程恢复，并将触发时返回的数据作为 Wait 的返回值交给调用位置。duration 为可选的等待时长参数。

参数类型说明
duration?Float超时时间（秒）

返回值 Any (事件参数)

示例代码

调用 Wait

lua
-- @runtime client
local bindableEvent = game:CreateUnit("BindableEvent", {})
local duration = 1  -- Number
local result = bindableEvent:Wait(duration)  -- 返回 Any
if result ~= nil then
    print("调用成功，结果: " .. tostring(result))
end