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.