RemoteEvent

概览

字段	值
Kind	Data · 数据 Data
Realm	common

远程事件，承担客户端与服务端之间的异步单向通信职责。它既支持服务端通过 FireClient 向指定客户端、FireAllClients 向所有客户端推送消息，也支持客户端通过 FireServer 向服务端上报请求，接收方分别用 OnServerEvent 与 OnClientEvent 监听。

适用场景

常用于把客户端的操作意图（例如点击按钮请求数据）交给服务端处理，再由服务端把结果回推给对应客户端，例如服务端读取该玩家的加入数据后通过事件回发给请求方。

使用要点

客户端与服务端分别使用相同的 eventName 调用 RemoteEvent.New(eventName) 获取对应事件通道；可把事件名称集中定义在两端共用的脚本模块中。服务端连接 OnServerEvent 接收客户端参数，处理后用 FireClient 或 FireAllClients 回传结果；客户端连接 OnClientEvent 处理回传数据，并用 FireServer 发送自身输入。

注意事项

RemoteEvent 用于客户端与服务端之间的事件通信。真实可用方法仅有：FireServer/FireClient/FireAllClients/OnServerEvent/OnClientEvent。注意：本类型没有 GetAllPlayers、GetPlayers 方法（那是 Players 服务的职责）——请勿在 RemoteEvent 示例中调用不相关服务的方法。当前版本不支持直接传递 CFrame 参数，请拆分为 position(Vector3) 与 rotation(Quaternion/Vector3) 等可序列化字段，或转换为 table 后再传递。服务端必须把 OnServerEvent 的 args 视为不可信客户端输入，校验类型、取值范围和玩家权限后才能修改权威状态。

代码示例

客户端发送事件，服务端监听

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

-- 服务端脚本中使用 remoteEvent.OnServerEvent 监听该事件

事件 (2)

OnServerEvent

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

OnServerEvent 是 RemoteEvent 在服务端可监听的信号，当有客户端向服务端发来消息时触发。回调会依次接收发起本次消息的 Player 玩家对象，以及客户端随消息传入的可选附加参数。

回调参数	类型	说明
player	Player	触发事件的玩家
args?	Any	事件参数

示例代码

服务端监听客户端事件

-- @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)

OnClientEvent

签名：OnClientEvent(args?: Any) 触发：local

当服务端通过 FireAllClients 或 FireClient 发送事件时，在客户端触发此信号。

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

示例代码

客户端监听服务端事件

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

函数 (4)

New

签名：New(eventName: String) -> RemoteEvent (新创建的 RemoteEvent 实例)

创建一个新的 RemoteEvent 实例。

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

返回值 RemoteEvent (新创建的 RemoteEvent 实例)

示例代码

创建远程事件通道

-- @runtime client
local remoteEvent = RemoteEvent.New('RoundStateChanged')
print('远程事件:', tostring(remoteEvent))

FireAllClients

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

从服务端向所有客户端广播事件。

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

返回值 void

示例代码

服务端向所有客户端广播

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

FireClient

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

FireClient 是 RemoteEvent 在服务端调用的函数，用于把消息发送给指定的单个玩家客户端。调用时需要传入目标 Player 对象，之后可继续传入任意可选的附加参数，这些参数会一并传递到该玩家客户端的接收回调中。

参数	类型	说明
player	Player	目标玩家
args?	Any	事件参数

返回值 void

示例代码

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

-- @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) -> void

从客户端向服务端发送事件。

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

返回值 void

示例代码

客户端向服务端发送事件

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