共计 5192 个字符,预计需要花费 13 分钟才能阅读完成。
多玩家脚本接口
接口继承
这个接口从 IObjectClass 派生,以提供特定于多玩家对象的 API。IMultiplayerObjectType
注意,此类从对象类接口继承,而不是实例接口。通常通过.runtime.objects.Multiplayer 访问。
API 组织
多玩家 API 大致分为两类:
- 信号 API,利用信号服务器与其他对等体建立连接
- 主要的多玩家 API,用于在建立连接后进行对等通信
为了明确区分这些用途,信号 API 位于专用的信号接口上,而其余的多玩家 API 位于主多玩家接口上。runtime.objects.Multiplayer.signalling
还有一些统计信息,但这些是可选的。runtime.objects.Multiplayer.stats
示例
请参阅多玩家脚本示例,了解如何在 JavaScript 代码中使用这些多玩家 API。
信号事件
这些事件在.runtime.objects.Multiplayer.signalling 上触发
"connected"
成功建立到信号服务器的连接时触发。事件对象包括以下属性:
myId: 分配给本地用户的对等 ID
serverVersion: 带有信号服务器软件版本的字符串
serverName: 信号服务器名称的字符串
serverOperator: 标识信号服务器操作员的字符串
serverMOTD: 服务器操作员选择的“今日消息”字符串
"login"
成功登录到信号服务器后触发。事件对象属性提供了分配给本地用户的别名(将是请求的别名,除非该别名已被使用,在这种情况下,信号服务器将分配一个从请求的别名派生的不同别名)。myAlias
"join"
成功加入信号服务器上的房间后触发。事件对象包括以下属性:
isHost: 表示本地用户是否是房间主机的布尔值。第一个加入房间的对等体被指定为主机。
hostId: 房间主机的对等 ID。仅当 isHost 为假时需要引用(因为如果本地用户是主机,则主机 ID 是他们自己的对等 ID)。isHost
hostAlias: 房间主机的别名。
room: 加入的房间名称字符串。(只有自动加入房间时,这可能与请求的房间名称不同)
"leave"
成功离开信号服务器上的房间后触发。
"disconnected"
与信号服务器断开连接时触发。
"kicked"
从信号服务器上的当前房间被强制移除时触发。这与 event 事件类似,但离开房间的原因是由服务器发起的,而不是由对等体发起的。"leave"
"error"
使用信号服务器时发生错误时触发。事件对象属性提供错误消息(如果有)。message
Signalling APIs
这些方法是在 .runtime.objects.Multiplayer.signalling 上可用的。
方法注释
addEventListener(eventName, callback)
removeEventListener(eventName, callback)
添加或移除信号事件的一个回调函数。更多信息请参阅上述的信号事件。
async connect(url = "wss://multiplayer.construct.net")
初始化到信号服务器的连接。默认 URL 是官方 Scirra 托管的信号服务器。该方法可以被等待,并且在信号事件触发时解析,解析对象具有与事件对象相同的属性。"connected"
disconnect()
从信号服务器断开连接。一旦建立起对等连接,如果不再需要信号服务器,则可以这样做,但请注意,这将阻止新玩家加入游戏。
isConnected
一个只读布尔值,表示当前是否已连接到信号服务器。
addICEServer(url, username, credential)
添加由 WebRTC 用于建立对等之间连接的自定义交互连通性建立(ICE)服务器。这些可以包括 STUN 和 TURN 服务器。如果服务器需要,还可以可选地提供用户名和凭证。此方法应在启动时调用,在任何连接之前。
async login(alias)
尝试登录到信号服务器并请求使用提供的别名。该方法可以被等待,并且在信号事件触发时解析,解析对象具有与事件对象相同的属性。"login"
isLoggedIn
一个布尔值,表示用户当前是否已登录到信号服务器。
async joinRoom(game, instance, room, maxPeers = 0)
加入给定的游戏实例中的特定房间。玩家必须已连接到信号服务器并已登录。第一个加入房间的玩家成为主机。maxPeers 可用于限制加入的对等数。只有主机的值被使用。如果房间已满,随后加入的对等方将收到“房间已满”的错误。对等计数包括主机,因此 2 是最小值,或者它可以保留为 0 以允许无限数量的对等方加入。该方法可以被等待,并且在信号事件触发时解析,解析对象具有与事件对象相同的属性。maxPeers "join"
async autoJoinRoom(game, instance, room, maxPeers = 2, isLocking = true)
使用给定的游戏、实例和第一个房间名称加入第一个可用的房间。玩家必须已连接到信号服务器并已登录。第一个加入房间的玩家成为主机。当房间满时,信号服务器将创建新的房间。例如,如果“myroom”已满,它将尝试“myroom2”,“myroom3”等。这有效地将所有加入的对等方安排到特定大小的游戏。如果 isLocking 为 true,则当房间满时锁定房间。在这种情况下,迟到者不允许加入;如果未锁定且对等方在游戏开始后离开,新加入的对等方可能会重新添加到游戏中以达到再次达到最大人数。该方法的工作方式类似于 joinRoom(),它可以被等待并在事件触发时解析。isLocking maxPeers "join"
async leaveRoom()
请求离开信号服务器上的当前房间。该方法可以被等待,并且在信号事件触发时解析。"leave"
async requestGameInstanceList(game)
请求给定游戏中的活动游戏实例列表。返回一个承诺,当接收到响应时解析,带有描述每个游戏实例的对象数组,对象属性:
- name: 游戏实例名称
- peerCount: 该游戏实例中的总对等数
async requestRoomList(game, instance, type = "all")
请求给定游戏实例中的活动房间列表。返回的房间取决于 type:包括所有房间;仅包括解锁的房间;仅包括可加入(解锁且未满)的房间。返回一个承诺,当接收到响应时解析,带有描述每个房间的对象数组,对象属性:type "all" "unlocked" "available"
- name: 房间名称
- peerCount: 房间中的对等数
- maxPeerCount: 允许的最大对等数,或者 0 表示无限制
- state: 房间状态,之一:"available" "locked" "full"
Multiplayer events
这些事件在 .runtime.objects.Multiplayer 上触发
- "peerconnect"
当对等方加入同一房间时触发。当加入现有房间时,它还会对已经在同一房间的每个对等方触发一次,包括主机。事件对象包含属性:- peerId: 连接的对等方的 ID
- peerAlias: 连接的对等方的别名
- "peerdisconnect"
当现有对等方从房间断开连接时触发。事件对象包含属性:- peerId: 断开连接的对等方的 ID
- peerAlias: 断开连接的对等方的别名
- leaveReason: 对等方断开连接提供的可选理由字符串
- "message"
当通过网络接收到消息时触发。注意接收消息的顺序,或者发送的消息是否接收到,取决于发送消息时的可靠性模式。事件对象包含属性:- fromId: 发送消息的对等方的 ID
- fromAlias: 发送消息的对等方的别名
- message: 消息的内容。根据发送的消息类型,这要么是字符串,要么是 JSON 数据,要么是用于二进制内容的 ArrayBuffer。
- transmissionMode: 发送消息的传输模式。
- "kicked"
如果被踢出当前房间,则触发。如果主机退出,无法建立与主机的连接,或者主机决定强制将你从房间中移除,就会发生这种情况。在此之后触发,玩家不再处于房间中,必须重新加入房间才能参与游戏。
多人游戏 APIs
这些方法和属性适用于 .runtime.objects.Multiplayer
。
信号接口
提供信号接口 – 见上文的信号 APIs。
统计接口
提供统计接口 – 见下文的统计 APIs。
是否为主机
一个只读的布尔值,表示当前对等端是否是房间主机。
我的 ID
我的别名
只读的字符串,包含本地用户的对等端 ID 和别名。
主机 ID
主机别名
只读的字符串,包含房间主机(如果 isHost 为真,则与 myId 和 myAlias 相同)的对等端 ID 和别名。
当前游戏
当前游戏实例
当前房间
只读的字符串,标识当前的游戏、游戏实例和房间。
对等端数量
只读的已连接对等端的数量,包括本地用户。
获取所有对等端 ()
返回一个数组,表示房间中的每一个对等端,包括本地用户。见下方的对等端 APIs。IMultiplayerPeer
通过 ID 获取对等端 (peerId)
根据对等端 ID 返回当前房间中的一个对等端,或如果不存在则返回 null。另见下方的对等端 APIs。IMultiplayerPeernull
发送对等端消息 (peerId, message, transmissionMode = "o")
通过网络向同一房间中的对等端发送消息。消息可以是字符串、用于 JSON 传输的对象(必须可以转换为字符串),或用于二进制内容的 ArrayBuffer。传输模式可以是可靠有序的 "o"、可靠无序的 "r" 或不可靠的 "u"(有关可靠性模式的更多详细信息,请参见 Multiplayer 对象文档)。当接收到时,将触发 "message" 事件。"o""r""u""message"
主机广播消息 (fromId, message, transmissionMode = "o")
这与 sendPeerMessage() 类似,但只能由主机调用,提供的消息将发送给房间中的其他所有对等端。fromId 可以设置为另一个对等端的 ID,使其看起来像是来自该对等端的消息,这对于通过主机转发消息很有用;如果留空,则使用主机 ID。sendPeerMessage()fromId
断开房间连接 ()
从当前房间的所有对等端断开连接,并在信号服务器上离开房间。如果当前用户是房间主机,则会踢出所有其他对等端。
模拟延迟 (latency, pdv, loss)
在所有传入和传出的消息上模拟延迟、PDV 和数据包丢失。这对于使本地测试更加现实很有用,因为与互联网不同,延迟实际上是不存在的。对于本地测试,只需在主机上模拟延迟,因为这保证了游戏中的每个消息都会增加延迟;不需要在对等端上也模拟延迟。单个消息的延迟计算为延迟加上从零到 PDV 的随机值。数据包丢失表示不可靠消息完全丢失的可能性,或者在可靠消息的情况下需要重传并且延迟乘以。
对等端 APIs
接口代表同一房间中的连接对等端。它由 getAllPeers() 和 getPeerById() 等方法返回。IMultiplayerPeer
id
此对等端的对等端 ID。
alias
此对等端的别名。
isHost
一个布尔值,表示此对等端是否是房间主机。
isMe
一个布尔值,表示此对等端是否代表本地用户。
latency
pdv
获取与此对等端网络连接上测量的延迟和数据包延迟变化(PDV)。注意,对等端只能使用此功能获取主机的统计数据,因为他们只有这个连接,但主机可以使用它获取任何对等端的统计数据。
send(message, transmissionMode = "o")
这是调用 sendPeerMessage() 的简写,使用此对等端的 ID。sendPeerMessage()
统计 APIs
这些属性适用于 .runtime.objects.Multiplayer.stats
。
inboundBandwidth
outboundBandwidth
只读的数字,表示所有通过网络传输的数据的总估算入站和出站带宽(以字节 / 秒为单位)。当自动数据压缩启用时,这测量实际通过网络发送的压缩数据的大小。
inboundDecompressedBandwidth
outboundDecompressedBandwidth
只读的数字,表示通过 Multiplayer 对象发送和接收的所有数据的总估算解压后的入站和出站带宽(以字节 / 秒为单位)。当自动数据压缩启用时,这测量解压后的消息大小,可能比实际通过网络发送的数据大得多。
inboundCount
outboundCount
只读的数字,表示发送和接收的单独入站和出站消息的总数。这包括用于诸如 ping 和同步等内部用途的消息;通常带宽是更有实用价值的统计数据。