modbison/docs/architecture/networking.md

# Multiplayer Networking Architecture

> **Status:** Proposed
> **Owner:** Platform team
> **Related:** Server authority + client prediction

## 1. Overview

This document specifies the multiplayer networking architecture for **agp-game**,
a Godot-based game built by autonomous agents. The architecture follows a
**server-authoritative model with client-side prediction and reconciliation**,
which is the industry standard for fast-paced, competitive multiplayer games.

The goals of this architecture are:

- **Fairness & anti-cheat:** The server is the single source of truth for all
  gameplay state. Clients never directly mutate world state.
- **Responsiveness:** Client-side prediction hides network latency so local input
  feels immediate.
- **Determinism:** The server runs a fixed-timestep simulation so that state is
  reproducible and testable.
- **Scalability:** A clear separation between transport, simulation, and
  replication layers allows the server to be tuned independently.

---

## 2. Transport Choice: ENet over WebSocket

### 2.1 Decision

We choose **ENet** as the primary transport for gameplay traffic.

### 2.2 Justification

| Criterion            | ENet                                   | WebSocket (TCP)                     |
|----------------------|----------------------------------------|-------------------------------------|
| **Reliability model**| Reliable + unreliable channels         | Reliable only (TCP)                 |
| **Latency**          | Low; unreliable packets skip retransmit| Head-of-line blocking on loss       |
| **Packet ordering**  | Per-channel ordering                   | Global strict ordering              |
| **Congestion control**| Lightweight, game-oriented            | TCP-style (slow start, backoff)     |
| **Godot support**    | First-class (`ENetConnection`, `MultiplayerPeerENet`) | Supported but TCP-based |
| **Use case fit**     | Real-time action game                  | Chat, lobby, HTTP-style messaging   |

**Rationale:**

- **Movement & state replication** are latency-sensitive and tolerate occasional
  packet loss. ENet's *unreliable* channel lets us send position snapshots at high
  frequency without head-of-line blocking.
- **RPCs that must be delivered** (e.g., interactions, spawns) use ENet's
  *reliable* channel, giving us exactly the semantics we need without TCP's
  retransmission stalls.
- Godot's `MultiplayerPeerENet` is mature and integrates directly with the
  high-level multiplayer API (`MultiplayerAPI`, `rpc()`).

### 2.3 WebSocket as a Secondary Transport

WebSocket remains available as a **secondary transport** for:

- **Lobby / matchmaking** messaging (low-frequency, must-be-reliable).
- **Browser builds** where raw UDP/ENet is unavailable.
- **Admin / telemetry** channels.

The transport layer is abstracted behind an interface so gameplay code does not
depend on the underlying protocol.

---

## 3. Server-Side Game Loop

### 3.1 Tick Rate

- **Simulation tick rate:** **30 Hz** (33.33 ms per tick).
- **Replication / snapshot rate:** **30 Hz**, aligned with the simulation tick.

**Justification:**

- 30 Hz is sufficient for smooth movement and interaction in a top-down / 2D
  action game while keeping CPU and bandwidth costs predictable.
- A fixed timestep (rather than delta-time) makes the simulation deterministic
  and testable.
- The tick rate is a **configuration constant** so it can be raised (e.g., to
  60 Hz) for competitive modes without architectural changes.

### 3.2 Authority Model

- **Server is authoritative** for:
  - Player position, velocity, and physics state.
  - Health, damage, and death.
  - Item pickups, inventory, and world-object state.
  - Spawning and despawning of entities.
  - Game rules, scoring, and win/lose conditions.
- **Client is authoritative** for:
  - Its own *input* (which keys/buttons are pressed).
  - Local camera and UI.
  - Cosmetic / non-gameplay presentation.

### 3.3 Server Loop Pseudocode

```
while server_running:
    process_network_inbound()      # read client inputs & RPCs
    for _ in range(ticks_to_advance):
        simulate_tick()            # fixed 30 Hz step
    broadcast_snapshots()          # replicate authoritative state
    process_network_outbound()     # flush reliable/unreliable channels
```

The server accumulates real elapsed time and advances the simulation in fixed
`TICK_DURATION` increments, decoupling simulation from frame rate.

---

## 4. RPC Call Patterns

RPCs are grouped by direction and reliability. All gameplay RPCs are routed
through the high-level `MultiplayerAPI` with explicit `rpc_id` targeting.

### 4.1 Client → Server (Input & Requests)

| RPC                          | Channel   | Payload                                   | Notes |
|------------------------------|-----------|-------------------------------------------|-------|
| `request_move_input`         | unreliable| `{ seq, input_state, timestamp }`         | Batched per tick; drives prediction |
| `request_interact`           | reliable  | `{ target_id }`                           | Open door, pick up item, use object |
| `request_attack`             | reliable  | `{ target_id, aim_dir }`                  | Combat action |
| `request_join`               | reliable  | `{ player_name, profile }`                | Session setup |
| `request_respawn`            | reliable  | `{}`                                      | After death |

**Design notes:**

- **Input is batched** per client tick and sent with a monotonically increasing
  `seq` so the server can detect gaps and the client can reconcile.
- **Interactions are reliable** because they are discrete, must-happen events
  (opening a door, picking up an item). Losing them would corrupt world state.

### 4.2 Server → Client (State & Events)

| RPC                          | Channel   | Payload                                   | Notes |
|------------------------------|-----------|-------------------------------------------|-------|
| `snapshot_state`             | unreliable| `{ tick, entities[], player_states[] }`   | Periodic authoritative state |
| `spawn_entity`               | reliable  | `{ entity_id, type, transform, props }`   | New entity enters world |
| `despawn_entity`             | reliable  | `{ entity_id, reason }`                   | Entity removed |
| `interact_result`            | reliable  | `{ request_seq, success, result }`        | Acknowledges interaction |
| `damage_event`               | reliable  | `{ target_id, amount, source_id }`        | Combat feedback |
| `game_event`                 | reliable  | `{ type, payload }`                       | Score, win, round start/end |

### 4.3 Broadcast vs. Targeted

- **Broadcast (all clients):** `snapshot_state`, `spawn_entity`,
  `despawn_entity`, `game_event`.
- **Targeted (single client):** `interact_result`, `damage_event` (to affected
  players), and any player-private data.

---

## 5. Client-Side Prediction & Reconciliation

### 5.1 Prediction

- The client runs a **local copy of the movement simulation** using the same
  physics constants as the server.
- When the player provides input, the client:
  1. Applies the input to its local player immediately.
  2. Renders the predicted position.
  3. Sends the input to the server (batched, with `seq`).

### 5.2 Reconciliation

- The server sends authoritative `snapshot_state` at 30 Hz containing the
  server's tick number and authoritative player positions.
- The client keeps a **ring buffer of predicted states** keyed by input `seq`.
- On receiving a snapshot:
  1. Find the last predicted state that matches the server's tick.
  2. Compute the **error** between predicted and authoritative position.
  3. If error exceeds a threshold, **snap or smoothly interpolate** the local
     player to the authoritative position (error correction).
  4. Re-simulate any inputs that occurred after the server's tick (rollback).

### 5.3 Interpolation of Remote Entities

- **Local player:** predicted + reconciled (see above).
- **Remote players / entities:** rendered with **interpolation delay** of
  `2 × TICK_DURATION` (≈ 66 ms) to smooth out snapshot jitter.
- The client buffers the last N snapshots and interpolates between them.

### 5.4 Prediction Buffer Sizing

- Buffer size is adaptive based on measured RTT.
- Default: hold up to `ceil(RTT / TICK_DURATION) + 2` predicted states.

---

## 6. Entity & World State Replication

### 6.1 Entity Model

Every networked entity has:

- A globally unique `entity_id` (server-assigned).
- An `EntityType` (player, enemy, item, projectile, door, ...).
- A `Transform` (position, rotation).
- A typed `props` dictionary of gameplay state (health, state machine, etc.).

### 6.2 Snapshot Format

```
snapshot_state:
  tick: uint32
  entities:
    - entity_id: uint32
      type: uint8
      transform: { x, y, rot }
      props: { ... }        # delta-encoded where possible
  player_states:
    - peer_id: int
      entity_id: uint32
      health: int
      state: uint8
```

### 6.3 Delta Compression

- Only **changed** entity fields are sent per snapshot (dirty-flag per entity).
- Static or unchanged entities are omitted from the snapshot.
- This keeps bandwidth proportional to *activity*, not world size.

---

## 7. Connection & Session Lifecycle

1. **Connect:** Client opens an ENet connection to the server.
2. **Authenticate / Join:** Client sends `request_join`; server validates and
   assigns a `peer_id` and spawns the player entity.
3. **Spawn:** Server broadcasts `spawn_entity` for the new player to all clients.
4. **Play:** Input → prediction → server simulation → snapshot → reconciliation.
5. **Disconnect:** Server removes the player entity, broadcasts `despawn_entity`,
   and cleans up session state.

---

## 7a. Server Orchestration (implemented, PC3 Phase 2)

**One dedicated server process per world**, spawned on demand.

```
client                    backend (single worker)              host
  │  POST /api/worlds/{id}/join  (bearer JWT)                    │
  │ ───────────────────────────▶ GameServerSupervisor           │
  │                              ensure_server(world_id):        │
  │                                if none running for world ─── spawn:
  │                                                              godot --headless
  │                                                              res://scenes/server.tscn --
  │                                                              --port <p> --world <id>
  │                                                              --status-file <path>
  │  ◀─────────────────────────── { host, port, world_id }       │
  │                                                              │
  │  ENet connect  host:port ───────────────────────────────────▶ dedicated server
```

- **Supervisor** (`backend/app/services/game_servers.py`): in-process singleton,
  so the backend MUST run single-worker. Keys servers by `world_id`. Allocates
  ports from `GAME_SERVER_PORT_MIN..MAX`. A background reaper kills a world's
  server once its **status file** (`{players, tick, updated}`, rewritten by the
  server ~1×/s) reports `players == 0` for `GAME_SERVER_IDLE_TIMEOUT_SECONDS`.
  No crash-restart — the next join respawns.
- **Enable flag:** `GAME_SERVERS_ENABLED` (default off). The checkpoint/playtest
  launcher (`pm/checkpoint_ops.py`) turns it on, passes `GODOT_BIN`,
  `GAME_PROJECT_DIR`, and `GAME_SERVER_HOST` (the LAN IP baked into the `.exe`).
  A backend with it off returns **503** from `/join`, and the client falls back
  to local single-player.
- **Per-world content:** all worlds currently load the same test level (M2/M7
  work). `world_id` still scopes a distinct process + session.

### 7b. Client play path

`world_list.gd` → `POST /join` → `Session.begin(world_id, host, port)` →
load `game.tscn`. `game.gd` sees `Session.active` and connects a
`NetworkClient`:

- **Local player** keeps predicting with its own collision-aware
  `CharacterBody3D` (`player.gd`) — that *is* the prediction. Its input frame
  (`player.net_input`) is forwarded to the server every physics tick.
- **Correction backstop:** if the local position drifts from the server's by
  more than `CORRECTION_THRESHOLD` (1.5 m — generous; catches teleport / a wall
  walked through / real desync, not prediction noise) it snaps.
- **Remote players:** rendered from snapshots, position lerped. *Appearance sync
  is a follow-up* — remotes currently show as labelled capsules; the server
  does not yet replicate avatar loadouts.
- **Disconnect** → status message → back to the world list.

The `NetworkClient`'s own flat-plane prediction + input-replay reconciliation
(§5) is exercised by `smoke_test_network_client.gd`; the collision-aware game
path above uses the lighter `send_input()` + drift-snap instead.

---

## 8. Security & Anti-Cheat

- **No client-authoritative gameplay values.** Clients only send *inputs* and
  *requests*; the server computes all outcomes.
- **Input validation:** Server clamps movement speed, rejects out-of-bounds
  positions, and validates interaction targets.
- **Rate limiting:** Per-peer input and RPC rate limits prevent flooding.
- **Sequence validation:** Gaps or replays in input `seq` are detected and
  rejected.

---

## 9. Testing & Determinism

- The simulation is a **pure function of (state, inputs, tick)** so it can be
  unit-tested headlessly.
- A **replay system** records inputs and can re-simulate to verify server and
  client produce identical results.
- Network code is tested with a **mock transport** that can inject latency,
  jitter, and packet loss.

---

## 10. Open Questions / Future Work

- **Interest management / spatial partitioning:** For large worlds, restrict
  snapshots to entities near each client (AOI culling).
- **Server-side physics:** Decide whether to use Godot's physics server on the
  host or a custom deterministic physics step.
- **Dedicated server vs. listen server:** The architecture supports both; a
  dedicated headless server is the target for production.
- **WebSocket fallback:** Implement the transport abstraction for browser builds.

---

## 11. Summary

| Concern                | Decision                                        |
|------------------------|-------------------------------------------------|
| Transport              | ENet (primary), WebSocket (secondary)           |
| Tick rate              | 30 Hz fixed timestep                            |
| Authority              | Server-authoritative; client sends input only   |
| Prediction             | Client-side prediction + reconciliation         |
| Remote interpolation   | 2-tick interpolation delay                      |
| Replication            | Delta-compressed snapshots at 30 Hz             |
| Interaction RPCs       | Reliable channel                                |
| Movement input         | Unreliable channel, batched with sequence       |