MultiplayerAPI

Inherits: Reference < Object

High-level multiplayer API.

Description

This class implements most of the logic behind the high-level multiplayer API. See also NetworkedMultiplayerPeer.

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 Node.custom_multiplayer property, effectively allowing to run both client and server in the same scene.

Note: The high-level multiplayer API protocol is an implementation detail and isn't meant to be used by non-Redot servers. It may change without notice.

Properties

bool

allow_object_decoding

false

NetworkedMultiplayerPeer

network_peer

bool

refuse_new_network_connections

false

Node

root_node

Methods

void

clear ( )

PoolIntArray

get_network_connected_peers ( ) const

int

get_network_unique_id ( ) const

int

get_rpc_sender_id ( ) const

bool

has_network_peer ( ) const

bool

is_network_server ( ) const

void

poll ( )

Error

send_bytes ( PoolByteArray bytes, int id=0, TransferMode mode=2 )

Signals

connected_to_server ( )

Emitted when this MultiplayerAPI's network_peer successfully connected to a server. Only emitted on clients.

connection_failed ( )

Emitted when this MultiplayerAPI's network_peer fails to establish a connection to a server. Only emitted on clients.

network_peer_connected ( int id )

Emitted when this MultiplayerAPI's 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).

network_peer_disconnected ( int id )

Emitted when this MultiplayerAPI's network_peer disconnects from a peer. Clients get notified when other clients disconnect from the same server.

network_peer_packet ( int id, PoolByteArray packet )

Emitted when this MultiplayerAPI's network_peer receive a packet with custom data (see send_bytes). ID is the peer ID of the peer that sent the packet.

server_disconnected ( )

Emitted when this MultiplayerAPI's network_peer disconnects from server. Only emitted on clients.

Enumerations

enum RPCMode:

RPCMode RPC_MODE_DISABLED = 0

Used with Node.rpc_config or Node.rset_config to disable a method or property for all RPC calls, making it unavailable. Default for all methods.

RPCMode RPC_MODE_REMOTE = 1

Used with Node.rpc_config or Node.rset_config to set a method to be called or a property to be changed only on the remote end, not locally. Analogous to the remote keyword. Calls and property changes are accepted from all remote peers, no matter if they are node's master or puppets.

RPCMode RPC_MODE_MASTER = 2

Used with Node.rpc_config or Node.rset_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 master keyword. Only accepts calls or property changes from the node's network puppets, see Node.set_network_master.

RPCMode RPC_MODE_PUPPET = 3

Used with Node.rpc_config or Node.rset_config to set a method to be called or a property to be changed only on puppets for this node. Analogous to the puppet keyword. Only accepts calls or property changes from the node's network master, see Node.set_network_master.

RPCMode RPC_MODE_SLAVE = 3

Deprecated. Use RPC_MODE_PUPPET instead. Analogous to the slave keyword.

RPCMode RPC_MODE_REMOTESYNC = 4

Behave like RPC_MODE_REMOTE but also make the call or property change locally. Analogous to the remotesync keyword.

RPCMode RPC_MODE_SYNC = 4

Deprecated. Use RPC_MODE_REMOTESYNC instead. Analogous to the sync keyword.

RPCMode RPC_MODE_MASTERSYNC = 5

Behave like RPC_MODE_MASTER but also make the call or property change locally. Analogous to the mastersync keyword.

RPCMode RPC_MODE_PUPPETSYNC = 6

Behave like RPC_MODE_PUPPET but also make the call or property change locally. Analogous to the puppetsync keyword.

Property Descriptions

bool allow_object_decoding = false

  • void set_allow_object_decoding ( bool value )

  • bool is_object_decoding_allowed ( )

If true (or if the network_peer has PacketPeer.allow_object_decoding set to true), the MultiplayerAPI will allow encoding and decoding of object during RPCs/RSETs.

Warning: 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.

NetworkedMultiplayerPeer 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 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.

bool refuse_new_network_connections = false

  • void set_refuse_new_network_connections ( bool value )

  • bool is_refusing_new_network_connections ( )

If true, the MultiplayerAPI's network_peer refuses new incoming connections.

Node root_node

  • void set_root_node ( Node value )

  • Node 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.

Method Descriptions

void clear ( )

Clears the current MultiplayerAPI network state (you shouldn't call this unless you know what you are doing).

PoolIntArray get_network_connected_peers ( ) const

Returns the peer IDs of all connected peers of this MultiplayerAPI's network_peer.

int get_network_unique_id ( ) const

Returns the unique peer ID of this MultiplayerAPI's network_peer.

int get_rpc_sender_id ( ) const

Returns the sender's peer ID for the RPC currently being executed.

Note: If not inside an RPC this method will return 0.

bool has_network_peer ( ) const

Returns true if there is a network_peer set.

bool is_network_server ( ) const

Returns true if this MultiplayerAPI's network_peer is in server mode (listening for connections).

void poll ( )

Method used for polling the MultiplayerAPI. You only need to worry about this if you are using Node.custom_multiplayer override or you set SceneTree.multiplayer_poll to false. By default, SceneTree will poll its MultiplayerAPI for you.

Note: This method results in RPCs and RSETs being called, so they will be executed in the same context of this function (e.g. _process, physics, Thread).

Error send_bytes ( PoolByteArray bytes, int id=0, TransferMode mode=2 )

Sends the given raw bytes to a specific peer identified by id (see NetworkedMultiplayerPeer.set_target_peer). Default ID is 0, i.e. broadcast to all peers.