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)

| Question | Prefer | Script |

|----------|--------|--------|

| Desktop/console LAN or dedicated UDP | ENet | MANDATORY [net_enet_expert_config.gd](scripts/net_enet_expert_config.gd) |

| Browser / NAT-hostile peers | WebRTC (or WebSocket fallback) | Official Docs + peer wrappers; still use secure RPC scripts |

| Who owns gameplay truth? | Server-authoritative | MANDATORY [server_authoritative_controller.gd](scripts/server_authoritative_controller.gd) |

| Dedicated host without GUI | --headless | MANDATORY [net_headless_server_auto_start.gd](scripts/net_headless_server_auto_start.gd) / [server_dedicated_host.gd](scripts/server_dedicated_host.gd) |

| Position @ 10–20 Hz, not every frame | Adaptive throttle | MANDATORY [net_adaptive_sync_throttle.gd](scripts/net_adaptive_sync_throttle.gd) |

> 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](scripts/server_dedicated_host.gd) + [net_headless_server_auto_start.gd](scripts/net_headless_server_auto_start.gd); clients → [client_network_setup.gd](scripts/client_network_setup.gd).
2. Secure RPC → [secured_rpc_pattern.gd](scripts/secured_rpc_pattern.gd) + [net_packet_rate_limiter.gd](scripts/net_packet_rate_limiter.gd) + [secure_variable_synchronizer.gd](scripts/secure_variable_synchronizer.gd).
3. Prediction / reconcile → [client_prediction_synchronizer.gd](scripts/client_prediction_synchronizer.gd) + [net_anti_desync_reconciler.gd](scripts/net_anti_desync_reconciler.gd); fighting/rollback → [net_rollback_helper.gd](scripts/net_rollback_helper.gd).
4. Interest culling → [net_visibility_grid_culling.gd](scripts/net_visibility_grid_culling.gd) before broadcasting positions.

Available Scripts

Transport & host

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

Authority, RPC, sync

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

Desync / rollback / interest

• [client_prediction_synchronizer.gd](scripts/client_prediction_synchronizer.gd) — predict + correct.
• [net_anti_desync_reconciler.gd](scripts/net_anti_desync_reconciler.gd) — forced correction.
• [net_rollback_helper.gd](scripts/net_rollback_helper.gd) — snapshot re-sim helper.
• [net_visibility_grid_culling.gd](scripts/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](references/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.