148 lines
9.0 KiB
XML
148 lines
9.0 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<class name="MultiplayerAPI" inherits="RefCounted" keywords="network" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
|
|
<brief_description>
|
|
High-level multiplayer API interface.
|
|
</brief_description>
|
|
<description>
|
|
Base class for high-level multiplayer API implementations. See also [MultiplayerPeer].
|
|
By default, [SceneTree] has a reference to an implementation of this class and uses it to provide multiplayer capabilities (i.e. RPCs) across the whole scene.
|
|
It is possible to override the MultiplayerAPI instance used by specific tree branches by calling the [method SceneTree.set_multiplayer] method, effectively allowing to run both client and server in the same scene.
|
|
It is also possible to extend or replace the default implementation via scripting or native extensions. See [MultiplayerAPIExtension] for details about extensions, [SceneMultiplayer] for the details about the default implementation.
|
|
</description>
|
|
<tutorials>
|
|
</tutorials>
|
|
<methods>
|
|
<method name="create_default_interface" qualifiers="static">
|
|
<return type="MultiplayerAPI" />
|
|
<description>
|
|
Returns a new instance of the default MultiplayerAPI.
|
|
</description>
|
|
</method>
|
|
<method name="get_default_interface" qualifiers="static">
|
|
<return type="StringName" />
|
|
<description>
|
|
Returns the default MultiplayerAPI implementation class name. This is usually [code]"SceneMultiplayer"[/code] when [SceneMultiplayer] is available. See [method set_default_interface].
|
|
</description>
|
|
</method>
|
|
<method name="get_peers">
|
|
<return type="PackedInt32Array" />
|
|
<description>
|
|
Returns the peer IDs of all connected peers of this MultiplayerAPI's [member multiplayer_peer].
|
|
</description>
|
|
</method>
|
|
<method name="get_remote_sender_id">
|
|
<return type="int" />
|
|
<description>
|
|
Returns the sender's peer ID for the RPC currently being executed.
|
|
[b]Note:[/b] This method returns [code]0[/code] when called outside of an RPC. As such, the original peer ID may be lost when code execution is delayed (such as with GDScript's [code]await[/code] keyword).
|
|
</description>
|
|
</method>
|
|
<method name="get_unique_id">
|
|
<return type="int" />
|
|
<description>
|
|
Returns the unique peer ID of this MultiplayerAPI's [member multiplayer_peer].
|
|
</description>
|
|
</method>
|
|
<method name="has_multiplayer_peer">
|
|
<return type="bool" />
|
|
<description>
|
|
Returns [code]true[/code] if there is a [member multiplayer_peer] set.
|
|
</description>
|
|
</method>
|
|
<method name="is_server">
|
|
<return type="bool" />
|
|
<description>
|
|
Returns [code]true[/code] if this MultiplayerAPI's [member multiplayer_peer] is valid and in server mode (listening for connections).
|
|
</description>
|
|
</method>
|
|
<method name="object_configuration_add">
|
|
<return type="int" enum="Error" />
|
|
<param index="0" name="object" type="Object" />
|
|
<param index="1" name="configuration" type="Variant" />
|
|
<description>
|
|
Notifies the MultiplayerAPI of a new [param configuration] for the given [param object]. This method is used internally by [SceneTree] to configure the root path for this MultiplayerAPI (passing [code]null[/code] and a valid [NodePath] as [param configuration]). This method can be further used by MultiplayerAPI implementations to provide additional features, refer to specific implementation (e.g. [SceneMultiplayer]) for details on how they use it.
|
|
[b]Note:[/b] This method is mostly relevant when extending or overriding the MultiplayerAPI behavior via [MultiplayerAPIExtension].
|
|
</description>
|
|
</method>
|
|
<method name="object_configuration_remove">
|
|
<return type="int" enum="Error" />
|
|
<param index="0" name="object" type="Object" />
|
|
<param index="1" name="configuration" type="Variant" />
|
|
<description>
|
|
Notifies the MultiplayerAPI to remove a [param configuration] for the given [param object]. This method is used internally by [SceneTree] to configure the root path for this MultiplayerAPI (passing [code]null[/code] and an empty [NodePath] as [param configuration]). This method can be further used by MultiplayerAPI implementations to provide additional features, refer to specific implementation (e.g. [SceneMultiplayer]) for details on how they use it.
|
|
[b]Note:[/b] This method is mostly relevant when extending or overriding the MultiplayerAPI behavior via [MultiplayerAPIExtension].
|
|
</description>
|
|
</method>
|
|
<method name="poll">
|
|
<return type="int" enum="Error" />
|
|
<description>
|
|
Method used for polling the MultiplayerAPI. You only need to worry about this if you set [member SceneTree.multiplayer_poll] to [code]false[/code]. By default, [SceneTree] will poll its MultiplayerAPI(s) for you.
|
|
[b]Note:[/b] This method results in RPCs 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="rpc">
|
|
<return type="int" enum="Error" />
|
|
<param index="0" name="peer" type="int" />
|
|
<param index="1" name="object" type="Object" />
|
|
<param index="2" name="method" type="StringName" />
|
|
<param index="3" name="arguments" type="Array" default="[]" />
|
|
<description>
|
|
Sends an RPC to the target [param peer]. The given [param method] will be called on the remote [param object] with the provided [param arguments]. The RPC may also be called locally depending on the implementation and RPC configuration. See [method Node.rpc] and [method Node.rpc_config].
|
|
[b]Note:[/b] Prefer using [method Node.rpc], [method Node.rpc_id], or [code]my_method.rpc(peer, arg1, arg2, ...)[/code] (in GDScript), since they are faster. This method is mostly useful in conjunction with [MultiplayerAPIExtension] when augmenting or replacing the multiplayer capabilities.
|
|
</description>
|
|
</method>
|
|
<method name="set_default_interface" qualifiers="static">
|
|
<return type="void" />
|
|
<param index="0" name="interface_name" type="StringName" />
|
|
<description>
|
|
Sets the default MultiplayerAPI implementation class. This method can be used by modules and extensions to configure which implementation will be used by [SceneTree] when the engine starts.
|
|
</description>
|
|
</method>
|
|
</methods>
|
|
<members>
|
|
<member name="multiplayer_peer" type="MultiplayerPeer" setter="set_multiplayer_peer" getter="get_multiplayer_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_server]) and will set root node's network mode to authority, or it will become a regular client peer. 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>
|
|
</members>
|
|
<signals>
|
|
<signal name="connected_to_server">
|
|
<description>
|
|
Emitted when this MultiplayerAPI's [member multiplayer_peer] successfully connected to a server. Only emitted on clients.
|
|
</description>
|
|
</signal>
|
|
<signal name="connection_failed">
|
|
<description>
|
|
Emitted when this MultiplayerAPI's [member multiplayer_peer] fails to establish a connection to a server. Only emitted on clients.
|
|
</description>
|
|
</signal>
|
|
<signal name="peer_connected">
|
|
<param index="0" name="id" type="int" />
|
|
<description>
|
|
Emitted when this MultiplayerAPI's [member multiplayer_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="peer_disconnected">
|
|
<param index="0" name="id" type="int" />
|
|
<description>
|
|
Emitted when this MultiplayerAPI's [member multiplayer_peer] disconnects from a peer. Clients get notified when other clients disconnect from the same server.
|
|
</description>
|
|
</signal>
|
|
<signal name="server_disconnected">
|
|
<description>
|
|
Emitted when this MultiplayerAPI's [member multiplayer_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_ANY_PEER" value="1" enum="RPCMode">
|
|
Used with [method Node.rpc_config] to set a method to be callable remotely by any peer. Analogous to the [code]@rpc("any_peer")[/code] annotation. Calls are accepted from all remote peers, no matter if they are node's authority or not.
|
|
</constant>
|
|
<constant name="RPC_MODE_AUTHORITY" value="2" enum="RPCMode">
|
|
Used with [method Node.rpc_config] to set a method to be callable remotely only by the current multiplayer authority (which is the server by default). Analogous to the [code]@rpc("authority")[/code] annotation. See [method Node.set_multiplayer_authority].
|
|
</constant>
|
|
</constants>
|
|
</class>
|