The High-Level Multiplayer system in Godot provides an abstraction over low-level networking (sockets, packets) to allow developers to synchronize game state using a scene-tree-oriented approach. It is built around the Remote Procedure Call (RPC) mechanism and specialized nodes for state replication and object spawning.
The architecture is layered, starting from the low-level MultiplayerPeer (transport) up to the SceneTree integration. The MultiplayerAPI serves as the primary interface for managing these connections.
| Class | Responsibility |
|---|---|
MultiplayerAPI | The abstract interface for multiplayer logic. It handles peer management and RPC dispatching. scene/main/multiplayer_api.h41 |
SceneMultiplayer | The default implementation of MultiplayerAPI. It manages the replication of nodes, spawners, and synchronizers. modules/multiplayer/scene_multiplayer.h64 |
MultiplayerPeer | An abstraction for the network transport layer (ENet, WebRTC, etc.). It provides methods for sending and receiving raw packets. modules/multiplayer/doc_classes/SceneMultiplayer.xml3-12 |
MultiplayerSpawner | Automates the instantiation of nodes across all connected peers. modules/multiplayer/multiplayer_spawner.h42 |
MultiplayerSynchronizer | Synchronizes specific properties of a node between peers in real-time. modules/multiplayer/multiplayer_synchronizer.h43 |
The SceneTree typically holds a default MultiplayerAPI instance. However, developers can override this for specific branches using SceneTree.set_multiplayer(), allowing a single engine instance to run both a client and a server simultaneously.
The following diagram illustrates how high-level concepts map to specific classes and methods within the codebase.
Sources: modules/multiplayer/scene_multiplayer.h:64-101(), modules/multiplayer/scene_multiplayer.cpp:153-156(), modules/multiplayer/doc_classes/SceneMultiplayer.xml:3-12()
The Remote Procedure Call (RPC) system allows a peer to call a function on a remote instance of the same node. It relies on NodePath matching across peers to identify target nodes doc/classes/Node.xml17
Node.rpc() or Node.rpc_id().MultiplayerAPI serializes the method name and arguments into a packet.MultiplayerPeer.MultiplayerPeer::get_var() is used to deserialize the packet back into Variant types.MultiplayerAPI.poll() is called (usually automatically by SceneTree). This processes incoming packets and triggers the local function execution scene/main/scene_tree.cpp48-49get_remote_sender_id() can be used to identify which peer initiated the call.The SceneMultiplayer class handles the RPC system through its SceneRPCInterface member.
RPC packets are structured with a command byte, followed by node and method identification, and then serialized arguments. Node paths can be compressed into a numerical ID after the first transmission to save bandwidth.
| Function | Description |
|---|---|
poll() | Must be called regularly to process incoming network events. Triggers signals and RPCs. modules/multiplayer/scene_multiplayer.cpp67-167 |
object_configuration_add() | Used internally to notify the API about new nodes or configurations. modules/multiplayer/scene_multiplayer.cpp300-303 |
is_server() | Checks if the current multiplayer_peer is acting as the authority (ID 1). modules/multiplayer/scene_multiplayer.cpp200-202 |
_parse_rpc_config() | Parses RPC configuration from a node or script, caching method IDs. modules/multiplayer/scene_rpc_interface.cpp75-103 |
_process_rpc() | Decodes and executes an incoming RPC packet. modules/multiplayer/scene_rpc_interface.cpp157-300 |
_send_rpc() | Encodes and sends an RPC packet to a target peer. modules/multiplayer/scene_rpc_interface.cpp302-400 |
Sources: modules/multiplayer/scene_rpc_interface.cpp:30-103(), modules/multiplayer/scene_rpc_interface.cpp:157-300(), modules/multiplayer/scene_rpc_interface.cpp:302-400(), modules/multiplayer/scene_multiplayer.cpp:67-167(), modules/multiplayer/scene_multiplayer.cpp:200-202(), modules/multiplayer/scene_multiplayer.cpp:300-303()
Scene replication is handled by two specialized nodes that work in tandem with SceneMultiplayer.
The MultiplayerSpawner node tracks a specific "spawn path." When a node is added as a child of that path on the authority, the MultiplayerSpawner automatically sends information to all clients to instantiate the same node type. It manages a list of "spawnable scenes" that can be instantiated.
spawnable_scenes: A LocalVector<SpawnableScene> storing paths and cached PackedScene resources. modules/multiplayer/multiplayer_spawner.h51-52spawn_path: The NodePath where spawned nodes will be added as children. modules/multiplayer/multiplayer_spawner.h54_track(): Registers a newly spawned node for tracking. modules/multiplayer/multiplayer_spawner.cpp200-209spawn(): Initiates the spawning process, either by instantiating a scene from spawnable_scenes or calling a custom spawn_function. modules/multiplayer/multiplayer_spawner.cpp260-290on_spawn(): SceneReplicationInterface method called when a node is spawned, responsible for creating and sending the spawn packet. modules/multiplayer/scene_replication_interface.cpp156-172on_spawn_receive(): SceneReplicationInterface method that handles incoming spawn packets, instantiating the node on the remote peer. modules/multiplayer/scene_replication_interface.cpp300-350The MultiplayerSynchronizer node is configured with a list of properties (e.g., position, rotation) and methods. It automatically packs these values and sends them to peers based on a configured update interval or "on change" logic. It also supports visibility filters to control which peers receive updates.
root_path: The NodePath to the node whose properties are being synchronized. modules/multiplayer/multiplayer_synchronizer.h50replication_config: A Ref<SceneReplicationConfig> resource defining which properties and methods to synchronize. modules/multiplayer/multiplayer_synchronizer.h51sync_interval: The frequency at which properties are synchronized. modules/multiplayer/multiplayer_synchronizer.h52visibility_filters: A Vector<Callable> used to determine which peers can see this synchronizer. modules/multiplayer/multiplayer_synchronizer.h55update_outbound_sync_time(): Checks if enough time has passed to send a new sync packet. modules/multiplayer/multiplayer_synchronizer.cpp129-135get_state(): Collects the current values of all configured properties. modules/multiplayer/multiplayer_synchronizer.cpp157-170set_state(): Applies received property values to the target node. modules/multiplayer/multiplayer_synchronizer.cpp174-182on_replication_start(): SceneReplicationInterface method called when a synchronizer starts, registering it for updates. modules/multiplayer/scene_replication_interface.cpp174-186on_sync_receive(): SceneReplicationInterface method that processes incoming synchronization packets and applies the state. modules/multiplayer/scene_replication_interface.cpp352-400on_delta_receive(): SceneReplicationInterface method that processes incoming delta packets. modules/multiplayer/scene_replication_interface.cpp402-440This diagram shows the relationship between the SceneMultiplayer orchestrator and the replication nodes.
Sources: modules/multiplayer/scene_multiplayer.cpp:67-167(), modules/multiplayer/scene_multiplayer.cpp:165-166(), modules/multiplayer/scene_replication_interface.cpp:156-172(), modules/multiplayer/scene_replication_interface.cpp:300-350(), modules/multiplayer/scene_replication_interface.cpp:352-400(), modules/multiplayer/multiplayer_spawner.cpp:260-290(), modules/multiplayer/multiplayer_synchronizer.cpp:129-135(), modules/multiplayer/multiplayer_synchronizer.cpp:157-170(), modules/multiplayer/multiplayer_synchronizer.cpp:174-182()
The MultiplayerAPI tracks the state of the network via signals. When a MultiplayerPeer is assigned to multiplayer_peer, the system transitions into a networked state.
connected_to_server: Emitted on the client when the handshake is complete. modules/multiplayer/scene_multiplayer.cpp210-211connection_failed: Emitted on the client if the server is unreachable. modules/multiplayer/scene_multiplayer.cpp57-58peer_connected(id): Emitted on all peers when a new member joins the session. modules/multiplayer/scene_multiplayer.cpp212-213peer_disconnected(id): Emitted when a member leaves. modules/multiplayer/scene_multiplayer.cpp59-60peer_authenticating(id): Emitted when a new peer connects and an auth_callback is set. modules/multiplayer/doc_classes/SceneMultiplayer.xml93-96peer_authentication_failed(id): Emitted if authentication fails or times out. modules/multiplayer/scene_multiplayer.cpp155-156SceneMultiplayer supports an authentication flow using auth_callback, send_auth(), and complete_auth(). Peers remain in an "authenticating" state until complete_auth() is called by both sides, or auth_timeout expires.
Sources: modules/multiplayer/scene_multiplayer.cpp:56-60(), modules/multiplayer/scene_multiplayer.cpp:155-156(), modules/multiplayer/scene_multiplayer.cpp:210-213(), modules/multiplayer/doc_classes/SceneMultiplayer.xml:93-96()
Multiplayer logic is heavily integrated into the SceneTree and Node lifecycle. Nodes are aware of their network authority via Node::get_multiplayer_authority() and can restrict processing based on peer IDs doc/classes/Node.xml17
Each Viewport can potentially have its own MultiplayerAPI instance, though by default they inherit from the parent or use the SceneTree global instance scene/main/viewport.cpp108-112
Sources: scene/main/scene_tree.cpp:48-51(), scene/main/viewport.cpp:108-118(), doc/classes/Node.xml:17-19()
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.