工坊手册

主题

RemoteEvent ​

远程事件 RemoteEvent 是可挂接到 World 或场景中的通信单元，用于客户端与服务端之间的单向异步消息传递。服务端可以借助 FireClient 向指定玩家下发消息，或用 FireAllClients 广播给所有客户端；客户端则...

概览 ​

远程事件 RemoteEvent 是可挂接到 World 或场景中的通信单元，用于客户端与服务端之间的单向异步消息传递。服务端可以借助 FireClient 向指定玩家下发消息，或用 FireAllClients 广播给所有客户端；客户端则通过 FireServer 把数据上报给服务端。接收方使用 OnServerEvent 与 OnClientEvent 事件配合 Connect 或 Once 完成监听，从而实现两端的状态同步与指令传递。

继承自 Unit；可通过 World:CreateUnit("RemoteEvent", ...) 创建；返回单个单位

代码示例 ​

客户端发送事件（先启动接收端监听）

lua
-- @runtime client
local remoteEvent = RemoteEvent.New('RoundStateChanged')
remoteEvent:FireServer({ state = 'Ready' })

服务端接收并校验客户端输入

lua
-- @runtime server
-- 服务端脚本：先启动监听，再由客户端发送
local remoteEvent = RemoteEvent.New('RoundStateChanged')
remoteEvent.OnServerEvent:Once(function(player, args)
    if type(args) ~= 'table' then return end
    if args.state ~= 'Ready' then return end
    -- 修改权威状态前，还需按业务规则校验 player 的权限
    print('收到已校验状态:', player, args.state)
end)

客户端监听服务端消息

lua
-- @runtime client
local remoteEvent = RemoteEvent.New('RoundStateChanged')
remoteEvent.OnClientEvent:Once(function(args)
    if type(args) ~= 'table' then return end
    print('服务端广播:', args.state)
end)

函数 ​

New ​

签名：RemoteEvent.New(eventName: String) -> RemoteEvent

构造一个 RemoteEvent 实例，通过 eventName 指定事件名称。返回值为新建的 RemoteEvent 实例。

参数类型说明
eventNameString事件名称，用于标识该远程事件

返回值 RemoteEvent

FireAllClients ​

签名：FireAllClients(args: Any?)

服务端向所有已连接的客户端广播事件的函数。调用后，每个客户端上该 RemoteEvent 的 OnClientEvent 信号都会被触发，并接收到调用时传入的参数。

参数类型说明
argsAny?事件参数

服务端向所有客户端广播

lua
-- @runtime server
local remoteEvent = RemoteEvent.New('RoundStateChanged')
remoteEvent:FireAllClients({ state = 'Started' })

FireClient ​

签名：FireClient(player: Player, args: Any?)

从服务端向指定的单个玩家客户端触发 RemoteEvent，并附带可选的若干参数。调用后，该玩家客户端对应的 OnClientEvent 会收到本次传递的参数。

参数类型说明
playerPlayer目标玩家
argsAny?事件参数

服务端向指定客户端发送事件

lua
-- @runtime server
local Players = game:GetService('Players')
local remoteEvent = RemoteEvent.New('PrivateMessage')
local player = Players:GetPlayers()[1]
if player ~= nil then
    remoteEvent:FireClient(player, { text = 'hello' })
end

FireServer ​

签名：FireServer(args: Any?)

客户端向服务端发送事件的函数。调用后，服务端上该 RemoteEvent 的 OnServerEvent 信号会被触发。

参数类型说明
argsAny?事件参数

客户端向服务端发送事件

lua
-- @runtime client
local remoteEvent = RemoteEvent.New('RoundStateChanged')
remoteEvent:FireServer({ state = 'Ready' })

事件 ​

OnServerEvent ​

签名：OnServerEvent(player: Player, args: Any?)

服务端监听来自客户端的远程事件，回调参数为 (player, ...)。懒注册：首个监听者 Connect 时才注册网络通道。

参数类型说明
playerPlayer触发事件的玩家
argsAny?事件参数

OnClientEvent ​

签名：OnClientEvent(args: Any?)

客户端监听来自服务端的远程事件，回调参数为 (...)。懒注册：首个监听者 Connect 时才注册网络通道。

参数类型说明
argsAny?事件参数