Class SceneMultiplayer

High-level multiplayer API implementation.

Inheritance

MultiplayerAPI

RefCounted

Object

SceneMultiplayer

Remarks

This class is the default implementation of MultiplayerAPI, used to provide multiplayer functionalities in Godot Engine.

This implementation supports RPCs via Node.rpc and Node.rpc_id and requires MultiplayerAPI.rpc to be passed a Node (it will fail for other object types).

This implementation additionally provide SceneTree replication via the MultiplayerSpawner and MultiplayerSynchronizer nodes, and the SceneReplicationConfig resource.

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

Note: When exporting to Android, make sure to enable the INTERNET permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android.

Properties

allow_object_decoding

If true, the MultiplayerAPI will allow encoding and decoding of object during RPCs.

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 threat such as remote code execution.

var allow_object_decoding : bool = false

Property Value

bool

Remarks

• void set_allow_object_decoding(bool value)
• bool is_object_decoding_allowed

auth_callback

The callback to execute when receiving authentication data sent via SceneMultiplayer.send_auth. If the Callable is empty (default), peers will be automatically accepted as soon as they connect.

var auth_callback : Callable = Callable()

Property Value

Callable

Remarks

• void set_auth_callback(Callable value)
• Callable get_auth_callback

auth_timeout

If set to a value greater than 0.0, the maximum duration in seconds peers can stay in the authenticating state, after which the authentication will automatically fail. See the SceneMultiplayer.peer_authenticating and SceneMultiplayer.peer_authentication_failed signals.

var auth_timeout : float = 3.0

Property Value

float

Remarks

• void set_auth_timeout(float value)
• float get_auth_timeout

max_delta_packet_size

Maximum size of each delta packet. Higher values increase the chance of receiving full updates in a single frame, but also the chance of causing networking congestion (higher latency, disconnections). See MultiplayerSynchronizer.

var max_delta_packet_size : int = 65535

Property Value

int

Remarks

• void set_max_delta_packet_size(int value)
• int get_max_delta_packet_size

max_sync_packet_size

Maximum size of each synchronization packet. Higher values increase the chance of receiving full updates in a single frame, but also the chance of packet loss. See MultiplayerSynchronizer.

var max_sync_packet_size : int = 1350

Property Value

int

Remarks

• void set_max_sync_packet_size(int value)
• int get_max_sync_packet_size

refuse_new_connections

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

var refuse_new_connections : bool = false

Property Value

bool

Remarks

• void set_refuse_new_connections(bool value)
• bool is_refusing_new_connections

root_path

The root path to use for RPCs and replication. 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.

var root_path : NodePath = NodePath("")

Property Value

NodePath

Remarks

• void set_root_path(NodePath value)
• NodePath get_root_path

server_relay

Enable or disable the server feature that notifies clients of other peers' connection/disconnection, and relays messages between them. When this option is false, clients won't be automatically notified of other peers and won't be able to send them packets through the server.

Note: Changing this option while other peers are connected may lead to unexpected behaviors.

Note: Support for this feature may depend on the current MultiplayerPeer configuration. See is_server_relay_supported.

var server_relay : bool = true

Property Value

bool

Remarks

• void set_server_relay_enabled(bool value)
• bool is_server_relay_enabled

Methods

clear

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

void clear

complete_auth(int)

Mark the authentication step as completed for the remote peer identified by id. The MultiplayerAPI.peer_connected signal will be emitted for this peer once the remote side also completes the authentication. No further authentication messages are expected to be received from this peer.

If a peer disconnects before completing authentication, either due to a network issue, the auth_timeout expiring, or manually calling SceneMultiplayer.disconnect_peer, the SceneMultiplayer.peer_authentication_failed signal will be emitted instead of MultiplayerAPI.peer_disconnected.

int complete_auth(int id)

Parameters

id int

disconnect_peer(int)

Disconnects the peer identified by id, removing it from the list of connected peers, and closing the underlying connection with it.

void disconnect_peer(int id)

Parameters

id int

get_authenticating_peers

Returns the IDs of the peers currently trying to authenticate with this MultiplayerAPI.

PackedInt32Array get_authenticating_peers

send_auth(int, PackedByteArray)

Sends the specified data to the remote peer identified by id as part of an authentication message. This can be used to authenticate peers, and control when MultiplayerAPI.peer_connected is emitted (and the remote peer accepted as one of the connected peers).

int send_auth(int id, PackedByteArray data)

Parameters

id int

data PackedByteArray

send_bytes(PackedByteArray, int, int, int)

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

int send_bytes(PackedByteArray bytes, int id, int mode, int channel)

Parameters

bytes PackedByteArray

id int

mode int

channel int

Events

peer_authenticating(int)

Emitted when this MultiplayerAPI's multiplayer_peer connects to a new peer and a valid auth_callback is set. In this case, the MultiplayerAPI.peer_connected will not be emitted until SceneMultiplayer.complete_auth is called with given peer id. While in this state, the peer will not be included in the list returned by get_peers (but in the one returned by get_authenticating_peers), and only authentication data will be sent or received. See SceneMultiplayer.send_auth for sending authentication data.

signal peer_authenticating(int id)

Parameters

id int

peer_authentication_failed(int)

Emitted when this MultiplayerAPI's multiplayer_peer disconnects from a peer for which authentication had not yet completed. See SceneMultiplayer.peer_authenticating.

signal peer_authentication_failed(int id)

Parameters

id int

peer_packet(int, PackedByteArray)

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

signal peer_packet(int id, PackedByteArray packet)

Parameters

id int

packet PackedByteArray