Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

SceneMultiplayer

继承： MultiplayerAPI < RefCounted < Object

高阶多人游戏 API 实现。

描述

这个类是 MultiplayerAPI 的默认实现，用于在 Godot 引擎中提供多人游戏功能。

该实现通过 Node.rpc 和 Node.rpc_id 来支持 RPC，需要向 MultiplayerAPI.rpc 传递一个 Node（传入其他对象类型会导致失败）。

该实现还提供了 SceneTree 复制功能，使用的是 MultiplayerSpawner 和 MultiplayerSynchronizer 节点，以及 SceneReplicationConfig 资源，。

注意：高阶多人游戏 API 协议属于实现细节，并不打算提供给非 Godot 服务器使用。对协议的更改可能不会进行提前通知。

注意：导出到 Android 时，在导出项目或使用一键部署之前，请务必在安卓导出预设中开启 INTERNET 权限。否则，任何类型的网络通信都将被 Android 阻止。

属性

bool

allow_object_decoding

false

Callable

auth_callback

Callable()

float

auth_timeout

3.0

int

max_delta_packet_size

65535

int

max_sync_packet_size

1350

bool

refuse_new_connections

false

NodePath

root_path

NodePath("")

bool

server_relay

true

方法

void

clear ( )

Error

complete_auth ( int id )

void

disconnect_peer ( int id )

PackedInt32Array

get_authenticating_peers ( )

Error

send_auth ( int id, PackedByteArray data )

Error

send_bytes ( PackedByteArray bytes, int id=0, TransferMode mode=2, int channel=0 )

信号

peer_authenticating ( int id )

当此 MultiplayerAPI 的 MultiplayerAPI.multiplayer_peer 连接到一个新对等体并设置有效的 auth_callback 时，将发出此信号。在这种情况下，只有在调用 complete_auth 并传递给定的对等体 id 时，才会发出 MultiplayerAPI.peer_connected。在此状态下，该对等体不会包含在 MultiplayerAPI.get_peers 返回的列表中（但会包含在 get_authenticating_peers 返回的列表中），且只会发送和接收身份验证数据。有关发送身份验证数据的信息，请参阅 send_auth。

peer_authentication_failed ( int id )

当这个 MultiplayerAPI 的 MultiplayerAPI.multiplayer_peer 与另一个尚未完成授权的对等体断开连接时触发。见 peer_authenticating。

peer_packet ( int id, PackedByteArray packet )

当这个 MultiplayerAPI 的 MultiplayerAPI.multiplayer_peer 收到带有自定义数据（见 send_bytes）的 packet 时发出。ID 是发送数据包的对等体的对等体 ID。

属性说明

bool allow_object_decoding = false

  • void set_allow_object_decoding ( bool value )

  • bool is_object_decoding_allowed ( )

如果为 true，则 MultiplayerAPI 将允许在远程过程调用期间对对象进行编码和解码。

警告：反序列化的对象可能包含要执行的代码。如果序列化的对象来自不受信任的来源，请勿使用此选项，以避免潜在的安全威胁，例如远程代码执行。

Callable auth_callback = Callable()

当通过 send_auth 接收身份验证数据时要执行的回调函数。如果 Callable 为空（默认），对等方将在连接后立即自动接受。

float auth_timeout = 3.0

  • void set_auth_timeout ( float value )

  • float get_auth_timeout ( )

如果将其设置为大于 0.0 的值，则对等方可以停留在正在验证状态的最长时间，之后身份验证将自动失败。请参阅 peer_authenticating 和 peer_authentication_failed 信号。

int max_delta_packet_size = 65535

  • void set_max_delta_packet_size ( int value )

  • int get_max_delta_packet_size ( )

增量数据包的最大大小。值越大，单帧能够收到完整更新的几率就越大，但造成网络拥堵的几率也越大（网络延迟、断线等）。见 MultiplayerSynchronizer。

int max_sync_packet_size = 1350

  • void set_max_sync_packet_size ( int value )

  • int get_max_sync_packet_size ( )

同步数据包的最大大小。值越大，单帧能够收到完整更新的几率就越大，但丢包的几率也越大。见 MultiplayerSynchronizer。

bool refuse_new_connections = false

  • void set_refuse_new_connections ( bool value )

  • bool is_refusing_new_connections ( )

如果为 true，则 MultiplayerAPI 的 MultiplayerAPI.multiplayer_peer 将拒绝新的传入连接。

NodePath root_path = NodePath("")

用于 RPC 和复制的根路径。将使用相对路径，而不是绝对路径，来查找 RPC 应该在其上被执行的节点。

这有效地允许场景树的不同分支，由不同的 MultiplayerAPI 管理，例如允许在同一场景中，同时运行客户端和服务器。

bool server_relay = true

  • void set_server_relay_enabled ( bool value )

  • bool is_server_relay_enabled ( )

启用或禁用服务器功能，该功能通知客户端其他对等体的连接/断开，并在它们之间转发消息。当此选项为 false 时，客户端将不会自动收到其他对等体的通知，也无法通过服务器向它们发送数据包。

注意：在其他对等体连接时更改此选项可能会导致意外行为。

注意：对该功能的支持可能取决于当前的 MultiplayerPeer 配置。请参阅 MultiplayerPeer.is_server_relay_supported。

方法说明

void clear ( )

清除当前 SceneMultiplayer 的网络状态（除非你知道你在做什么，否则不应该调用这个函数）。

Error complete_auth ( int id )

完成对由 id 标识的远程对等体的身份验证步骤。远程端也完成身份验证之后，将会为这个对等体发出 MultiplayerAPI.peer_connected 信号。不会再从此对等体接收到身份验证消息。

如果对等体在完成身份验证之前断开连接，无论是由于网络问题、auth_timeout 过期还是手动调用 disconnect_peer，都会发出 peer_authentication_failed 信号，而不是 MultiplayerAPI.peer_disconnected 信号。

void disconnect_peer ( int id )

断开由 id 标识的对等体的连接，将其从连接的对等体列表中移除，并关闭与它的底层连接。

PackedInt32Array get_authenticating_peers ( )

返回当前尝试使用此 MultiplayerAPI 进行身份验证的对等方的 ID。

Error send_auth ( int id, PackedByteArray data )

将指定的 data 作为身份验证消息的一部分发送到由 id 标识的远程对等方。这可用于验证对等方，并控制何时发出 MultiplayerAPI.peer_connected（并接受远程对等方作为连接的对等方之一）。

Error send_bytes ( PackedByteArray bytes, int id=0, TransferMode mode=2, int channel=0 )

向由 id 标识的特定对等体发送给定的原始字节 bytes（见 MultiplayerPeer.set_target_peer）。默认 ID 为 0，即广播到所有对等体。