Scenario Godot Multiplayer

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 (make_sync, make_spawner) writes scenes with SceneReplicationConfig set in code; the Replication panel is for humans (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

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.