Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

MultiplayerAPI

继承： RefCounted < Object

派生： MultiplayerAPIExtension, SceneMultiplayer

高阶多人游戏 API 接口。

描述

用于高级多人游戏 API 实现的基类。另见 MultiplayerPeer。

默认情况下，SceneTree 引用了这个类的一个实现，并使用它来提供跨整个场景的多人游戏功能（即 RPC）。

可以通过调用 SceneTree.set_multiplayer() 方法，覆盖特定树分支使用的 MultiplayerAPI 实例，从而有效地允许在同一场景中同时运行客户端和服务器。

也可以通过脚本或本地扩展来扩展或替换默认实现。有关扩展的详细信息，请参阅 MultiplayerAPIExtension；有关默认实现的详细信息，请参阅 SceneMultiplayer。

属性

MultiplayerPeer

multiplayer_peer

方法

MultiplayerAPI	create_default_interface() static
StringName	get_default_interface() static
PackedInt32Array	get_peers()
int	get_remote_sender_id()
int	get_unique_id()
bool	has_multiplayer_peer()
bool	is_server()
Error	object_configuration_add(object: Object, configuration: Variant)
Error	object_configuration_remove(object: Object, configuration: Variant)
Error	poll()
Error	rpc(peer: int, object: Object, method: StringName, arguments: Array = [])
void	set_default_interface(interface_name: StringName) static

信号

connected_to_server() 🔗

当此 MultiplayerAPI 的 multiplayer_peer 成功连接到服务器时发出。仅在客户端上发出。

connection_failed() 🔗

当此 MultiplayerAPI 的 multiplayer_peer 无法与服务器建立连接时发出。仅在客户端上发出。

peer_connected(id: int) 🔗

当此 MultiplayerAPI 的 multiplayer_peer 与新对等体连接时发出。ID 为新对等体的对等体 ID。当某个客户端连接到同一服务器时，其他客户端会收到通知。连接到服务器时，该客户端也会收到此信号，新对等体为服务器（ID 为 1）。

peer_disconnected(id: int) 🔗

当此 MultiplayerAPI 的 multiplayer_peer 与对等体断开连接时发出。当某个客户端从同一服务器断开连接时，其他客户端会收到通知。

server_disconnected() 🔗

当此 MultiplayerAPI 的 multiplayer_peer 与服务器断开连接时发出。仅在客户端上发出。

枚举

enum RPCMode: 🔗

RPCMode RPC_MODE_DISABLED = 0

在 Node.rpc_config() 中使用，可以为所有 RPC 调用禁用某个方法或属性，使其不可用。所有方法的默认值。

RPCMode RPC_MODE_ANY_PEER = 1

在 Node.rpc_config() 中使用，可以将某个方法设置为能够被任何对等体远程调用。类似于 @rpc("any_peer") 注解。接受来自所有远程对等体的调用，无论是否为节点的控制者。

RPCMode RPC_MODE_AUTHORITY = 2

在 Node.rpc_config() 中使用，可以将某个方法设置为仅能够被当前的多人控制者远程调用（默认为服务器）。类似于 @rpc("authority") 注解。见 Node.set_multiplayer_authority()。

属性说明

MultiplayerPeer multiplayer_peer 🔗

void set_multiplayer_peer(value: MultiplayerPeer)
MultiplayerPeer get_multiplayer_peer()

处理 RPC 系统的对等体对象（设置后会启用网络）。根据对等体本身的不同，该 MultiplayerAPI 可能会成为网络服务器（使用 is_server() 判断）并将根节点的网络模式设置为控制者，也可能会成为普通的客户端对等体。所有子节点默认会继承其网络模式。网络相关事件（连接、断开连接、新客户端）的处理是通过连接 MultiplayerAPI 的信号来完成的。

方法说明

MultiplayerAPI create_default_interface() static 🔗

返回默认 MultiplayerAPI 的新实例。

StringName get_default_interface() static 🔗

返回默认的 MultiplayerAPI 实现类名称。SceneMultiplayer 可用时通常为 "SceneMultiplayer"。见 set_default_interface()。

PackedInt32Array get_peers() 🔗

返回这个 MultiplayerAPI 的 multiplayer_peer 所有已连接对等体的对等体 ID。

int get_remote_sender_id() 🔗

返回当前正在执行的 RPC 的发送方对等 ID。

注意：在 RPC 之外调用时，该方法返回 0。因此，当代码延迟执行时（例如使用 GDScript 的 await 关键字），原始对等 ID 可能会丢失。

int get_unique_id() 🔗

返回这个 MultiplayerAPI 的 multiplayer_peer 唯一对等体 ID。

bool has_multiplayer_peer() 🔗

如果设置了 multiplayer_peer，则返回 true。

bool is_server() 🔗

如果这个 MultiplayerAPI 的 multiplayer_peer 有效，且处于服务器模式（监听连接），则返回 true。

Error object_configuration_add(object: Object, configuration: Variant) 🔗

通知该 MultiplayerAPI，以添加用于给定 object 的新的 configuration。该方法在内部被 SceneTree 使用，以配置该 MultiplayerAPI 的根路径（传入 null 并将一个有效的 NodePath 作为 configuration）。该方法可以进一步被 MultiplayerAPI 实现使用，以提供其他功能，有关如何使用它的详细信息，请参阅具体实现（例如 SceneMultiplayer）。

注意：当通过 MultiplayerAPIExtension 扩展或重写 MultiplayerAPI 行为时，该方法最相关。

Error object_configuration_remove(object: Object, configuration: Variant) 🔗

通知该 MultiplayerAPI，以移除用于给定 object 的 configuration。该方法在内部被 SceneTree 使用，以配置该 MultiplayerAPI 的根路径（传入 null 并将一个空的 NodePath 作为 configuration）。该方法可以进一步被 MultiplayerAPI 实现使用，以提供其他功能，有关如何使用它的详细信息，请参阅具体实现（例如 SceneMultiplayer）。

注意：当通过 MultiplayerAPIExtension 扩展或重写 MultiplayerAPI 行为时，该方法最相关。

Error poll() 🔗

用于轮询 MultiplayerAPI 的方法。将 SceneTree.multiplayer_poll 设置为 false 时才需要关心。默认情况下，SceneTree 将为你轮询其 MultiplayerAPI。

注意：该方法会导致 RPC 被调用，因此它们将在该函数的相同上下文中执行（例如 _process、physics、Thread）。

Error rpc(peer: int, object: Object, method: StringName, arguments: Array = []) 🔗

向目标对等体 peer 发送 RPC。会使用提供的参数 arguments 在远程对象 object 上调用给定的方法 method。根据实现和 RPC 配置，RPC 可能也可以进行本地调用。见 Node.rpc() 和 Node.rpc_config()。

注意：请尽量使用 Node.rpc()、Node.rpc_id() 或 my_method.rpc(peer, arg1, arg2, ...)（适用于 GDScript），因为速度更快。这个方法主要用于 MultiplayerAPIExtension 进行多人游戏能力的扩展和替换。

void set_default_interface(interface_name: StringName) static 🔗

设置默认的 MultiplayerAPI 实现类。模块和扩展可以使用这个方法来配置引擎启动时 SceneTree 将使用哪个实现。