9fcf3b5a9c
`PackedScene`s can be configured to be spawnable via a new `MultiplayerAPI.spawnable_config` method. They can be configured either to be spawned automatically when coming from the server or to always require verification. Another method, `MultiplayerAPI.send_spawn` lets you request a spawn on the remote peers. When a peer receive a spawn request: - If it comes from the server and the scene is configured as `SPAWN_MODE_SERVER`: - Spawn the scene (instantiate it, add it to tree). - Emit signal `network_spawn`. - Else: - Emit signal `network_spawn_request`. In a similar way, `despawn`s are handled automatically in `SPAWN_MODE_SERVER`. In `SPAWN_MODE_SERVER`, when a new client connects it will also receive, from the server all the spawned (and not yet despawned) instances.
226 lines
14 KiB
XML
226 lines
14 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<class name="MultiplayerAPI" inherits="RefCounted" version="4.0">
|
|
<brief_description>
|
|
High-level multiplayer API.
|
|
</brief_description>
|
|
<description>
|
|
This class implements most of the logic behind the high-level multiplayer API. See also [MultiplayerPeer].
|
|
By default, [SceneTree] has a reference to this class that is used to provide multiplayer capabilities (i.e. RPC/RSET) across the whole scene.
|
|
It is possible to override the MultiplayerAPI instance used by specific Nodes by setting the [member Node.custom_multiplayer] property, effectively allowing to run both client and server in the same scene.
|
|
[b]Note:[/b] The high-level multiplayer API protocol is an implementation detail and isn't meant to be used by non-Godot servers. It may change without notice.
|
|
</description>
|
|
<tutorials>
|
|
</tutorials>
|
|
<methods>
|
|
<method name="clear">
|
|
<return type="void" />
|
|
<description>
|
|
Clears the current MultiplayerAPI network state (you shouldn't call this unless you know what you are doing).
|
|
</description>
|
|
</method>
|
|
<method name="get_network_connected_peers" qualifiers="const">
|
|
<return type="PackedInt32Array" />
|
|
<description>
|
|
Returns the peer IDs of all connected peers of this MultiplayerAPI's [member network_peer].
|
|
</description>
|
|
</method>
|
|
<method name="get_network_unique_id" qualifiers="const">
|
|
<return type="int" />
|
|
<description>
|
|
Returns the unique peer ID of this MultiplayerAPI's [member network_peer].
|
|
</description>
|
|
</method>
|
|
<method name="get_rpc_sender_id" qualifiers="const">
|
|
<return type="int" />
|
|
<description>
|
|
Returns the sender's peer ID for the RPC currently being executed.
|
|
[b]Note:[/b] If not inside an RPC this method will return 0.
|
|
</description>
|
|
</method>
|
|
<method name="has_network_peer" qualifiers="const">
|
|
<return type="bool" />
|
|
<description>
|
|
Returns [code]true[/code] if there is a [member network_peer] set.
|
|
</description>
|
|
</method>
|
|
<method name="is_network_server" qualifiers="const">
|
|
<return type="bool" />
|
|
<description>
|
|
Returns [code]true[/code] if this MultiplayerAPI's [member network_peer] is in server mode (listening for connections).
|
|
</description>
|
|
</method>
|
|
<method name="poll">
|
|
<return type="void" />
|
|
<description>
|
|
Method used for polling the MultiplayerAPI. You only need to worry about this if you are using [member Node.custom_multiplayer] override or you set [member SceneTree.multiplayer_poll] to [code]false[/code]. By default, [SceneTree] will poll its MultiplayerAPI for you.
|
|
[b]Note:[/b] This method results in RPCs and RSETs being called, so they will be executed in the same context of this function (e.g. [code]_process[/code], [code]physics[/code], [Thread]).
|
|
</description>
|
|
</method>
|
|
<method name="send_bytes">
|
|
<return type="int" enum="Error" />
|
|
<argument index="0" name="bytes" type="PackedByteArray" />
|
|
<argument index="1" name="id" type="int" default="0" />
|
|
<argument index="2" name="mode" type="int" enum="MultiplayerPeer.TransferMode" default="2" />
|
|
<argument index="3" name="channel" type="int" default="0" />
|
|
<description>
|
|
Sends the given raw [code]bytes[/code] to a specific peer identified by [code]id[/code] (see [method MultiplayerPeer.set_target_peer]). Default ID is [code]0[/code], i.e. broadcast to all peers.
|
|
</description>
|
|
</method>
|
|
<method name="send_despawn">
|
|
<return type="int" enum="Error" />
|
|
<argument index="0" name="peer_id" type="int" />
|
|
<argument index="1" name="scene_id" type="int" />
|
|
<argument index="2" name="path" type="NodePath" />
|
|
<argument index="3" name="data" type="PackedByteArray" default="PackedByteArray()" />
|
|
<description>
|
|
Sends a despawn request for the scene identified by [code]scene_id[/code] to the given [code]peer_id[/code] (see [method MultiplayerPeer.set_target_peer]). If the scene is configured as [constant SPAWN_MODE_SERVER] (see [method spawnable_config]) and the request is sent by the server (see [method is_network_server]), the receiving peer(s) will automatically queue for deletion the node at [code]path[/code] and emit the signal [signal network_despawn]. In all other cases no deletion happens, and the signal [signal network_despawn_request] is emitted instead.
|
|
</description>
|
|
</method>
|
|
<method name="send_spawn">
|
|
<return type="int" enum="Error" />
|
|
<argument index="0" name="peer_id" type="int" />
|
|
<argument index="1" name="scene_id" type="int" />
|
|
<argument index="2" name="path" type="NodePath" />
|
|
<argument index="3" name="data" type="PackedByteArray" default="PackedByteArray()" />
|
|
<description>
|
|
Sends a spawn request for the scene identified by [code]scene_id[/code] to the given [code]peer_id[/code] (see [method MultiplayerPeer.set_target_peer]). If the scene is configured as [constant SPAWN_MODE_SERVER] (see [method spawnable_config]) and the request is sent by the server (see [method is_network_server]), the receiving peer(s) will automatically instantiate that scene, add it to the [SceneTree] at the given [code]path[/code] and emit the signal [signal network_spawn]. In all other cases no instantiation happens, and the signal [signal network_spawn_request] is emitted instead.
|
|
</description>
|
|
</method>
|
|
<method name="spawnable_config">
|
|
<return type="int" enum="Error" />
|
|
<argument index="0" name="scene_id" type="int" />
|
|
<argument index="1" name="spawn_mode" type="int" enum="MultiplayerAPI.SpawnMode" />
|
|
<description>
|
|
Configures the MultiplayerAPI to track instances of the [PackedScene] idenfied by [code]scene_id[/code] (see [method ResourceLoader.get_resource_uid]) for the purpose of network replication. See [enum SpawnMode] for the possible configurations.
|
|
</description>
|
|
</method>
|
|
</methods>
|
|
<members>
|
|
<member name="allow_object_decoding" type="bool" setter="set_allow_object_decoding" getter="is_object_decoding_allowed" default="false">
|
|
If [code]true[/code], the MultiplayerAPI will allow encoding and decoding of object during RPCs/RSETs.
|
|
[b]Warning:[/b] Deserialized objects can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats such as remote code execution.
|
|
</member>
|
|
<member name="network_peer" type="MultiplayerPeer" setter="set_network_peer" getter="get_network_peer">
|
|
The peer object to handle the RPC system (effectively enabling networking when set). Depending on the peer itself, the MultiplayerAPI will become a network server (check with [method is_network_server]) and will set root node's network mode to master, or it will become a regular peer with root node set to puppet. All child nodes are set to inherit the network mode by default. Handling of networking-related events (connection, disconnection, new clients) is done by connecting to MultiplayerAPI's signals.
|
|
</member>
|
|
<member name="refuse_new_network_connections" type="bool" setter="set_refuse_new_network_connections" getter="is_refusing_new_network_connections" default="false">
|
|
If [code]true[/code], the MultiplayerAPI's [member network_peer] refuses new incoming connections.
|
|
</member>
|
|
<member name="root_node" type="Node" setter="set_root_node" getter="get_root_node">
|
|
The root node to use for RPCs. Instead of an absolute path, a relative path will be used to find the node upon which the RPC should be executed.
|
|
This effectively allows to have different branches of the scene tree to be managed by different MultiplayerAPI, allowing for example to run both client and server in the same scene.
|
|
</member>
|
|
</members>
|
|
<signals>
|
|
<signal name="connected_to_server">
|
|
<description>
|
|
Emitted when this MultiplayerAPI's [member network_peer] successfully connected to a server. Only emitted on clients.
|
|
</description>
|
|
</signal>
|
|
<signal name="connection_failed">
|
|
<description>
|
|
Emitted when this MultiplayerAPI's [member network_peer] fails to establish a connection to a server. Only emitted on clients.
|
|
</description>
|
|
</signal>
|
|
<signal name="network_despawn">
|
|
<argument index="0" name="id" type="int" />
|
|
<argument index="1" name="scene_id" type="int" />
|
|
<argument index="2" name="node" type="Node" />
|
|
<argument index="3" name="data" type="PackedByteArray" />
|
|
<description>
|
|
Emitted on a client before deleting a local Node upon receiving a despawn request from the server.
|
|
</description>
|
|
</signal>
|
|
<signal name="network_despawn_request">
|
|
<argument index="0" name="id" type="int" />
|
|
<argument index="1" name="scene_id" type="int" />
|
|
<argument index="2" name="parent" type="Node" />
|
|
<argument index="3" name="name" type="String" />
|
|
<argument index="4" name="data" type="PackedByteArray" />
|
|
<description>
|
|
Emitted when a network despawn request has been received from a client, or for a [PackedScene] that has been configured as [constant SPAWN_MODE_CUSTOM].
|
|
</description>
|
|
</signal>
|
|
<signal name="network_peer_connected">
|
|
<argument index="0" name="id" type="int" />
|
|
<description>
|
|
Emitted when this MultiplayerAPI's [member network_peer] connects with a new peer. ID is the peer ID of the new peer. Clients get notified when other clients connect to the same server. Upon connecting to a server, a client also receives this signal for the server (with ID being 1).
|
|
</description>
|
|
</signal>
|
|
<signal name="network_peer_disconnected">
|
|
<argument index="0" name="id" type="int" />
|
|
<description>
|
|
Emitted when this MultiplayerAPI's [member network_peer] disconnects from a peer. Clients get notified when other clients disconnect from the same server.
|
|
</description>
|
|
</signal>
|
|
<signal name="network_peer_packet">
|
|
<argument index="0" name="id" type="int" />
|
|
<argument index="1" name="packet" type="PackedByteArray" />
|
|
<description>
|
|
Emitted when this MultiplayerAPI's [member network_peer] receive a [code]packet[/code] with custom data (see [method send_bytes]). ID is the peer ID of the peer that sent the packet.
|
|
</description>
|
|
</signal>
|
|
<signal name="network_spawn">
|
|
<argument index="0" name="id" type="int" />
|
|
<argument index="1" name="scene_id" type="int" />
|
|
<argument index="2" name="node" type="Node" />
|
|
<argument index="3" name="data" type="PackedByteArray" />
|
|
<description>
|
|
Emitted on a client after a new Node is instantiated locally and added to the SceneTree upon receiving a spawn request from the server.
|
|
</description>
|
|
</signal>
|
|
<signal name="network_spawn_request">
|
|
<argument index="0" name="id" type="int" />
|
|
<argument index="1" name="scene_id" type="int" />
|
|
<argument index="2" name="parent" type="Node" />
|
|
<argument index="3" name="name" type="String" />
|
|
<argument index="4" name="data" type="PackedByteArray" />
|
|
<description>
|
|
Emitted when a network spawn request has been received from a client, or for a [PackedScene] that has been configured as [constant SPAWN_MODE_CUSTOM].
|
|
</description>
|
|
</signal>
|
|
<signal name="network_spawnable_added">
|
|
<argument index="0" name="scene_id" type="int" />
|
|
<argument index="1" name="node" type="Node" />
|
|
<description>
|
|
Emitted when an instance of a [PackedScene] that has been configured for networking enters the [SceneTree]. See [method spawnable_config].
|
|
</description>
|
|
</signal>
|
|
<signal name="network_spawnable_removed">
|
|
<argument index="0" name="scene_id" type="int" />
|
|
<argument index="1" name="node" type="Node" />
|
|
<description>
|
|
Emitted when an instance of a [PackedScene] that has been configured for networking leaves the [SceneTree]. See [method spawnable_config].
|
|
</description>
|
|
</signal>
|
|
<signal name="server_disconnected">
|
|
<description>
|
|
Emitted when this MultiplayerAPI's [member network_peer] disconnects from server. Only emitted on clients.
|
|
</description>
|
|
</signal>
|
|
</signals>
|
|
<constants>
|
|
<constant name="RPC_MODE_DISABLED" value="0" enum="RPCMode">
|
|
Used with [method Node.rpc_config] to disable a method or property for all RPC calls, making it unavailable. Default for all methods.
|
|
</constant>
|
|
<constant name="RPC_MODE_REMOTE" value="1" enum="RPCMode">
|
|
Used with [method Node.rpc_config] to set a method to be called or a property to be changed only on the remote end, not locally. Analogous to the [code]remote[/code] keyword. Calls and property changes are accepted from all remote peers, no matter if they are node's master or puppets.
|
|
</constant>
|
|
<constant name="RPC_MODE_MASTER" value="2" enum="RPCMode">
|
|
Used with [method Node.rpc_config] to set a method to be called or a property to be changed only on the network master for this node. Analogous to the [code]master[/code] keyword. Only accepts calls or property changes from the node's network puppets, see [method Node.set_network_master].
|
|
</constant>
|
|
<constant name="RPC_MODE_PUPPET" value="3" enum="RPCMode">
|
|
Used with [method Node.rpc_config] to set a method to be called or a property to be changed only on puppets for this node. Analogous to the [code]puppet[/code] keyword. Only accepts calls or property changes from the node's network master, see [method Node.set_network_master].
|
|
</constant>
|
|
<constant name="SPAWN_MODE_NONE" value="0" enum="SpawnMode">
|
|
Used with [method spawnable_config] to identify a [PackedScene] that should not be replicated.
|
|
</constant>
|
|
<constant name="SPAWN_MODE_SERVER" value="1" enum="SpawnMode">
|
|
Used with [method spawnable_config] to identify a [PackedScene] that should be automatically replicated from server to clients.
|
|
</constant>
|
|
<constant name="SPAWN_MODE_CUSTOM" value="2" enum="SpawnMode">
|
|
Used with [method spawnable_config] to identify a [PackedScene] that can be manually replicated among peers.
|
|
</constant>
|
|
</constants>
|
|
</class>
|