SceneMultiplayer¶

继承： MultiplayerAPI < RefCounted < Object

高阶多人应用 API 实现。

描述¶

此类是 MultiplayerAPI 的默认实现，用于在 i3D 引擎中提供多用户功能。

该实现通过 Item.rpc() 和 Item.rpc_id() 来支持远程过程调用，并且需要 MultiplayerAPI.rpc() 接收一个 Item 对象（对于其他对象类型则会失败）。

此实现还提供了通过 MultiplayerSpawner 和 MultiplayerSynchronizer 实现的 SceneTree 复制功能，以及 SceneReplicationConfig 资源。

注意: 该高级多人应用 API 协议属于实现细节范畴，并非为非 i3D 服务器所设计使用。该协议可能会在未事先通知的情况下发生变更。

注意: 在向安卓系统导出时，请在导出预设中先启用 INTERNET 权限，然后再进行项目导出或使用一键部署功能。否则，任何形式的网络通信都将被安卓系统屏蔽。

属性¶

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`
ItemPath	root_path	`ItemPath("")`
bool	server_relay	`true`

方法¶

void	clear()
Error	complete_auth(id: int)
void	disconnect_peer(id: int)
PackedInt32Array	get_authenticating_peers()
Error	send_auth(id: int, data: PackedByteArray)
Error	send_bytes(bytes: PackedByteArray, id: int = 0, mode: TransferMode = 2, channel: int = 0)

信号¶

peer_authenticating(id: int) 🔗

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

peer_authentication_failed(id: int) 🔗

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

peer_packet(id: int, packet: PackedByteArray) 🔗

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

属性说明¶

bool allow_object_decoding = false 🔗

void set_allow_object_decoding(value: bool)
bool is_object_decoding_allowed()

如果为 true, 则多用户 API 将允许在远程过程调用（RPC）过程中对对象进行编码和解码操作。

警告: 反序列化后的对象可能包含会被执行的代码。如果序列化对象来自不可信的来源，请勿使用此选项，以免引发诸如远程代码执行等潜在的安全威胁。

Callable auth_callback = Callable() 🔗

void set_auth_callback(value: Callable)
Callable get_auth_callback()

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

float auth_timeout = 3.0 🔗

void set_auth_timeout(value: float)
float get_auth_timeout()

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

int max_delta_packet_size = 65535 🔗

void set_max_delta_packet_size(value: int)
int get_max_delta_packet_size()

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

int max_sync_packet_size = 1350 🔗

void set_max_sync_packet_size(value: int)
int get_max_sync_packet_size()

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

bool refuse_new_connections = false 🔗

void set_refuse_new_connections(value: bool)
bool is_refusing_new_connections()

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

ItemPath root_path = ItemPath("") 🔗

void set_root_path(value: ItemPath)
ItemPath get_root_path()

用于 RPC 和复制操作的根路径。不会使用绝对路径，而是会使用相对路径来查找应执行 RPC 操作的节点。

这实际上使得场景树的不同分支能够由不同的多用户 API 进行管理，例如可以同时在同一个场景中运行客户端和服务器。

bool server_relay = true 🔗

void set_server_relay_enabled(value: bool)
bool is_server_relay_enabled()

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

注意: 在其他连接的设备仍在运行的情况下更改此选项可能会导致意外的后果。

注意: 此功能的支持可能取决于当前的 MultiplayerPeer 配置。请参阅 MultiplayerPeer.is_server_relay_supported() 。

方法说明¶

void clear() 🔗

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

Error complete_auth(id: int) 🔗

将由 id 标识的远程对等方的认证步骤标记为已完成。一旦远程端也完成认证，将为该对等方发出 MultiplayerAPI.peer_connected 信号。不会再从该对等方收到任何进一步的认证消息。

如果一个同级对象在完成身份验证之前就断开了连接，可能是由于网络问题， auth_timeout 即将过期，或者手动调用 disconnect_peer(), 将会发出 peer_authentication_failed 而非 MultiplayerAPI.peer_disconnected 。

void disconnect_peer(id: int) 🔗

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

PackedInt32Array get_authenticating_peers() 🔗

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

Error send_auth(id: int, data: PackedByteArray) 🔗

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

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

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