MultiplayerAPI

继承： RefCounted < Object

派生： MultiplayerAPIExtension, SceneMultiplayer

高阶多人游戏 API 接口。

描述

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

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

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

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

属性

方法

信号

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 将使用哪个实现。