@thedivergentai/godot-multiplayer-networking

NEVER Do (Expert Networking Rules)

Core Architecture

• NEVER use Reliable for high-frequency data (Position/Movement) — Reliable packets block all following packets until acknowledged (Head-of-Line blocking). Use UnreliableOrdered.
• NEVER trust the client for shared state (Health/Money/Inventory) — Clients should only suggest actions. The Server MUST validate and broadcast the result.
• NEVER hardcode the Server IP — Always allow for discovery (net_lan_discovery.gd) or pass the IP via CLI/UI.

Performance & Bandwidth

• NEVER send the same data every frame — Use net_adaptive_sync_throttle.gd to only send updates when state changes significantly or at fixed Hz intervals (e.g., 20Hz).
• NEVER use JSON for high-speed synchronization — String serialization is massive over the wire. Use bit-packing (net_packet_bit_packer.gd) to keep packets under 100 bytes.
• NEVER broadcast to all peers if it's not needed — In large worlds, use Interest Management (net_visibility_grid_culling.gd). A player in the forest doesn't need the position of a player in the city.

Security

• NEVER allow unlimited RPC calls per second — An attacker can flood the server with 1,000 "Attack" RPCs to crash the game. Use net_packet_rate_limiter.gd.
• NEVER expose PeerIDs to the end-user — PeerIDs are internal. Always map them to persistent UserIDs (net_custom_id_mapper.gd) from a database.
• NEVER run a dedicated server with a GUI enabled — Use --headless (net_headless_server_auto_start.gd) to save resources and ensure stability.

Decision Tree (transport / authority / sync Hz)

Do NOT Load lobby/RPC beginner recipes from memory — use the golden path below and open only matching scripts.

Golden Path

1. Host / dedicated → server_dedicated_host.gd + net_headless_server_auto_start.gd; clients → client_network_setup.gd.
2. Secure RPC → secured_rpc_pattern.gd + net_packet_rate_limiter.gd + secure_variable_synchronizer.gd.
3. Prediction / reconcile → client_prediction_synchronizer.gd + net_anti_desync_reconciler.gd; fighting/rollback → net_rollback_helper.gd.
4. Interest culling → net_visibility_grid_culling.gd before broadcasting positions.

Available Scripts

Transport & host

• net_enet_expert_config.gd — channels, compression, bandwidth.
• net_headless_server_auto_start.gd — CLI/--headless detect.
• server_dedicated_host.gd — dedicated host bootstrap.
• client_network_setup.gd — client peer join.
• net_lan_discovery.gd — UDP LAN discovery.
• network_error_handler.gd — disconnect/error routing.
• packet_peer_latency_test.gd — latency probes.
• net_heartbeat_monitor.gd — RTT/jitter.

Authority, RPC, sync

• server_authoritative_controller.gd — server validates actions.
• secured_rpc_pattern.gd — safe RPC annotations/patterns.
• secure_variable_synchronizer.gd — server-owned vars.
• net_packet_rate_limiter.gd — flood protection.
• net_packet_bit_packer.gd — compact payloads (no JSON on hot path).
• net_adaptive_sync_throttle.gd — Hz / change-threshold sync.
• game_state_sync_manager.gd — snapshot/state sync.
• multiplayer_spawner_manager.gd — spawn authority.
• network_input_synchronizer.gd — input frames to server.
• networked_interpolator.gd — remote entity smoothing.
• net_custom_id_mapper.gd — UserID ↔ PeerID.

Desync / rollback / interest

• client_prediction_synchronizer.gd — predict + correct.
• net_anti_desync_reconciler.gd — forced correction.
• net_rollback_helper.gd — snapshot re-sim helper.
• net_visibility_grid_culling.gd — interest management.

Expert Pointers

• Position/movement: UnreliableOrdered + throttle — never reliable every frame.
• Clients suggest; server validates and broadcasts results.
• Large worlds: cull with visibility grid before adding more sync Hz.

Deep dives (on demand)

• RPC modes, lobby handshake, puppet interpolation → rpc-lobby-and-sync.md
• Delta-compression + network simulator concepts live in that reference (LLM-ignorance: unreliable vs reliable HoL blocking is NOT generic knowledge).

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• High-level multiplayer — RPC modes, authority, and peer lifecycle for host/join lobbies and server-validated actions.
• Networking — Transport map (ENet / WebSocket / WebRTC / HTTP) so peer choice matches platform and NAT constraints.
• MultiplayerAPI — multiplayer singleton: peer IDs, connection signals, and rpc / rpc_id entry points.
• MultiplayerPeer — Transfer modes (reliable / unreliable / unordered) and connection status shared by every backend.
• ENetMultiplayerPeer — UDP host/client peer used for LAN, dedicated servers, and most action games.
• SceneMultiplayer — Default MultiplayerAPI: root path, auth callbacks, and scene-tree RPC routing.
• MultiplayerSpawner — Spawn/despawn replication so late joiners share the same networked scene graph.
• MultiplayerSynchronizer — Property replication, on-change deltas, and visibility filters that replace ad-hoc position RPCs.
• Node — set_multiplayer_authority / is_multiplayer_authority ownership rules for input vs shared state.
• PacketPeerUDP — Raw UDP send/receive for LAN discovery broadcasts outside the high-level multiplayer peer.
• WebRTC — Browser-friendly P2P path when ENet UDP cannot punch through firewalls alone.
• Command line tutorial — --headless and CLI flags for dedicated-server launches and multi-instance tests.

Related Skills

Prerequisites

• godot-project-foundations — Project layout, Autoloads, and export/feature flags that host/join and dedicated-server builds depend on.
• godot-gdscript-mastery — Typed @rpc annotations, Callables, and PackedByteArray patterns used by secure RPCs and bit-packers.
• godot-input-handling — Split InputMap reads from simulation so clients send intents and the authority owns outcomes.

Complements

• godot-adapt-single-to-multiplayer — Migration shape (authority split, prediction shells) before applying this skill’s lobby/RPC/ENet toolkit.
• godot-autoload-architecture — Session/lobby Autoloads that outlive scene changes during host/join and reconnect flows.
• godot-signal-architecture — Local peer-connected / lobby events that stay decoupled from transport RPCs.
• godot-server-architecture — Headless host scaffolding and PhysicsServer/RID patterns used by authoritative simulation.
• godot-export-builds — Dedicated-server export presets and CLI packaging for real multi-instance tests.
• godot-debugging-profiling — RTT/jitter overlays and remote debug habits that catch sync bugs localhost never shows.
• godot-save-load-systems — Persist UserIDs, lobby prefs, and reconnect tokens without treating PeerIDs as durable identity.

Downstream / consumers

• godot-performance-optimization — Cap replication Hz and interest culling when bandwidth/CPU budgets break under peer load.
• godot-monte-carlo-balancer — Retune economy/TTK after netcode changes alter effective weapon timings or ability windows.
• godot-genre-battle-royale — Large-peer interest management and late-join snapshots at BR scale.
• godot-genre-moba — Fixed-tick authority, ability RPCs, and spectator-safe state sync for multiplayer arenas.

Master

• godot-master — Library router and mirrored module entry; open when discovering which Domain Skill owns a cross-cutting networking concern.