gamedev-skills/awesome-gamedev-agent-skills / skills/godot/godot-multiplayer
godot-multiplayer
VerifiedGodot 4.7 high-level multiplayer: ENet host and join, @rpc with rpc_id(), MultiplayerSpawner and MultiplayerSynchronizer, with a two-instance headless test. Use for online or LAN co-op in Godot, or a rejected RPC, spawned nodes missing on clients, or state that does not sync. Not for Roblox (`roblox-networking`), server exports (`godot-export`) or local split-screen (`camera-systems`).
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 with ENet (see
Version notes). Treat all client input as untrusted; keep the server authoritative.
When to use
- Hosting/joining over ENet, writing 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 (PacketPeer); HTTP requests; Roblox → roblox-networking; persistence →
save-systems.
Core workflow
-
Create a peer (
ENetMultiplayerPeer), callcreate_server(port, max_clients)orcreate_client(address, port), check the returnedError, and assign it tomultiplayer.multiplayer_peer. The server's id is always1; clients get random positive ids. -
Handle connection signals on
multiplayer:peer_connected(id),peer_disconnected(id),connected_to_server,connection_failed,server_disconnected. Print each one; the smoke test (step 8) reads those lines. -
Define RPCs with
@rpc(...)and call them on the method'sCallablewithrpc()(all peers) orrpc_id(peer_id)(one peer). Inside,multiplayer.get_remote_sender_id()says who sent it. -
Keep the RPC set identical on every build that runs the script: Godot checksums all
@rpcmethods of a script, and a mismatch prints errors that can name an unrelated RPC. -
Assign authority per node with
set_multiplayer_authority(id); gate input and movement onis_multiplayer_authority(). -
Replicate state with
MultiplayerSpawner(instances scenes on clients) andMultiplayerSynchronizer(syncs chosen properties). Both can be configured in code (Pattern 4), so no Replication-dock clicks are needed. -
Validate on the server. Clients send intent; the server checks it and broadcasts results.
-
Check with two headless instances before you finish. Make the game host or join from command-line user args (Pattern 5), then:
timeout 20 godot --headless --path . -- --host > server.log 2>&1 & sleep 2 timeout 15 godot --headless --path . -- --join 127.0.0.1 > client.log 2>&1 wait grep -nE "^ *(SCRIPT ERROR|ERROR):" server.log client.log # no output = pass grep -n "connected" server.log client.log # your step-2 printsPass means both logs show the handshake prints and no error lines (RPC "not allowed", checksum and "Node not found" errors all print as
ERROR:). With no Godot binary (godot,godot4or$GODOT_BIN), ask the user to run these lines and paste both logs. Gameplay feel still needs a human: ask the user to start two or more windows (editor menu Debug > Customize Run Instances...) and report what desyncs.
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" % error_string(err)); return
multiplayer.multiplayer_peer = peer
multiplayer.peer_connected.connect(func(id: int): print("peer_connected ", id))
func join(address := "127.0.0.1") -> void:
var peer := ENetMultiplayerPeer.new()
var err := peer.create_client(address, PORT)
if err != OK:
push_error("Cannot join: %s" % error_string(err)); return
multiplayer.multiplayer_peer = peer
multiplayer.connected_to_server.connect(func(): print("connected_to_server"))
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 configured from code
@onready var sync: MultiplayerSynchronizer = $MultiplayerSynchronizer
func _ready() -> void:
# Paths are relative to sync.root_path (default "..", the synchronizer's parent).
var config := SceneReplicationConfig.new()
config.add_property(^".:position")
config.property_set_replication_mode(^".:position",
SceneReplicationConfig.REPLICATION_MODE_ALWAYS) # unreliable, every interval
config.add_property(^".:health")
config.property_set_replication_mode(^".:health",
SceneReplicationConfig.REPLICATION_MODE_ON_CHANGE) # reliable, only when changed
sync.replication_config = config
Per-peer visibility (public_visibility, set_visibility_for) is in the reference.
5. Host or join from the command line (for the smoke test)
func _ready() -> void:
var args := OS.get_cmdline_user_args() # only the arguments after `--`
if "--host" in args:
host()
elif "--join" in args:
var i := args.find("--join")
join(args[i + 1] if i + 1 < args.size() else "127.0.0.1")
Gotchas
- RPC checksum. Every
@rpcmethod in a script must exist with the same annotation on client and server builds, even unused ones. Argument names and counts are not part of the check; the set of RPCs and their annotations are. - Default
@rpcis"authority". Calls from other peers are dropped unless the mode is"any_peer". Add"call_local"when the host is also a player. 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 aget_remote_sender_id() == 1check, 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 path; spawn with
identical names everywhere (
MultiplayerSpawner, oradd_child(node, true)after settingname). - Trusting the client. Never let clients set authoritative state (health, position, hits) directly. Send intent, validate on the server, then broadcast.
- RPCs live on Nodes and carry plain data.
@rpcworks only onNode-derived classes, notResource/RefCounted, and Objects and Callables do not serialize. Send ints, strings, arrays, dictionaries and packed arrays. - Disconnect by resetting the peer:
multiplayer.multiplayer_peer = OfflineMultiplayerPeer.new(). - Port already in use in the smoke test → a previous server is still running; the
timeoutwrapper ends it, or pick another port. - Android exports need the INTERNET permission in the export preset, or all networking is blocked.
References
- Read
references/replication-and-rpc.mdwhen you need the full@rpcargument rules,MultiplayerSpawnerwith a customspawn_function, synchronizer visibility filters,SceneMultiplayerauthentication, transfer-mode choices, or a lobby skeleton.
Related skills
godot-nodes-scenesfor instancing the scenes that get spawned and synced.godot-signals-groupsfor connection signals and event flow.godot-exportfor a headless dedicated-server build.godot-gdscript-headless-testingto keep server-logic tests in CI.
Version notes
Last verified: 2026-11-11 against Godot 4.7.2-stable (released 2026-08-18).
SceneReplicationConfig.property_set_sync/property_set_watchare deprecated; useproperty_set_replication_mode().MultiplayerSynchronizer.public_visibilitydefaults totrue;MultiplayerSpawner.spawn()errors without aspawn_function.
Sources: SceneReplicationConfig @ 4.7.2-stable, ENetMultiplayerPeer @ 4.7.2-stable, OS.get_cmdline_user_args @ 4.7.2-stable, High-level multiplayer.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |