godot-adapt-single-to-multiplayer

Files (14)

• SKILL.md
• multiplayer_sync.gd · scripts/
• net_auth_server_validator.gd · scripts/
• net_debug_overlay_monitor.gd · scripts/
• net_delta_compression_sync.gd · scripts/
• net_interest_management.gd · scripts/
• net_lag_compensation.gd · scripts/
• net_latency_simulator.gd · scripts/
• net_lobby_late_join_sync.gd · scripts/
• net_prediction_reconciliation.gd · scripts/
• net_rpc_rate_limiter.gd · scripts/
• net_snapshot_interpolation.gd · scripts/
• net_upnp_discovery_logic.gd · scripts/
• rpc_bridge.gd · scripts/

SKILL.md (first lines)

## Godot 4.7 Baseline

- Expert patterns in this skill target **Godot 4.7+** (stable, 2026-06-18).
- Consult the [Godot 4.7 migration guide](https://docs.godotengine.org/en/4.7/tutorials/migrating/upgrading_to_godot_4.7.html) when upgrading projects from 4.6.
- **NEVER** assume 4.6 defaults (stretch mode, audio area_mask, RichTextLabel percent flags) without checking 4.7 migration notes.

# Adapt: Single to Multiplayer

Expert guidance for retrofitting multiplayer into single-player games.

## 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**: Read the appropriate script before implementing the corresponding pattern.

### [net_prediction_reconciliation.gd](scripts/net_prediction_reconciliation.gd)
Expert CharacterBody3D prediction with input-buffer replaying for server reconciliation.

### [net_snapshot_interpolation.gd](scripts/net_snapshot_interpolation.gd)
Professional snapshot interpolation logic for smoothing peer movement via jitter buffers.

### [net_auth_server_validator.gd](scripts/net_auth_server_validator.gd)
Authoritative server validator for anti-cheat (Position, Speed, and Action checks).

### [net_rpc_rate_limiter.gd](scripts/net_rpc_rate_limiter.gd)
Expert rate-limiter to prevent RPC flooding and macro-abuse by clients.

### [net_interest_management.gd](scripts/net_interest_management.gd)
Distance-based visibility management to optimize binary bandwidth per-peer.

### [net_delta_compression_sync.gd](scripts/net_delta_compression_sync.gd)
Expert quantization and significance-checking logic for delta-compression.

### [net_upnp_discovery_logic.gd](scripts/net_upnp_discovery_logic.gd)
Robust script for P2P network discovery and automatic port forwarding via UPNP.

### [net_debug_overlay_monitor.gd](scripts/net_debug_overlay_monitor.gd)
In-game diagnostic overlay reporting RTT (Ping), Packet Loss, and Jitter.

### [net_lag_compensation.gd](scripts/net_lag_compensation.gd)
Expert server-side state rewinding (Lag Compensation) for accurate hit-registration.

### [net_lobby_late_join_sync.gd](scripts/net_lobby_late_join_sync.gd)
Professional state-initialization logic to bridge 'Late Joiners' into a synced session.

### [net_latency_simulator.gd](scripts/net_latency_simulator.gd)
Editor-only tool for simulating high-ping and loss conditions for stress-testing.

---

## Architecture Patterns

### Pattern 1: Authoritative Server (Recommended)

```gdscript
# Server validates ALL gameplay logic
# Clients send inputs → Server processes → Server broadcasts state

# Pros: Secure, prevents cheating
# Cons: Requires server hosting, lag affects gameplay

# Use for: Competitive games, PvP, games with economies
```

### Pattern 2: Peer-to-Peer (Lockstep)

```gdscript
# All clients run identical simulation
# Inputs synced, deterministic physics

# Pros: No dedicated server needed
# Cons: Vulnerable to cheating, desyncs common

# Use for: Co-op, casual games, small player counts (2-4)
```

### Pattern 3: Hybrid (Authority Transfer)

```gdscript
# Host acts as server
# Authority can transfer between peers

# Use for: 4-8 player co-op, party games
```

---

## Step-by-Step Migration

### Step 1: Separate Input from Logic

```gdscript
# ❌ BAD: Input directly modifies state (single-player)
extends CharacterBody2D

func _physics_process(delta: float) -> void:
    var input := Input.get_vector("left", "right", "up", "down")
    velocity = input.normalized() * SPEED
    move_and_slide()

# ✅ GOOD: Input → Logic separation

From bgrenat/godot-game-dev-studio, LGPL-3.0.

More from bgrenat/godot-game-dev-studio