MultiplayerAPI
Inherited by: MultiplayerAPIExtension, SceneMultiplayer
High-level multiplayer API interface.
Description
Section titled “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 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.
Properties
Section titled “Properties”| Type | Name | Default |
|---|---|---|
| MultiplayerPeer | multiplayer_peer |
Methods
Section titled “Methods”| Returns | Method |
|---|---|
| MultiplayerAPI | create_default_interface() |
| StringName | get_default_interface() |
[]i32 | get_peers() |
| int | get_remote_sender_id() |
| int | get_unique_id() |
| bool | has_multiplayer_peer() |
| bool | is_server() |
| Error | object_configuration_add(object, configuration) |
| Error | object_configuration_remove(object, configuration) |
| Error | poll() |
| Error | rpc(peer, object, method, arguments) |
| void | set_default_interface(interface_name) |
Signals
Section titled “Signals”connected_to_server
Section titled “connected_to_server”connected_to_server()Emitted when this MultiplayerAPI’s multiplayer_peer successfully connected to a server. Only emitted on clients.
connection_failed
Section titled “connection_failed”connection_failed()Emitted when this MultiplayerAPI’s multiplayer_peer fails to establish a connection to a server. Only emitted on clients.
peer_connected
Section titled “peer_connected”peer_connected(id: int)Emitted when this MultiplayerAPI’s 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).
peer_disconnected
Section titled “peer_disconnected”peer_disconnected(id: int)Emitted when this MultiplayerAPI’s multiplayer_peer disconnects from a peer. Clients get notified when other clients disconnect from the same server.
server_disconnected
Section titled “server_disconnected”server_disconnected()Emitted when this MultiplayerAPI’s multiplayer_peer disconnects from server. Only emitted on clients.
Enumerations and constants
Section titled “Enumerations and constants”enum RPCMode
Section titled “enum RPCMode”- RPC_MODE_DISABLED =
0— Used withActor.rpc_config()to disable a method or property for all RPC calls, making it unavailable. Default for all methods.
- RPC_MODE_ANY_PEER =
1— Used withActor.rpc_config()to set a method to be callable remotely by any peer. Calls are accepted from all remote peers, no matter if they are actor’s authority or not.
- RPC_MODE_AUTHORITY =
2— Used withActor.rpc_config()to set a method to be callable remotely only by the current multiplayer authority (which is the server by default). SeeActor.set_multiplayer_authority().
Property descriptions
Section titled “Property descriptions”multiplayer_peer
Section titled “multiplayer_peer”MultiplayerPeer multiplayer_peer
Setter/getter: set_multiplayer_peer(), 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 is_server()) and will set root actor’s network mode to authority, or it will become a regular client peer. All child actors 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.
Method descriptions
Section titled “Method descriptions”create_default_interface
Section titled “create_default_interface”MultiplayerAPI create_default_interface() static
Returns a new instance of the default MultiplayerAPI.
get_default_interface
Section titled “get_default_interface”StringName get_default_interface() static
Returns the default MultiplayerAPI implementation class name. This is usually "SceneMultiplayer" when SceneMultiplayer is available. See set_default_interface().
get_peers
Section titled “get_peers”[]i32 get_peers()
Returns the peer IDs of all connected peers of this MultiplayerAPI’s multiplayer_peer.
get_remote_sender_id
Section titled “get_remote_sender_id”int get_remote_sender_id()
Returns the sender’s peer ID for the RPC currently being executed.
Note: This method returns 0 when called outside of an RPC. As such, the original peer ID may be lost when code execution is delayed (such as with Grost’s await keyword).
get_unique_id
Section titled “get_unique_id”int get_unique_id()
Returns the unique peer ID of this MultiplayerAPI’s multiplayer_peer.
has_multiplayer_peer
Section titled “has_multiplayer_peer”bool has_multiplayer_peer()
Returns true if there is a multiplayer_peer set.
is_server
Section titled “is_server”bool is_server()
Returns true if this MultiplayerAPI’s multiplayer_peer is valid and in server mode (listening for connections).
object_configuration_add
Section titled “object_configuration_add”Error object_configuration_add(object: Object, configuration: Variant)
Notifies the MultiplayerAPI of a new configuration for the given object. This method is used internally by SceneTree to configure the root path for this MultiplayerAPI (passing null and a valid NodePath as 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.
Note: This method is mostly relevant when extending or overriding the MultiplayerAPI behavior via MultiplayerAPIExtension.
object_configuration_remove
Section titled “object_configuration_remove”Error object_configuration_remove(object: Object, configuration: Variant)
Notifies the MultiplayerAPI to remove a configuration for the given object. This method is used internally by SceneTree to configure the root path for this MultiplayerAPI (passing null and an empty NodePath as 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.
Note: This method is mostly relevant when extending or overriding the MultiplayerAPI behavior via MultiplayerAPIExtension.
Error poll()
Method used for polling the MultiplayerAPI. You only need to worry about this if you set SceneTree.multiplayer_poll to false. By default, SceneTree will poll its MultiplayerAPI(s) for you.
Note: This method results in RPCs being called, so they will be executed in the same context of this function (e.g. _process, physics, Thread).
Error rpc(peer: int, object: Object, method: StringName, arguments: Array = [])
Sends an RPC to the target peer. The given method will be called on the remote object with the provided arguments. The RPC may also be called locally depending on the implementation and RPC configuration. See Actor.rpc() and Actor.rpc_config().
Note: Prefer using Actor.rpc(), Actor.rpc_id(), or my_method.rpc(peer, arg1, arg2, ...) (in Grost), since they are faster. This method is mostly useful in conjunction with MultiplayerAPIExtension when extending or replacing the multiplayer capabilities.
set_default_interface
Section titled “set_default_interface”void set_default_interface(interface_name: StringName) static
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.