Multiplayer

Purpose

modules/multiplayer/ is Godot's high-level networking layer. It extends the abstract MultiplayerAPI (defined in scene/main/multiplayer_api.cpp) with a scene-tree-aware implementation that supports @rpc-decorated method calls, automatic property synchronization on tracked nodes, and dynamic spawn/despawn of nodes on connecting peers. Transport (TCP, UDP via ENet, WebSocket, WebRTC) is handled by sibling modules; this module is what most game code interacts with.

Directory layout

modules/multiplayer/
├── scene_multiplayer.{cpp,h}                The SceneMultiplayer (default MultiplayerAPI impl)
├── scene_rpc_interface.{cpp,h}              Handles @rpc dispatch + serialization
├── scene_replication_interface.{cpp,h}      Property + spawn replication
├── scene_replication_config.{cpp,h}         SceneReplicationConfig resource
├── scene_cache_interface.{cpp,h}            Scene path interning across peers
├── multiplayer_spawner.{cpp,h}              MultiplayerSpawner node
├── multiplayer_synchronizer.{cpp,h}         MultiplayerSynchronizer node
├── multiplayer_debugger.{cpp,h}             Editor debugger panel showing replicated state
├── editor/                                  SceneReplicationEditor (the inspector panel for the synchronizer)
├── doc_classes/, icons/, register_types.cpp, tests/

SceneMultiplayer

SceneMultiplayer (scene_multiplayer.cpp) is the default MultiplayerAPI implementation that SceneTree instantiates. Responsibilities:

• Owns a MultiplayerPeer (the transport, e.g., ENetMultiplayerPeer, WebSocketMultiplayerPeer, WebRTCMultiplayerPeer, OfflineMultiplayerPeer).
• Tracks the local peer ID and the connected peer set.
• Routes incoming packets through one of three sub-interfaces:
  • RPC interface for @rpc calls.
  • Replication interface for spawn/despawn + property sync.
  • Cache interface for resolving node paths via short integer IDs (so packets carry "node 17" instead of "/root/Game/Players/Player1").
• Encrypts traffic when an MultiplayerPeer reports itself as untrusted.

RPC

GDScript and C# can mark a method with @rpc(...):

@rpc("any_peer", "call_local", "reliable")
func chat_message(text: String):
    ...

# elsewhere
chat_message.rpc("hello world")              # broadcast
chat_message.rpc_id(peer_id, "private")     # targeted

The decorator's metadata (mode, transfer_mode, transfer_channel, call_local flag) is registered in Node's RPC table. SceneRPCInterface (scene_rpc_interface.cpp):

1. Verifies the caller is allowed to invoke this RPC on this node (multiplayer authority + mode).
2. Looks up the node's path/id via SceneCacheInterface.
3. Marshals arguments through Variant's binary serialization (Marshalls).
4. Sends through the active MultiplayerPeer with the appropriate channel/transfer mode.
5. On receipt, reverses the process and invokes the method on the matching node.

Replication

MultiplayerSynchronizer is a node attached to any Node whose properties should auto-sync. Attach a SceneReplicationConfig resource that lists which properties to sync, when (always, on_change), and at what rate. The replication interface:

• Tracks per-property dirty bits and last-sent values.
• Emits delta packets (only changed properties) at the configured rate.
• Applies received packets on remote peers, with optional spawn/despawn coordination via MultiplayerSpawner.

MultiplayerSpawner watches a list of "spawnable" scene paths under a parent node. When the authority spawns one of those scenes, the spawner sends a packet that other peers use to instantiate the same scene at the same path. Custom spawn data can be passed through _spawn_custom.

Scene path caching

SceneCacheInterface (scene_cache_interface.cpp) interns node paths so messages carry small integers instead of full paths. The cache is built on first reference: when peer A sends a message about /root/Game/Players/Player1, both sides agree on a numeric id (negotiated in a one-shot exchange) and use that id for subsequent traffic.

Transports

The actual networking is provided by sibling modules; MultiplayerAPI is transport-agnostic:

Module	Class	Use
enet	ENetMultiplayerPeer (ENet wrapper)	Reliable + unreliable UDP, default
websocket	WebSocketMultiplayerPeer	WS over TCP/TLS; web platform only or plain text
webrtc	WebRTCMultiplayerPeer	NAT-traversed peer-to-peer
multiplayer	OfflineMultiplayerPeer	No-op peer for single-player mode

Authority

Each Node has a multiplayer_authority (default 1, the server). Methods like Node::is_multiplayer_authority() and the @rpc("authority", ...) mode use this to gate behavior. Spawners and synchronizers only emit packets from the authority for their target subtree.

Debugger integration

MultiplayerDebugger registers panels in the editor's debugger that show:

• Per-node bandwidth usage.
• Replicated property history.
• RPC call rate and timing.

The data is streamed from the running game via EngineDebugger and rendered by editor-side code.

Key abstractions

Abstraction	File	Role
MultiplayerAPI	scene/main/multiplayer_api.cpp	Abstract API tied to SceneTree
SceneMultiplayer	modules/multiplayer/scene_multiplayer.cpp	Default impl
MultiplayerPeer	scene/main/multiplayer_peer.cpp	Transport interface
SceneRPCInterface	modules/multiplayer/scene_rpc_interface.cpp	RPC dispatch
SceneReplicationInterface	modules/multiplayer/scene_replication_interface.cpp	Property + spawn replication
SceneCacheInterface	modules/multiplayer/scene_cache_interface.cpp	Path id negotiation
MultiplayerSpawner, MultiplayerSynchronizer	scene-tree nodes	User-facing replication helpers
SceneReplicationConfig	modules/multiplayer/scene_replication_config.cpp	Resource describing what to sync

Integration points

• Node exposes rpc_config, set_multiplayer_authority, get_multiplayer_authority. Scripts mark methods @rpc to populate the table.
• The transport modules (ENet, WebSocket, WebRTC) only need to implement MultiplayerPeer; the rest of the multiplayer flow is shared.
• The editor's "Replication" panel is a SceneReplicationEditor plugin that lets users compose SceneReplicationConfig visually.

Entry points for modification

• Custom replication strategies → subclass SceneReplicationInterface, install via a custom MultiplayerAPI (not common, but possible).
• New RPC mode → declare an RPCMode value, handle it in SceneRPCInterface::_send_rpc + the receiver authority check.
• New transport → subclass MultiplayerPeerExtension (a MultiplayerPeer with extension points) and ship it as a module or GDExtension.