Scenario Godot Multiplayer

---
name: scenario-godot-multiplayer
description: "Use when a Godot 4 game goes online or co-op: host and join with ENet, WebSocket for a web build, RPCs (@rpc, rpc_id, any_peer), MultiplayerSpawner and MultiplayerSynchronizer, player authority, lobbies and login, a dedicated or headless server export, lag, rubber-banding, prediction or netfox, cheating, bandwidth, Steam, Nakama or WebRTC. Symptoms: players do not appear on the client, 'rpc node checksum failed', 'node not found' on an RPC, desync, the server build is huge, a client never connects."
license: MIT
---

# Godot multiplayer (network programmer)

Target: Godot 4.7.2, SceneMultiplayer over ENet and WebSocket.

Expert level here means the networked game is proven with several processes, under injected latency, before anyone plays it: authority is a written decision per object, every client message is a request the server checks, and replication cost is measured in KiB/s. This skill builds the replication in code, runs a server and 2 to 3 clients headless on localhost (plus a browser client), and passes only on numbers from those runs. If a sibling skill named here is missing from your available skills, ask the user to install it (`npx skills add scenario-labs/skills --skill <name>`); unattended, proceed from tool schemas and flag the gap.

**REQUIRED BACKGROUND:** scenario-godot-expert (channels, `gd_run`, review loop, 4.7 traps).

**Status (2026-10-02):** 16 live tests (up to 3 clients, ENet, WebSocket, exported server, headless Chrome) and 18 offline tests pass. Evidence: `tests/live_evidence/godot-multiplayer/`.

## Stance (the expert delta)

1. **Decide authority per object before writing code.** Someone must own each object's data (AndrooDev, jff9oxO8v1s [00:04:01]). Client authority over the body is fine for casual co-op; competitive or cheat-prone games keep the body on the server and give clients their input only (Tamas Galffy, iP_xdJ0peFo [00:03:46, 00:06:47]; BatteryAcidDev, GqHTNmRspjU [00:00:33]). Deciding condition: cost of cheating against cost of input lag. Measured at 250 ms RTT: server authority shows your own move after 294 to 310 ms, client authority after 11 to 22 ms, and a client-authority cheater's 50 m jump stuck.
2. **Set authority from the node name in `_enter_tree`.** Name each player node with its peer id; `_enter_tree` calls `set_multiplayer_authority(name.to_int())` so it holds before `_ready` (Travis Hunter, tK2ACXUGcrY [00:46:16]). Do not read a spawn-synced property there: on every client copy measured, `peer_id` was still 0 in `_enter_tree`.
3. **Every `any_peer` RPC is a request.** Read `multiplayer.get_remote_sender_id()` first (it is 0 after an `await`, measured), check that the sender owns the target and that the values are possible, then act. A forged teleport for another player and a 30 m jump were both rejected in the live test.
4. **The RPC checksum compares method names only, whatever the docs say.** The high-level docs say it covers every `@rpc` declaration and skips arguments; two live runs in 4.7.2 (M2, round 1 and round 2) disagree. A name missing on one side logs "The rpc node checksum failed" on both sides and RPCs are matched by sorted index: the client called `b` and the server ran `a`. A different mode only fails per call ("not allowed"), a different argument count fails per call ("expected 2 argument(s)"), different `call_local` or transfer mode passes silently. Keep server and client on one script per node path (one codebase: Davide Di Staso, nyKBuM9Y_-Q).
5. **Test with latency and three players.** Localhost hides every latency bug; two players hide what a bystander sees (Galffy, iP_xdJ0peFo [00:09:58, 00:42:31]). `gd_net.UdpLagProxy` adds delay, jitter and loss on localhost without root.
6. **Replication cost is a design input.** ALWAYS sends every network frame whether or not the value changed; ON_CHANGE is reliable and costs more than ALWAYS while values move (measured: 72.6 against 100 KiB/s for 50 moving props). A headless server is uncapped: 145 fps here, 2.2 to 2.4 times the bandwidth of 60 fps. Cap it (`--max-fps`, `Engine.max_fps`) or set `replication_interval`. Cut by visibility (Di Staso [00:14:29]).
7. **Know which connection event fires where.** On a joining client, `peer_connected` fires once per existing peer, server id 1 included; `connected_to_server` fires on clients only, so send client info there, not from `peer_connected` (docs delta 7; FinePointCGI e0JLO_5UgQo [00:22:50]). After the server leaves, `get_unique_id()` reads 0: skip id 0 in registries and spawn loops (pA9RGn87Uag [00:47:31]). All measured (M14).
8. **The server stops speed hacks, not wall hacks.** Server authority blocks impossible moves and infinite health; it does not stop wall hacks or aimbots, because every client still receives everyone's position. Interest management (synchronizer visibility, server line-of-sight checks) limits the leak (MfjEB1cowsE [00:18:55]; iP_xdJ0peFo [00:53:28]).
9. **The dedicated server is the same project exported in "dedicated server" mode.** That mode adds the `dedicated_server` feature, which forces headless display and dummy audio even without `--headless` (measured on the exported macOS binary), and Strip Visuals removed the 3.1 MB texture from the server pack (BatteryAcidDev, jgJuX04cq7k [00:04:47]).

## Establish first

Genre and player count; who may cheat (competitive, co-op, friends only); platforms (browser means WebSocket or WebRTC, no ENet); topology (dedicated server, listen server, relay or P2P); a backend already chosen (Steam, Nakama, Colyseus, own server); hosting budget (cloud costs money: ask before any deployment); tick and target RTT (default 60 Hz server, play tested at 100 and 250 ms). Defaults: one project, server authority with input-only clients for anything competitive, ENet for desktop and mobile, WebSocket behind TLS (`wss://`) for the web.

## Workflow

1. **Network design note.** Per object: owner, what replicates (synchronizer property and mode), what is an event (RPC with mode, transfer and channel), what a client may request. Streams of unreliable_ordered updates get their own transfer channel, channel last in `@rpc` (docs deltas 4, 5); idle players send nothing below a velocity threshold (pA9RGn87Uag [00:42:16]). GATE: no object without an owner; no client-owned health, score or inventory unless the brief accepts cheating.
2. **Build the replication in code.** `gd_net.install_netkit(P)`, then [`net_build.gd`](scripts/agentkit/multiplayer/net_build.gd) (`make_sync`, `make_spawner`) writes scenes with `SceneReplicationConfig` set in code; the Replication panel is for humans ([`references/gui-paths.md`](references/gui-paths.md)). Players: name = peer id, `add_child(node, true)`, authority in `_enter_tree`. GATE: `net_audit.gd:scene` has no flags (root paths resolve, no Object or RID property, no `@Node@2` names, intervals match modes).
3. **Session test on localhost.** `gd_net.session(P, roles)` runs a server and 2 to 3 clients, each in its own APFS clone, all machine slots held first. Cover the lobby gate, a late joiner, a leaver, cheat RPCs, and a password through `auth_callback` plus `complete_auth` on both sides (P5). GATE: every client sees every player, the late joiner sees all, the leaver's node is freed everywhere, authority report correct, forged RPCs rejected, logs clean.
4. **Latency pass.** Rerun through `UdpLagProxy` at 100 and 250 ms, then 250 ms with 30 ms jitter and 5 % loss; `replication_delay()` measures how far behind the server truth a remote client shows a player. GATE: the numbers fit the genre, or prediction is planned (netfox or own).
5. **Bandwidth pass.** Server KiB/s per client from ENet counters (`bandwidth` in the result), per mode, interval and visibility. GATE: under the budget at max players, fps capped.
6. **Web and transports.** Same session with `transport="websocket"`; for a browser build, export Web and run the client in headless Chrome (procedure P9). WebSocket is TCP: "unreliable" RPCs arrive reliable and ordered, with head-of-line blocking under loss; WebRTC gives unreliable browser channels but needs signalling, STUN/TURN and webrtc-native on desktop (WebRTC doc; wgIqB6JNcro [00:19:35]). An HTTPS page needs `wss://`. A background tab stops `_process` and the socket drops: build reconnect (web doc). GATE: the browser client joins, sees all players, RTT measured.
7. **Dedicated server.** `gd_net.server_preset()`, export, compare client and server packs (`pack_report`), run the exported binary without `--headless` and connect clients. Set `application/run/flush_stdout_on_print=true` for systemd or journald logs (docs delta 12; default false, measured). GATE: `dedicated_server` feature true, display `headless`, no client textures in the pack, exit 0.
8. **Look.** A windowed observer client captures the replicated world (`capture_at`); open it. GATE: players where the server says, colors per peer, nothing missing.

## Harness in one call

```python
import sys; sys.path[:0] = ["<skills>/scenario-godot-expert/scripts", "<skills>/scenario-godot-multiplayer/scripts"]
import gd_net
gd_net.install_netkit(P); gd_net.build_scenes(P)          # res://net/world.tscn, player.tscn, props
roles = [gd_net.role("server", role="server", port=24010, lobby_size=2),
         gd_net.role("c1", role="client", port=24011, index=0, delay_s=0.3, cheat_at=2.0),
         gd_net.role("c2", role="client", port=24011, index=1, delay_s=0.3)]
with gd_net.UdpLagProxy(24011, 24010, rtt_ms=100, jitter_ms=0, loss=0.0):
    s = gd_net.session(P, roles)                            # one APFS clone and one Godot per role
s["roles"]["c1"]["result"]["rtt_median_ms"]                 # every NetLab number is in AGENT_RESULT
```

Your own game uses the same pattern: a job script per role (`role(name, script=...)`), user args after `--`, `AGENT_RESULT` printed by each process. Keep ports unique per project; two roles never share a project folder.

## Prediction, rollback and backends (not run here)

netfox gives server authority with client prediction and rollback: input gathered on the network tick, logic in `_rollback_tick`, `NetworkTime.physics_factor` around `move_and_slide`, `TickInterpolator` for display (GqHTNmRspjU [00:06:58, 00:18:55, 00:21:24]; iP_xdJ0peFo [00:28:00]). Prove it on a small prototype first: it is opinionated (GqHTNmRspjU [00:34:53]). Deterministic input-only rollback fits fighting and RTS-like games with 2 to 8 players (David Snopek, zvqQPbT8rAE). Steam (GodotSteam, SteamMultiplayerPeer), Nakama, Colyseus and WebRTC P2P swap the peer and lobby calls; authority, spawner and synchronizer code stays the same (Gwizz, fUBdnocrc3Y; AndrooDev, wgIqB6JNcro [00:07:18]). None of these ran here: they need a third-party addon, an account or a signalling server. Verify against the installed release before quoting an API.

## Numbers

| Value                                         | Measured here (2026-10-02, M-series Mac, localhost)                                                        | Relative to                                           |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| RPC round trip, no proxy                      | 16 to 19 ms                                                                                                | 60 fps both ends; one frame each way dominates        |
| ENet RTT statistic                            | 15 to 23 ms                                                                                                | same                                                  |
| Own input to visible motion, server authority | 47 to 52 ms                                                                                                | about 3 frames                                        |
| Remote view behind server truth               | 20 to 30 ms, 0.07 m error at 3 m/s                                                                         | no proxy                                              |
| Same at 100 / 250 ms RTT                      | 70 to 80 / 150 to 155 ms; 0.22 / 0.44 m                                                                    | `UdpLagProxy`, adds about 6 ms per direction          |
| 50 props, ALWAYS, 60 fps                      | 72.6 KiB/s, moving or idle                                                                                 | 1 client                                              |
| ON_CHANGE moving / idle                       | 98 to 101 / 2.3 KiB/s                                                                                      | same                                                  |
| ALWAYS, `replication_interval` 0.05           | 21 to 22 KiB/s                                                                                             | same                                                  |
| ALWAYS, uncapped headless server (145 fps)    | 160 to 175 KiB/s                                                                                           | same                                                  |
| `auth_timeout` default; kick of a silent peer | 3.0 s; 1.50 s after setting 1.5                                                                            | server                                                |
| Web export, single-thread                     | 40 MB, wasm 39.5 MB (10.1 MB gzip)                                                                         | handoff to scenario-godot-performance-export          |
| Dedicated server pack / client pack           | 0.11 / 3.27 MB (3.1 MB texture stripped)                                                                   | same project                                          |
| `spawn_limit`                                 | 0 = unlimited (default); limit 2: third `spawn()` logs "Spawn limit reached!", returns null, clients get 2 | M14; raise it to max players (jgJuX04cq7k [00:18:34]) |

## Quality gates

- Measurable: `net_audit` flags empty; every role `ok` with no unexpected engine error; `players_seen_max` equals the player count everywhere; authority body 1, input = peer; teleport counts as expected; RTT and `replication_delay` at 100 and 250 ms; KiB/s per mode; `rpc_audit` reviewed, `rpc_pair_check` ok; exported server boot dict correct.
- Visual: observer capture shows every player; under 250 ms no streak after a teleport; the browser screenshot shows the replicated players.

## Common mistakes

| Mistake                                                                             | What it looks like                                      | Fix                                                                                            |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Players spawned only on the server without a spawner, or spawner `spawn_path` empty | client sees nobody                                      | `MultiplayerSpawner` with `spawn_path` and the scene in its list; server calls `add_child`     |
| Authority read from a synced property in `_enter_tree`                              | authority 1 everywhere on clients                       | authority from `name.to_int()`                                                                 |
| Runtime node without `add_child(node, true)`                                        | `@Node@2` names, "node not found" on RPC                | readable names                                                                                 |
| `await` before `get_remote_sender_id()`                                             | sender 0, validation passes or fails wrongly            | read the sender first                                                                          |
| RPC added on the server script only                                                 | checksum error, the wrong method runs                   | one script, or `rpc_pair_check`                                                                |
| Object or Resource as RPC argument                                                  | no error; receiver gets `EncodedObjectAsID`             | send ids, paths or plain data                                                                  |
| Client owns its body in a competitive game                                          | speed and teleport hacks stick                          | input-only authority plus server simulation                                                    |
| Headless server not capped                                                          | 2.4 times the bandwidth                                 | `--max-fps 60` or intervals                                                                    |
| `server_relay` turned off for a P2P-style feature                                   | "Attempt to call RPC with unknown peer ID"              | keep relay on, or route through the server                                                     |
| Freeing a networked branch in the wrong order                                       | "isn't currently active", "Node not found"              | offline peer, free contents, drop custom API, free branch                                      |
| Server export in normal mode                                                        | full-size pack, window opens                            | dedicated server export mode, Strip Visuals                                                    |
| Server start inside `assert()`                                                      | works from the editor; the release export never listens | `var err := peer.create_server(port)`, then check `err` (M15: assert body stripped in release) |
| Client info sent from `peer_connected`, or id 0 registered                          | duplicate nodes on late joiners, a phantom player       | `connected_to_server`; skip id 0                                                               |
| Client and server on different Godot versions                                       | connection or protocol failures                         | same 4.7.2 build (protocol changed in 4.3)                                                     |

## Handoffs

- Receives: the game scene and player controller from scenario-godot-gameplay and scenario-godot-3d-world or scenario-godot-2d; architecture rules from scenario-godot-architecture.
- Delivers: network design note, kit scenes or scripts, session evidence JSON, server preset; the web build size and headers go to scenario-godot-performance-export, CI jobs to scenario-godot-pipeline-automation, lobby screens to scenario-godot-ui.

## Godot 4.7 notes

- `get_rpc_config` became `get_node_rpc_config` (4.5); `@rpc` tables live on `Script.get_rpc_config()`.
- `auth_timeout` is the property; the docs page spells `auth_timout`.
- 4.7.2 fixed peers that stopped replicating after deleting a spawner-spawned node.
- Godot 3 names (`NetworkedMultiplayerENet`, `remote`, `rset`, `get_rpc_sender_id`) do not exist; `gd_net.rpc_audit` flags them.
- WebRTC on desktop needs the webrtc-native extension: `initialize()` returns OK and only logs an error without it (measured).
- Open: under heavy machine load, 4 of 20 ALWAYS runs sent about 10 packets/s instead of 68 (ENet throttle at 0). Log `NetUtil.enet_throttle()` in long sessions (P8).
- Two peers leaving in one server frame log "Unable to send packet on channel 0" (ENet) or `ready_state != STATE_OPEN` (WebSocket); harmless, whitelisted by exact text.

## References

- [`references/procedures.md`](references/procedures.md): P1 to P14 with code, test ids and results.
- [`references/expert-notes.md`](references/expert-notes.md): claims by expert with timestamps and verified corrections.
- [`references/critique.md`](references/critique.md), [`references/gui-paths.md`](references/gui-paths.md) (Replication panel, Run Instances, Network Profiler), [`references/sources.md`](references/sources.md).
- [`scripts/gd_net.py`](scripts/gd_net.py), [`scripts/agentkit/multiplayer/`](scripts/agentkit/multiplayer/): the harness and kit.