godot-adapt-single-to-multiplayer

name

godot-adapt-single-to-multiplayer

description

Expert patterns for adding multiplayer to single-player games including client-server architecture, authoritative server design, MultiplayerSynchronizer, lag compensation (client prediction, server reconciliation), input buffering, and anti-cheat measures. Use when retrofitting multiplayer, porting to online play, or designing networked gameplay. Trigger keywords: MultiplayerPeer, ENetMultiplayerPeer, SceneMultiplayer, MultiplayerSynchronizer, rpc, rpc_id, multiplayer_authority, client_prediction, server_reconciliation, lag_compensation, rollback.

NEVER Do (Expert Multiplayer Rules)

Security & Authority

• NEVER trust client-reported state — Clients own their 'Input', NOT their 'Position' or 'Health'. Server must validate every coordinate and health change.
• NEVER use get_tree() groups for authority checks — Use is_multiplayer_authority(). Group registration is non-deterministic in high-latency joins.
• NEVER allow unrestricted RPC rates — A malicious client can call a 'FireWeapon' RPC 10,000 times per second. Always implement rate-limiting (net_rpc_rate_limiter.gd).

Movement & Lag

• NEVER skip Client-Side Prediction — Movement without prediction feels 'heavy' and unresponsive. Predict movement locally, then correct only on server disagreement.
• NEVER sync peers at 60Hz — Sending entire state every frame will saturate client bandwidth. Use a lower tick-rate (20-30Hz) and interpolate between packets.
• NEVER snap peer positions — Abrupt position updates cause 'jitter'. Store a buffer of past states and lerp between them with a 100ms delay.

Bandwidth & Sync

• NEVER sync 'Full Floats' if possible — Quantize Vector3 data (truncating decimals) to save 50%+ bandwidth. Use MultiplayerSynchronizer with delta-sync enabled.
• NEVER ignore 'Late Joiners' — Players who join mid-game won't see existing environmental changes. Broadcast a full world-state 'Snapshot' on peer connection.
• NEVER test on 0ms ping — Everything works on localhost. Use a simulator (net_latency_simulator.gd) with 150ms ping to identify sync bugs.

---

Available Scripts

MANDATORY: Architecture decision tree first, then golden-path scripts. Deep latency workflows → references/latency-testing.md.

Authority / transport bridges

multiplayer_sync.gd

MANDATORY when adding MultiplayerSynchronizer interpolation for remote peers. Trigger: authority owns transforms; non-authority interpolates.

rpc_bridge.gd

MANDATORY signal→RPC bridge. Trigger: gameplay emits local signals; bridge validates authority and fans out RPCs.

Prediction / lag / lobby

net_prediction_reconciliation.gd

CharacterBody prediction + input-buffer replay for server reconciliation.

net_snapshot_interpolation.gd

Snapshot interpolation / jitter buffers for remote peers.

net_auth_server_validator.gd

Authoritative validation (position, speed, actions).

net_rpc_rate_limiter.gd

RPC flood / macro protection.

net_interest_management.gd

Distance-based visibility to cut bandwidth.

net_delta_compression_sync.gd

Quantization + significance checks for delta sync.

net_lag_compensation.gd

Server-side rewind for hit registration.

net_lobby_late_join_sync.gd

Late-joiner world snapshot bootstrap.

Diagnostics

net_latency_simulator.gd

MANDATORY before ship — see references/latency-testing.md.

net_debug_overlay_monitor.gd

RTT / loss / jitter overlay.

net_upnp_discovery_logic.gd

UPNP port mapping for listen-server / P2P hosts.

---

Architecture Patterns

Pattern	When	Script golden path
Authoritative server	PvP, economies, cheat risk	rpc_bridge.gd → net_auth_server_validator.gd → prediction/recon
P2P lockstep	2–4 co-op, low cheat risk	Deterministic inputs + net_upnp_discovery_logic.gd
Hybrid / host authority	Party games 4–8	Host authority + late-join snapshot

---

Migration golden path (no inline host/join tutorials)

1. Separate input (client) from simulation (authority).
2. Set multiplayer_authority per player node; clients send intents only.
3. MANDATORY multiplayer_sync.gd for property replication / remote interpolation.
4. MANDATORY rpc_bridge.gd for gameplay events that cross the wire.
5. Add prediction / lag compensation scripts only for the genres that need them.
6. Validate with latency-testing reference + net_latency_simulator.gd at ~150 ms RTT.

Expert insights (WHY — keep in body)

• Client prediction — WHY: without local sim, RTT doubles perceived input lag. Replay buffered inputs after server correction (net_prediction_reconciliation.gd).
• Interpolation buffer — WHY: raw sync packets jitter; lerp between snapshots with ~100 ms delay (net_snapshot_interpolation.gd).
• Hit rewind — WHY: clients fire at past world state; server rewinds RIDs via PhysicsServer3D before raycast (net_lag_compensation.gd).
• Input send rate — WHY: 60 Hz input RPCs saturate uplink; batch at 20–30 Hz with significance checks (net_delta_compression_sync.gd).

Decision Tree: Which Architecture?

Factor	Authoritative Server	P2P Lockstep
Player count	8-100+	2-4
Cheat prevention	Critical	Not important
Server hosting	Available	Not available
Gameplay type	PvP, competitive	Co-op, casual
Lag tolerance	Medium (prediction helps)	Low (desyncs)
Development complexity	High	Medium

Advanced Networking Topics

Peer-to-Peer NAT Traversal (Hole Punching)

In P2P architectures, clients often sit behind firewalls. UPNP (Universal Plug and Play) is the first line of defense, allowing the game to request port forwarding from the router automatically using net_upnp_discovery_logic.gd.

For cases where UPNP fails:

• STUN/TURN: Use a STUN server to discover public IP/port pairings.
• Relay Servers: If direct connection is impossible, fallback to a relay server (TURN) to bridge the two peers.

Network Profiling & Visualization

Visualizing the packet timeline is critical for debugging jitter. Propose an overlay that graphs:

• Packet Arrival: A scrolling timeline showing when packets arrive relative to physics frames.
• Buffer Health: A visualization of the interpolation jitter buffer size.
• RTT (Round Trip Time): Real-time graph of latency spikes.

Deep recipes (on demand)

Topic	Reference / script
Prediction / recon / interpolation	prediction-and-reconciliation.md
Authority / anti-cheat / bandwidth	authority-and-security.md

Reference

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

Official Documentation

• High-level multiplayer — RPC modes, authority, and peer lifecycle you must retrofit before any gameplay state leaves the single-player path.
• Networking — Transport map (ENet / WebSocket / WebRTC) so host/join choices match platform and NAT constraints.
• MultiplayerSynchronizer — Property replication, delta sync, and visibility filters that replace ad-hoc position RPCs.
• MultiplayerSpawner — Spawn/despawn replication when late joiners need the same scene graph as the host.
• SceneMultiplayer — Default MultiplayerAPI implementation: root path, auth callbacks, and RPC routing under SceneTree.
• ENetMultiplayerPeer — UDP host/client peer used by most LAN and dedicated-server ports of single-player games.
• MultiplayerAPI — multiplayer singleton surface: peer IDs, signals, and rpc / rpc_id entry points.
• MultiplayerPeer — Transfer modes and connection status shared by every concrete peer backend.
• UPNP — Automatic port mapping for listen-server / P2P hosts behind consumer routers.
• WebRTC — Browser-friendly P2P path when ENet UDP cannot punch through firewalls alone.
• Node — set_multiplayer_authority / is_multiplayer_authority ownership rules for input vs state.
• PhysicsServer3D — Direct RID transforms for server-side hit rewind without SceneTree side effects.

Related Skills

Prerequisites

• godot-input-handling — Split InputMap reads from simulation so clients send intents and the authority owns outcomes.
• godot-signal-architecture — Local signal graphs that rpc_bridge.gd can wrap without coupling gameplay to transport.
• godot-autoload-architecture — Session/lobby Autoloads that outlive scene changes during host/join flow.

Complements

• godot-multiplayer-networking — Broader RPC, lobby, and ENet tuning once the single-player→online migration shape is fixed.
• godot-characterbody-2d — Deterministic move_and_slide steps reused by client prediction and reconciliation buffers.
• godot-physics-3d — Body/shape setup that lag-compensation rewind and hit validation query against.
• godot-raycasting-queries — Server-side ray/shape queries for authoritative shots after state rewind.
• godot-debugging-profiling — RTT/jitter overlays and remote debug habits that catch sync bugs localhost never shows.
• godot-export-builds — Headless/dedicated-server export presets and CLI flags for real multi-instance tests.
• godot-server-architecture — PhysicsServer/RID patterns and headless host scaffolding used by rewind and dedicated peers.

Downstream / consumers

• godot-genre-shooter-fps — Hitscan/projectile feel that depends on prediction + lag compensation from this skill.
• godot-genre-battle-royale — Large-peer interest management and late-join snapshots at BR scale.
• godot-monte-carlo-balancer — Retune economy/TTK after netcode changes alter effective weapon timings.
• godot-performance-optimization — Cap replication rate and cull interest when bandwidth/CPU budgets break under peer load.

Master

• godot-master — Library router and mirrored module entry for this Domain Skill.