client/overview/networking_implementation_plan.md

# Networking Implementation Plan

> **Status: complete.** This was the ordered checklist that took Spacewar from
> zero networking code to the real ENet authoritative-server implementation —
> all 10 phases below were executed (see `CLAUDE.md` item 6 and the many items
> after it that build on top of this foundation). Kept as a historical record
> of the approach and ordering; the checkboxes are left unchecked as
> originally written rather than retroactively edited. For current
> architecture, see `tech.md`; for the present file layout, see `structure.md`.

Step-by-step breakdown for taking Spacewar from single-player-only to working
multiplayer. `tech.md` describes the target architecture; this doc is the
ordered checklist for getting there from the current codebase.

**Original starting state:** zero networking code existed anywhere in
the project. The server browser's JOIN button and the main menu's CASUAL
button just set local `GameConfig` fields and load `world.tscn` — no
connection was ever made. Everything downstream assumed exactly one player.

**Guiding principle:** get two peers moving/shooting/dying correctly over
ENet *first*, with ugly/no prediction. Polish feel (prediction,
reconciliation, lag comp) only after the authoritative loop is proven
correct. Don't build matchmaking/Steam/galaxy-war until basic peer-to-peer
combat works.

---

## Phase 0 — Decisions to make before writing code

- [ ] Pick topology for early dev: dedicated headless server instance vs.
      one client acting as host. (Recommend: always run a dedicated server,
      even locally — avoids a host-migration refactor later, and matches
      the authoritative-server model in `tech.md`.)
- [ ] Decide the connection target for now: hardcoded `127.0.0.1` / LAN IP
      is fine until Phase 8. Don't build matchmaking yet.
- [ ] Confirm max casual match size (25v25 per `overview.md`) — this affects
      how much you can get away with naive replication before needing
      interest management / area-of-interest culling.

---

## Phase 1 — ENet bootstrap & connect flow

**Goal:** two Godot instances can connect over ENet and see each other join/leave.

- [ ] Add a `NetworkManager` autoload (new, alongside `GameConfig` in
      `autoload/`) that owns the `ENetMultiplayerPeer`, exposes
      `host_server(port)` / `join_server(ip, port)`, and connects to
      `multiplayer.peer_connected` / `peer_disconnected` / `connected_to_server`
      / `connection_failed`.
- [ ] Wire `menu/server_browser.gd`'s `_on_join_pressed` (currently just sets
      `GameConfig` fields and changes scene) to actually call
      `NetworkManager.join_server(...)` and only transition to `world.tscn`
      on `connected_to_server`.
- [ ] Add a minimal headless server launch path (`--server` CLI flag or a
      separate export target) that calls `host_server()` and loads
      `world.tscn` without a local player.
- [ ] Smoke test: launch one headless server + two client instances, confirm
      `peer_connected` fires on the server for both and each client sees the
      other's peer_id.

---

## Phase 2 — Per-peer player state

**Goal:** replace the single-player assumption in `GameConfig` with a real
per-peer registry.

- [ ] Split `autoload/game_config.gd`: keep shared/match-wide constants
      (thrust, speed, fire rate, `world_bounds`, etc.) as-is, but move the
      per-player fields (`player_name`, `player_race`, `player_ship_path`,
      `player_ship_scale`, `player_ship_speed_factor`) out of flat globals
      into a `Dictionary[int, PlayerInfo]` keyed by `peer_id`, on
      `NetworkManager` or a new `PlayerRegistry` autoload.
- [ ] On connect, client sends its chosen name/race/ship to the server via
      RPC (`@rpc("any_peer", "call_local", "reliable") submit_loadout(...)`);
      server stores it in the registry and relays to all peers so everyone
      knows everyone's loadout.
- [ ] Update `menu/team_select.gd` (currently sets `GameConfig` fields
      directly and emits local `team_selected`) to submit the choice via
      this RPC path instead.
- [ ] Update anywhere still reading `GameConfig.player_name` /
      `player_race` / `player_ship_path` directly to read from the local
      peer's entry in the registry instead.

---

## Phase 3 — Spawning multiple ships

**Goal:** N ships exist in `world.tscn`, one per connected peer, each owned
by the right client.

- [ ] `world.tscn` currently has a single hardcoded ship node named "Player"
      as a direct child. Remove it; replace with an empty `Node2D`
      container (e.g. `Ships`) that ships get added to at runtime.
- [ ] Add a `MultiplayerSpawner` in `world.tscn` pointed at the `Ships`
      container, with `ship.tscn` in its spawnable scene list.
- [ ] Server-side: on `peer_connected` (or once loadout is submitted),
      instantiate `ship.tscn` for that peer under `Ships`, set
      `set_multiplayer_authority(peer_id)` on the ship root, name the node
      by peer_id (e.g. `str(peer_id)`) so it replicates deterministically.
- [ ] On `peer_disconnected`, despawn that peer's ship and remove it from
      the registry.
- [ ] **Camera2D fix:** `ship.tscn` currently bakes a `Camera2D` into the
      scene itself, which breaks with multiple instances. Move the camera
      out of `ship.tscn`; in `ship_movement.gd`'s `_ready()`, only create/
      activate a `Camera2D` if `is_multiplayer_authority()` is true (i.e.
      this is the local player's own ship).
- [ ] **HUD fix:** `ship_movement.gd` currently pushes health to
      `/root/World/HUD/HealthLabel` via a hardcoded absolute path. Gate this
      the same way — only the locally-authoritative ship should update the
      local HUD.

---

## Phase 4 — Split input from simulation

**Goal:** stop reading `Input.is_action_pressed()` inside the shared
simulation code; every ship's movement should be driven by whoever is
authoritative for it (server), fed by input coming from the owning client.

- [ ] In `ship_movement.gd`, extract the current `_physics_process` block
      (lines ~45–66, direct `Input.is_action_pressed` calls) into a small
      input struct/dictionary (`{thrust: bool, rotate: float, firing: bool}`)
      gathered only when `is_multiplayer_authority()` on the *client* side.
- [ ] Add `@rpc("any_peer", "call_remote", "unreliable") send_input(input)`
      on the ship: client calls it every physics tick with its local input;
      server receives it, validates the sender is this ship's owning peer,
      and stores it as "current input" for that ship.
- [ ] Server's `_physics_process` runs the actual movement/`move_and_slide`
      simulation using the last-received input for every ship it owns
      authority over (the server owns authority over all ships in the
      dedicated-server model).
- [ ] Add a `MultiplayerSynchronizer` per ship replicating `position`,
      `rotation`, `velocity` from server → clients.
- [ ] Get this working *without* prediction first: local ship will feel
      laggy (input → server → back). That's expected at this stage — fixed
      in Phase 7.

---

## Phase 5 — Shooting / bullets over the network

**Goal:** bullets are server-simulated and replicated, not spawned locally
by each client.

- [ ] `ship_movement.gd`'s fire logic (~line 72) currently does
      `get_parent().add_child(bullet)` directly on whichever peer runs it.
      Change so firing is just another bit in the input struct from Phase 4;
      server decides when a shot is actually fired (respecting fire-rate
      cooldown server-side, not trusting client timing).
- [ ] Server instantiates `bullet.tscn` via a `MultiplayerSpawner` (or
      manual spawn + RPC) under a shared `Bullets` container in
      `world.tscn`.
- [ ] `bullet.gd` currently self-simulates movement in `_process` and
      resolves damage locally via `body_entered`. Keep bullet *movement*
      client-side-predicted for visual smoothness if desired, but damage
      resolution (`take_damage()` call, ~lines 15–20) must only happen on
      the server's copy of the bullet.
- [ ] Despawn bullets server-side when out of `world_bounds`; replicate
      despawn to clients.

---

## Phase 6 — Server-authoritative health / death / respawn

**Goal:** no client can kill, heal, or respawn anything except by asking the
server.

- [ ] Move `take_damage` / `_die` / `_respawn` (`ship_movement.gd` lines
      ~104–135) so the actual state mutation only runs where
      `multiplayer.is_server()` is true. Clients only ever display the
      replicated result.
- [ ] Add an authority check at the top of `take_damage`: reject calls that
      didn't originate from the server (bullets are already server-spawned
      after Phase 5, so this mostly falls out naturally — but double check
      nothing client-side can still call it directly).
- [ ] Replicate `health`, `is_dead` (or similar) via the ship's
      `MultiplayerSynchronizer` from Phase 4 so HUD and visuals update on
      all clients.
- [ ] Respawn: server decides timing/position and re-broadcasts spawn
      state; don't let respawn timers run independently on each client.

---

## Phase 7 — Client-side prediction & reconciliation

**Goal:** local ship feels responsive despite server round-trip; remote
ships move smoothly despite update-rate gaps.

- [ ] Local client: predict own ship's movement immediately on input
      (re-run the same movement function locally that the server runs),
      rather than waiting for the server echo.
- [ ] Server periodically sends authoritative position/velocity/tick back to
      the owning client; client reconciles by snapping/blending toward it
      if prediction drifted (basic version: hard snap if error exceeds a
      threshold; polish later with smoothing).
- [ ] Remote ships (not locally owned): interpolate between the last two
      received network states instead of snapping on every update.
- [ ] This is the highest-skill, most iterative phase — budget real time for
      tuning "feel," not just correctness.

---

## Phase 8 — Real server browser / connect flow

**Goal:** menus do what they currently only pretend to do.

- [ ] `menu/server_browser.gd`'s server list is a single hardcoded
      "Trench Wars 0/32" entry. Replace with either: (a) a small manual
      "enter IP" field for direct-connect testing, or (b) if a lightweight
      server-list service exists by this point, query it.
- [ ] `menu/main_menu.gd`'s CASUAL/RANKED buttons currently skip networking
      entirely and load `world.tscn` locally. Route CASUAL through the same
      `NetworkManager.join_server` path once a target server is chosen.
- [ ] Handle connection failure / timeout UI (currently nothing exists for
      this — `connection_failed` signal has no handler anywhere).

---

## Phase 9 — Testing & hardening

- [ ] Test with 2 clients, then push toward the real casual target (25v25)
      to find where naive full-replication breaks down (bandwidth, spawn
      storms). Consider interest management / relevance culling only if
      needed at that scale — don't build it preemptively.
- [ ] Artificially add latency/packet loss locally (Godot has debug tools
      for this, or use `tc`/`netem` on Linux) and verify prediction/
      reconciliation still feels acceptable.
- [ ] Verify a client can't cheat: send garbage/rapid-fire input via a
      modified client and confirm the server-side rate limits / bounds
      checks (added in Phases 4–6) actually hold.

---

## Phase 10 — Deferred / parallelizable (not blocking core multiplayer)

These don't block getting ship-vs-ship combat working over the network and
can happen in parallel or after Phases 1–9:

- [ ] Matchmaking backend (queue, MMR, lobby assignment) — see `tech.md`'s
      Go/Node + Redis + Postgres sketch.
- [ ] GodotSteam integration (auth, VAC, lobbies).
- [ ] Lag compensation (server-side rewind for hit validation) — only
      matters once hit-detection precision is actually being contested;
      skip until basic damage registration is proven reliable.
- [ ] Bot fill for casual matches (`bots.md`) — depends on Phases 3–6 being
      done, since bots need to be simulate-able the same way real players'
      ships are.
- [ ] Galaxy war meta / sector control — orthogonal system, layer on top
      once match-level multiplayer is solid.

---

## Effort summary

| Phase | Relative effort | Notes |
|---|---|---|
| 1. ENet bootstrap | Small | 1–2 days |
| 2. Per-peer state | Small–Medium | Mechanical, touches every menu script |
| 3. Spawning | Medium | Camera/HUD ownership bugs are the sharp edges |
| 4. Input/sim split | Medium | The core refactor of `ship_movement.gd` |
| 5. Bullets | Small–Medium | Mostly follows the pattern from Phase 4 |
| 6. Authoritative health | Medium | Mostly enforcement of what Phase 4/5 set up |
| 7. Prediction/reconciliation | Medium–Large | Iterative feel-tuning, not just correctness |
| 8. Real menus | Small | UI wiring once NetworkManager exists |
| 9. Testing/hardening | Medium | Scales with target match size (25v25) |
| 10. Deferred systems | Large, but parallelizable | Doesn't block core multiplayer |

**Bare working version (Phases 1–6, no prediction polish):** roughly 1–2
weeks of focused work. **Feeling good at 25v25 (through Phase 9):** the long
pole — budget significantly more for iteration on Phase 7 in particular.