共计 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 和同步等内部用途的消息；通常带宽是更有实用价值的统计数据。