How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill godot-multiplayerBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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)or
create_client(address, port), check the returned Error, and assign it to multiplayer.multiplayer_peer. The server's 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. Print each one; the smoke test (step 8) reads those lines.
- Define RPCs with
@rpc(...)and call them on the method'sCallablewithrpc()
(all peers) or rpc_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
@rpc methods 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 on is_multiplayer_authority().
- Replicate state with
MultiplayerSpawner(instances scenes on clients) and
MultiplayerSynchronizer (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, godot4 or $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 (anypeer, calllocal)
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 = configPer-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 `@rpc` is `"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 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 path; spawn with
identical names everywhere (MultiplayerSpawner, or add_child(node, true) after setting name).
- 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, not Resource/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
timeout wrapper 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,
MultiplayerSpawner with a custom spawn_function, synchronizer visibility filters, SceneMultiplayer authentication, 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; use
property_set_replication_mode().
MultiplayerSynchronizer.public_visibilitydefaults totrue;MultiplayerSpawner.spawn()
errors without a spawn_function.
Sources: SceneReplicationConfig @ 4.7.2-stable, ENetMultiplayerPeer @ 4.7.2-stable, OS.get_cmdline_user_args @ 4.7.2-stable, High-level multiplayer.