Godot Multiplayer (4.x high-level)
Connect peers, call functions remotely with @rpc, assign authority, and replicate state
with MultiplayerSpawner/MultiplayerSynchronizer. Targets Godot 4.7 (ENet). Treat
all client input as untrusted; keep the server authoritative.
When to use
- Use when adding networked multiplayer: hosting/joining over ENet, calling RPCs,
assigning per-node authority, or auto-spawning/syncing nodes across peers.
When not to use: local split-screen (no networking); raw TCP/UDP/WebSocket protocol
work (low-level PacketPeer); HTTP requests. For save/persistence → save-systems.
Core workflow
- Create a peer (
ENetMultiplayerPeer), call create_server(port, max) or
create_client(ip, port), and assign it to multiplayer.multiplayer_peer. The
server's unique ID is always 1; clients get random positive IDs.
- Handle connection signals on
multiplayer: peer_connected(id),
peer_disconnected(id), connected_to_server, connection_failed,
server_disconnected.
- Define RPCs with
@rpc(...). Call them on a Callable via rpc() (all peers) or
rpc_id(peer_id) (one peer). Inside, multiplayer.get_remote_sender_id() tells you who
sent it.
- Keep RPC signatures identical on every peer that runs the script — Godot checksums
all
@rpc methods in a script; a mismatch prints errors that can name an unrelated RPC.
- Assign authority per node with
set_multiplayer_authority(id); gate input/RPCs by
is_multiplayer_authority().
- Replicate state with
MultiplayerSpawner (auto-instances scenes on clients) and
MultiplayerSynchronizer (auto-syncs selected properties).
- Validate on the server. Don't trust client-reported positions/results.
Patterns
1. Host or join (ENet)
const PORT := 7000
const MAX_PLAYERS := 8
func host() -> void:
var peer := ENetMultiplayerPeer.new()
var err := peer.create_server(PORT, MAX_PLAYERS)
if err != OK:
push_error("Cannot host: %s" % err); return
multiplayer.multiplayer_peer = peer
multiplayer.peer_connected.connect(_on_peer_connected)
func join(ip := "127.0.0.1") -> void:
var peer := ENetMultiplayerPeer.new()
peer.create_client(ip, PORT)
multiplayer.multiplayer_peer = peer
multiplayer.connected_to_server.connect(func(): print("connected"))
func leave() -> void:
multiplayer.multiplayer_peer = OfflineMultiplayerPeer.new()
2. RPCs: client sends input to the server (any_peer, call_local)
This script sits on a player avatar whose authority is the owning client (Pattern 3), so
the server is not the node's authority. A server→clients RPC on such a node must be
"any_peer" and check that the sender is the server.
func _unhandled_input(event: InputEvent) -> void:
if event.is_action_pressed("fire") and is_multiplayer_authority():
request_fire.rpc_id(1) # send only to the server (id 1)
# Clients may call this; it runs on the server (and locally if server is a player).
@rpc("any_peer", "call_local", "reliable")
func request_fire() -> void:
if not multiplayer.is_server(): # ignore copies relayed to other clients
return
var sender := multiplayer.get_remote_sender_id()
if not _can_fire(sender): # server-side validation
return
spawn_projectile.rpc(sender) # tell everyone to spawn it
# "authority" here would make clients reject the server's call (the client is the
# authority), so accept any peer and keep only calls that come from the server.
@rpc("any_peer", "call_local", "reliable")
func spawn_projectile(owner_id: int) -> void:
if multiplayer.get_remote_sender_id() != 1:
return
_do_spawn(owner_id)
3. Per-node authority (each player controls their own avatar)
extends CharacterBody2D
func _ready() -> void:
# The node name is the owning peer's id; that peer is the authority.
set_multiplayer_authority(name.to_int())
func _physics_process(delta: float) -> void:
if not is_multiplayer_authority():
return # only the owner reads input & moves
velocity = Input.get_vector("left", "right", "up", "down") * 200.0
move_and_slide()
4. MultiplayerSynchronizer config (editor + replication)
# Add a MultiplayerSynchronizer child; in its Replication editor add the properties to
# sync (e.g. position, velocity). Set "Sync"/"Spawn" flags per property. From code you
# can scope visibility:
@onready var sync: MultiplayerSynchronizer = $MultiplayerSynchronizer
func _ready() -> void:
# Only replicate this node to a specific peer (e.g. private info). Per-peer visibility
# matters only once public_visibility is off; by default every peer receives it.
sync.public_visibility = false
sync.set_visibility_for(target_peer_id, true)
Pitfalls
- RPC signature checksum. Every
@rpc method in a script must exist with the same
declaration on both client and server builds — even unused ones. A mismatch causes
errors that may point at the wrong function. Argument names/count are not checked, but
the set of RPCs and their annotations are.
- Default
@rpc is "authority". Clients calling it are ignored unless you set
"any_peer". Use "call_local" so the host (also a player) runs it too.
RPC 'x' is not allowed on node ... from: 1. Mode is "authority" → the server called
an "authority" RPC on a node a client owns. "Authority" means the node's authority, not
the server. Use "any_peer" plus a get_remote_sender_id() == 1 check, or move
server-driven RPCs to a server-owned node (e.g. a game manager).
- NodePaths must match across peers. RPC routing uses the node's path/name; spawn nodes
with identical names on all peers (use
MultiplayerSpawner or add_child(node, true) for
readable, deterministic names).
- Trusting the client. Never let clients set authoritative state (health, position,
hits) directly. Send intent, validate on the server, then broadcast results.
- RPC on non-Node classes fails.
@rpc methods must be on Node-derived classes, not
plain Resource/RefCounted.
- RPCs don't serialize Objects/Callables. Pass plain data (ints, strings, arrays,
dictionaries, PackedArrays).
- Forgetting to reset the peer. To disconnect cleanly, set
multiplayer.multiplayer_peer = OfflineMultiplayerPeer.new().
- Android needs INTERNET permission in the export preset or all networking is blocked.
References
- For
MultiplayerSpawner setup, transfer modes/channels, SceneMultiplayer
authentication (auth_callback/complete_auth), a lobby skeleton, and dedicated-server
export notes, read references/replication-and-rpc.md.
Related skills
godot-nodes-scenes — instancing the scenes that get spawned/synced.
godot-signals-groups — connection signals and event flow.
godot-export — exporting a headless dedicated server build.
1---2name: godot-multiplayer3description: >4 Build networked games with Godot 4.7 high-level multiplayer: set up an5 ENetMultiplayerPeer server/client, define RPCs with the @rpc annotation6 (call via rpc()/rpc_id()), set per-node multiplayer authority, and replicate7 state with MultiplayerSpawner and MultiplayerSynchronizer. Use when adding8 multiplayer/networking to a Godot project, writing @rpc functions, or syncing9 player/world state across peers.10metadata:11 source: https://skillmd.com/skills/junmystery/godot-multiplayer12---1314# Godot Multiplayer (4.x high-level)1516Connect peers, call functions remotely with `@rpc`, assign authority, and replicate state17with `MultiplayerSpawner`/`MultiplayerSynchronizer`. Targets **Godot 4.7** (ENet). Treat18all client input as untrusted; keep the server authoritative.1920## When to use2122- Use when adding networked multiplayer: hosting/joining over ENet, calling RPCs,23 assigning per-node authority, or auto-spawning/syncing nodes across peers.2425**When *not* to use:** local split-screen (no networking); raw TCP/UDP/WebSocket protocol26work (low-level `PacketPeer`); HTTP requests. For save/persistence → `save-systems`.2728## Core workflow29301. **Create a peer** (`ENetMultiplayerPeer`), call `create_server(port, max)` or31 `create_client(ip, port)`, and assign it to `multiplayer.multiplayer_peer`. The32 server's unique ID is always `1`; clients get random positive IDs.332. **Handle connection signals** on `multiplayer`: `peer_connected(id)`,34 `peer_disconnected(id)`, `connected_to_server`, `connection_failed`,35 `server_disconnected`.363. **Define RPCs** with `@rpc(...)`. Call them on a `Callable` via `rpc()` (all peers) or37 `rpc_id(peer_id)` (one peer). Inside, `multiplayer.get_remote_sender_id()` tells you who38 sent it.394. **Keep RPC signatures identical** on every peer that runs the script — Godot checksums40 all `@rpc` methods in a script; a mismatch prints errors that can name an unrelated RPC.415. **Assign authority** per node with `set_multiplayer_authority(id)`; gate input/RPCs by42 `is_multiplayer_authority()`.436. **Replicate state** with `MultiplayerSpawner` (auto-instances scenes on clients) and44 `MultiplayerSynchronizer` (auto-syncs selected properties).457. **Validate on the server.** Don't trust client-reported positions/results.4647## Patterns4849### 1. Host or join (ENet)5051```gdscript52const PORT := 700053const MAX_PLAYERS := 85455func host() -> void:56 var peer := ENetMultiplayerPeer.new()57 var err := peer.create_server(PORT, MAX_PLAYERS)58 if err != OK:59 push_error("Cannot host: %s" % err); return60 multiplayer.multiplayer_peer = peer61 multiplayer.peer_connected.connect(_on_peer_connected)6263func join(ip := "127.0.0.1") -> void:64 var peer := ENetMultiplayerPeer.new()65 peer.create_client(ip, PORT)66 multiplayer.multiplayer_peer = peer67 multiplayer.connected_to_server.connect(func(): print("connected"))6869func leave() -> void:70 multiplayer.multiplayer_peer = OfflineMultiplayerPeer.new()71```7273### 2. RPCs: client sends input to the server (any_peer, call_local)7475This script sits on a player avatar whose authority is the owning client (Pattern 3), so76the server is *not* the node's authority. A server→clients RPC on such a node must be77`"any_peer"` and check that the sender is the server.7879```gdscript80func _unhandled_input(event: InputEvent) -> void:81 if event.is_action_pressed("fire") and is_multiplayer_authority():82 request_fire.rpc_id(1) # send only to the server (id 1)8384# Clients may call this; it runs on the server (and locally if server is a player).85@rpc("any_peer", "call_local", "reliable")86func request_fire() -> void:87 if not multiplayer.is_server(): # ignore copies relayed to other clients88 return89 var sender := multiplayer.get_remote_sender_id()90 if not _can_fire(sender): # server-side validation91 return92 spawn_projectile.rpc(sender) # tell everyone to spawn it9394# "authority" here would make clients reject the server's call (the client is the95# authority), so accept any peer and keep only calls that come from the server.96@rpc("any_peer", "call_local", "reliable")97func spawn_projectile(owner_id: int) -> void:98 if multiplayer.get_remote_sender_id() != 1:99 return100 _do_spawn(owner_id)101```102103### 3. Per-node authority (each player controls their own avatar)104105```gdscript106extends CharacterBody2D107108func _ready() -> void:109 # The node name is the owning peer's id; that peer is the authority.110 set_multiplayer_authority(name.to_int())111112func _physics_process(delta: float) -> void:113 if not is_multiplayer_authority():114 return # only the owner reads input & moves115 velocity = Input.get_vector("left", "right", "up", "down") * 200.0116 move_and_slide()117```118119### 4. MultiplayerSynchronizer config (editor + replication)120121```gdscript122# Add a MultiplayerSynchronizer child; in its Replication editor add the properties to123# sync (e.g. position, velocity). Set "Sync"/"Spawn" flags per property. From code you124# can scope visibility:125@onready var sync: MultiplayerSynchronizer = $MultiplayerSynchronizer126127func _ready() -> void:128 # Only replicate this node to a specific peer (e.g. private info). Per-peer visibility129 # matters only once public_visibility is off; by default every peer receives it.130 sync.public_visibility = false131 sync.set_visibility_for(target_peer_id, true)132```133134## Pitfalls135136- **RPC signature checksum.** Every `@rpc` method in a script must exist with the same137 declaration on both client and server builds — *even unused ones*. A mismatch causes138 errors that may point at the wrong function. Argument names/count are not checked, but139 the set of RPCs and their annotations are.140- **Default `@rpc` is `"authority"`.** Clients calling it are ignored unless you set141 `"any_peer"`. Use `"call_local"` so the host (also a player) runs it too.142- **`RPC 'x' is not allowed on node ... from: 1. Mode is "authority"`** → the server called143 an `"authority"` RPC on a node a client owns. "Authority" means the node's authority, not144 the server. Use `"any_peer"` plus a `get_remote_sender_id() == 1` check, or move145 server-driven RPCs to a server-owned node (e.g. a game manager).146- **NodePaths must match across peers.** RPC routing uses the node's path/name; spawn nodes147 with identical names on all peers (use `MultiplayerSpawner` or `add_child(node, true)` for148 readable, deterministic names).149- **Trusting the client.** Never let clients set authoritative state (health, position,150 hits) directly. Send *intent*, validate on the server, then broadcast results.151- **RPC on non-Node classes fails.** `@rpc` methods must be on `Node`-derived classes, not152 plain `Resource`/`RefCounted`.153- **RPCs don't serialize Objects/Callables.** Pass plain data (ints, strings, arrays,154 dictionaries, PackedArrays).155- **Forgetting to reset the peer.** To disconnect cleanly, set156 `multiplayer.multiplayer_peer = OfflineMultiplayerPeer.new()`.157- **Android needs INTERNET permission** in the export preset or all networking is blocked.158159## References160161- For `MultiplayerSpawner` setup, transfer modes/channels, `SceneMultiplayer`162 authentication (`auth_callback`/`complete_auth`), a lobby skeleton, and dedicated-server163 export notes, read `references/replication-and-rpc.md`.164165## Related skills166167- `godot-nodes-scenes` — instancing the scenes that get spawned/synced.168- `godot-signals-groups` — connection signals and event flow.169- `godot-export` — exporting a headless dedicated server build.