RemoteEvent

概览

字段	值
Kind	Unit · 单位 Unit
Realm	common

继承关系

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

继承成员

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

• 来自 Unit（4 属性 / 25 函数 / 6 事件）
  • 属性：AssetId、Name、Desc、Parent
  • 函数：ClearAllChildren、GetChildren、GetDescendants、IsAncestorOf、IsDescendantOf、FindFirstAncestor、FindFirstAncestorWhichIsA、FindFirstAncestorOfClass、FindFirstChild、FindFirstChildWhichIsA、FindFirstChildOfClass、HasChildren、GetChildCount、GetChildAtIndex、SetAttribute、GetAttribute、GetAllProps、Clone、IsA、Destroy、GetPropertyChangedSignal、GetAttributeChangedSignal、FindFromPath、GetFullPath、GetDebugId
  • 事件：ChildAdded、ChildRemoved、DescendantAdded、DescendantRemoving、AncestryChanged、Destroying

RemoteEvent 是可挂接到场景层级的远程通信单元，负责在服务端与客户端之间传递单向异步消息。服务端可通过 FireClient 向指定玩家推送数据，或通过 FireAllClients 向全部玩家广播；客户端通过 FireServer 向服务端上报数据。接收端分别用 OnServerEvent 与 OnClientEvent 事件回调取得消息内容及来源玩家。

适用场景

适合把客户端产生的操作意图上报给服务端处理，再由服务端校验后向单个玩家回执或向所有玩家广播统一状态，使各端表现保持一致。

使用要点

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

注意事项

RemoteEvent.New(eventName) 是静态工厂；FireServer、FireClient 和 FireAllClients 是发送方法，OnServerEvent 与 OnClientEvent 是消息接收事件，通过 Connect 或 Once 连接。当前版本不支持直接传递 CFrame 参数，请拆分为 position(Vector3) 与 rotation(Quaternion/Vector3) 等可序列化字段，或转换为 table 后再传递。服务端必须把 OnServerEvent 的 args 视为不可信客户端输入，校验类型、取值范围和玩家权限后才能修改权威状态。

代码示例

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

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

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

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

客户端监听服务端消息

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

关联类型

• Unit

事件 (2)

OnServerEvent

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

服务端侧监听客户端消息的信号。当客户端通过 RemoteEvent 发送消息时在服务端触发，回调首个参数为发送该消息的 Player，后续为客户端传入的可变参数 args。

回调参数	类型	说明
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

客户端侧监听服务端消息的信号。当服务端通过 RemoteEvent 向本客户端发送消息时触发，回调按顺序接收服务端传入的可变参数 args。

回调参数	类型	说明
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 指定事件名称。返回值为新建的 RemoteEvent 实例。

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

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

示例代码

创建远程事件通道

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

FireAllClients

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

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

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

返回值 void

示例代码

服务端向所有客户端广播

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

FireClient

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

服务端向指定单个玩家的客户端发送事件的函数。调用后，只有目标玩家客户端上该 RemoteEvent 的 OnClientEvent 信号会被触发。

参数	类型	说明
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

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

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

返回值 void

示例代码

客户端向服务端发送事件

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