CosmicClash/multiplayer-todo.md

Online multiplayer — architecture and task breakdown

Working document for the online multiplayer effort. TODO.md points here.

Everything below is written so an agent (or a person) can pick up a single numbered task, do it, verify it against a stated acceptance criterion, and stop. Sections 1–6 are the decisions those tasks assume; read them before picking up work in Phase 2 or later.

Status: Phase 0 done, Phase 1 done, Phase 2 done — milestone gate passing. A real two-process 1v1 runs: a headless server hosts, a client joins through the lobby, spawns into a server-picked arena, drives its ship via real held input, and renders server-authoritative movement (verified: 26–31 m over a 2 s held-thrust drive, purely from interpolated snapshots) with camera and HUD attached — and this still holds under --net-sim-latency 80 --net-sim-jitter 20 (task 2.8's net_sim.gd), which is Phase 2's own stated gate, not just LAN. No own-ship/ball prediction yet (Phase 4) — everything the client renders, including its own ship, comes from the interpolation buffer. See §7 for per-task status and evidence.

---

1. Architecture decisions

1.1 Locked decisions

#	Decision	Why
1	Server-authoritative simulation, with client-side prediction of the local ship and ball. No world rollback / resimulation.	Jolt is not bit-deterministic across platforms or across differing contact orderings, and Godot exposes no world snapshot/restore API. Rollback netcode would be a research project.
2	Dedicated servers only. Headless Godot export; the server is never a player.	Fair for every player, no host advantage. Self-hostable community servers first, so nothing is blocked on paid infrastructure.
3	ENet first, GodotSteam later, behind a boundary.	ENet works in-editor, headless, on LAN, and in CI with no Steam client. Direct-IP connect stays permanently supported and must never become the degraded path.
4	No custom backend.	Steam's ISteamGameServer master-server listing covers discovery, ISteamMatchmakingServers covers the in-game browser, and Steam auth tickets cover identity and ban state. README.md's C# backend stays unstarted.

1.2 Rejected alternatives

• Peer-authoritative ships (each client owns its own transform). Easiest to build, feels perfect locally, and is trivially cheatable — it directly contradicts README.md's stated anti-cheat position. Ship-vs-ship collisions also become ambiguous with no arbiter.

• Deterministic lockstep / rollback. See decision 1.

• MultiplayerSynchronizer / MultiplayerSpawner. The decisive objection is not bandwidth. It is that last_processed_input_seq must arrive in the same packet as the state it describes, or reconciliation is off by a snapshot — and a synchroniser gives you nowhere to put it. It also writes replicated properties directly onto the node, which is exactly wrong for a RigidBody3D under prediction: incoming state has to enter a compare-against-history pipeline, not be stamped onto global_transform. You would end up building the correction pipeline anyway, with the synchroniser as pure overhead. Secondary objections: one packet per body (7 bodies × ~50 B of UDP/IP/ENet framing versus one coalesced snapshot), no per-field quantisation, and no client-side interpolation.

  MultiplayerSpawner is unnecessary for a separate reason: the roster is fixed at match start and fully described by the match_config message, and no ship is ever despawned (§6.4).

• Seeded RNG for kickoff jitter. Shared-seed determinism requires both sides to consume the RNG stream in exactly the same order forever. The first randf() anyone later adds anywhere in the reset path — a spawn VFX variation, a cosmetic, a commentary line — silently desyncs kickoff positions with no error message. The server broadcasts the resulting transforms instead: 336 bytes, once per kickoff, cannot rot.

1.3 Derived decisions

All hot-path RPCs live on autoloads. /root/NetworkManager and /root/MatchNet exist at identical paths on every peer regardless of which scene is loaded, which side is headless, or whether a client is mid-scene-transition. This deletes the entire "NodePaths must match across peers" class of bugs, kills a family of late-join races where an RPC arrives before its target node exists, and warms Godot's RPC path cache once at connect so it never re-sends a full path on scene change.

Entities are addressed by integer slot, never by path. The snapshot is [slot 0..N-1] in a fixed order established by match_config. MatchNet holds an Array[Node] _slots populated at spawn.

One server process hosts exactly one match. This is forced, not chosen: ship.gd:162 resolves the arena boundary via get_tree().get_first_node_in_group("arena_boundary") and ai_ship_controller.gd discovers its roster via get_tree().get_nodes_in_group("ship"). Both are tree-global, so two matches in one scene tree would cross-wire instantly. It is recorded here because it determines the RAM figure in §1.4.

1.4 Server sizing — bandwidth and CPU are not the constraint

Worth establishing up front, because §2 and §3 repeatedly trade bandwidth for latency and somebody will eventually want to trade back.

ArenaBoundary.bake_colliders() generates roughly 168 box colliders (corner fillets, base wrap, ceiling, end walls) plus the scene's own slabs, 2 goal backstops, 2 Area3D sensors, and 7 dynamic bodies (the ball with continuous_cd). Estimated per-tick cost:

Component	ms/tick
Jolt step	0.15 – 0.4
Godot headless main loop	0.1 – 0.3
Bot inference, amortised (see task 0.8)	~0.3
Total, of a 16.7 ms budget	0.6 – 1.1

→ ~6–10 concurrent matches per modern core, ~150–250 MB RSS per process. 100 concurrent matches ≈ 12–16 cores and ~20 GB — a single mid-tier VPS. Upstream bandwidth for a full 6-player match is ~630 kbit/s (§2.4).

Neither CPU nor bandwidth is scarce. Latency is. Optimise accordingly.

---

2. Wire format

Two peers must agree byte-for-byte, so this is specified rather than sketched.

2.1 Channels

Channel	Transfer mode	Contents
0	reliable	handshake, match_config, kickoff, goal, clock, state changes, chat, admin
1	unreliable-ordered	client → server input
2	unreliable-ordered	server → client snapshots

Unreliable-ordered (ENet sequenced-unreliable, drops stale) rather than plain unreliable for both hot paths: we carry explicit sequence numbers, and a reordered late packet is worthless work. Separating them stops a large reliable match_config from head-of-line-blocking state on a lossy link.

Verify at implementation time. Godot's ENetMultiplayerPeer reserves low ENet channels for its own system messages and offsets transfer_channel on top. The intent above is "three logically distinct channels"; the concrete indices may need an offset. Confirm empirically, don't assume.

Set ENetMultiplayerPeer.server_relay = false. It defaults to true, which lets any client rpc() any other client through your server. With it off, clients can only talk to peer 1. Single highest-value one-line security change in this document.

2.2 Packet header

Every hot-path packet opens with a 1-byte type + version. A capture then decodes standalone, and a mismatched build fails loudly instead of decoding garbage straight into state.transform.

Hot paths carry a single PackedByteArray RPC argument (≈14 B of Godot RPC framing once the path cache is warm). Control messages on channel 0 use normal typed arguments — they are rare and readability beats bytes.

2.3 Input packet — client → server, channel 1, 60 Hz

u8   type_version
u32  seq                 server-tick-space sequence of the NEWEST action
u8   count               1..4 (MAX_REDUNDANCY)
u32  ack_snapshot_tick   newest snapshot tick this client has processed
u16  client_send_ms      wrapping ms clock, echoed back for RTT
--- repeated `count` times, newest first ---
i8   thrust_x, thrust_y, thrust_z    value = clamp(round(v*127), -127, 127)
i8   rot_x, rot_y, rot_z
u8   flags                           bit0 = turbo

12 + 7×4 = 40 B payload, ~90 B on the wire with UDP/IP/ENet framing → ~43 kbit/s up per client.

• Redundancy 4 is what makes an unreliable input channel safe: starvation requires four consecutive losses (~66 ms).
• i8 per axis, not 3-bit bins. Bins matching ShipActionCodec.HEADS would cut an action to 3 bytes, but they permanently foreclose analog gamepad sticks, which this game will want. round(v*127)/127 round-trips -1/0/+1 exactly, so today's digital input (player_ship_controller.gd is is_action_pressed-only) is lossless.
• The encoding is itself a validator. i8/127 cannot express NaN, Inf, or a value outside [-1.008, 1.008]. Half of "sanitise untrusted client input" is solved by not using Variant encoding.

2.4 Snapshot — server → client, channel 2, 60 Hz default

Per-client header built per peer; body buffer built once per tick and reused across peers.

--- per-client header (7 B) ---
u32  last_input_seq        newest input from THIS client the server has applied
i8   input_buffer_depth    jitter-buffer occupancy; negative = starved
u16  echo_client_send_ms   from that input packet, for RTT

--- shared body header (8 B) ---
u8   type_version
u32  server_tick           Engine.get_physics_frames() on the server
u8   match_state           see §6.1
u8   reset_gen             increments on every authoritative teleport
u8   body_count

--- repeated body_count times, slot order fixed by match_config (22 B each) ---
i16  pos_x, pos_y, pos_z         range ±64 m   -> 1.95 mm
i16  quat_x, quat_y, quat_z      w = ±sqrt(1-x²-y²-z²), sign in flags
i16  vel_x, vel_y, vel_z         range ±64 m/s -> 1.95 mm/s
i8   avel_x, avel_y, avel_z      ships ±4 rad/s; ball ±32 rad/s
u8   flags                       bit0 frozen, bit1 turbo, bits2-4 thrust_z bin,
                                 bit5 stalled, bit6 quat_w sign

7 bodies → 8 + 7 + 7×22 = 169 B payload, ~219 B on the wire.

	per client down	server up, 6 clients	+ 10 spectators
60 Hz	105 kbit/s	631 kbit/s	1.68 Mbit/s

MTU headroom is ~6× (ENet fragments above ~1400 B); a hypothetical 10v10 at 21 bodies is 477 B and still fits. This format does not need delta compression.

Plain i16 quaternion components, not smallest-three. Smallest-three saves 4 B/body and is the textbook answer. It is also exactly where a hand-rolled codec goes subtly wrong — off-by-one in the 2-bit index, sign of the dropped component, renormalisation drift — in a project that has no test framework yet. Three i16s plus a sign bit give ~3e-5 rad with no bit-shifting, for 2 B/body (≈3 kbit/s). Take the bytes.

Quantisation ranges derive from constants, not from prose. ArenaBoundary.INNER_HALF_X = 18.0, INNER_HALF_Z = 27.0, INNER_HEIGHT = 18.0 (arena_boundary.gd:8-10) plus GameMode.ESCAPE_MARGIN = 15.0; Ship.max_speed = 35.0 (ship.gd:16); Ball.MAX_SPEED = 32.0 (ball.gd:17).

CLAUDE.md's Architecture section states the play volume as "inner x ±12, z ±18, height 12, goal lines z ±17". That is stale — see the real constants above. Task 0.13 fixes the doc.

The flags byte must carry turbo and a 3-bit thrust_z bin. _integrate_forces is not called on frozen bodies, so remote ships on a client never pull get_action(), and Ship._update_movement_vfx() (ship.gd:293) reads _current_action.thrust.z and turbo. Without those bits, every remote ship flies with dead engines.

2.5 Reliable control messages, channel 0

hello · welcome · player_joined · player_left · ready_state · match_config · scene_ready · kickoff · state_change · goal_scored · clock_state · match_ended · chat · server_shutdown.

---

3. Server-side input handling

Per-player server state:

class PlayerSlot:
    var peer_id: int
    var slot: int                   # snapshot index
    var ring: Array[ShipAction]     # FIXED 32 entries, indexed seq % 32
    var ring_seq: PackedInt32Array  # 32 entries, seq stored at each index (-1 = empty)
    var last_applied_seq: int
    var last_action: ShipAction
    var starved_ticks: int
    var packets_this_second: int
    var remote_controller: RLShipController   # see §7 task 5.7 — null on takeover

3.1 Ingestion

@rpc("any_peer", "unreliable_ordered", channel = 1), in order:

1. multiplayer.get_remote_sender_id() → look up slot. Unknown sender → drop and count.
2. Rate limit. packets_this_second > 110 (60 Hz × 1.5 + 20) → drop. Three consecutive seconds over budget → disconnect with RATE_LIMIT. Same for a byte budget.
3. Framing. count > 4 or payload_size != 12 + count*7 → drop, count malformed. 20 malformed → disconnect.
4. Sequence range. seq > server_tick + 20 → drop. (Not 120: input_lead is clamped to 12, so anything above ~20 is broken or hostile.) This is why the ring is fixed-size and indexed seq % 32 — a client can never make the server allocate.
5. For each action, newest first at descending seq: seq <= last_applied_seq → discard (already consumed); else write ring[seq % 32].
6. Decode with per-axis clamp only:

   action.thrust = Vector3(b[0]/127.0, b[1]/127.0, b[2]/127.0).clampf(-1.0, 1.0)
   

Never normalise the thrust vector. A player holding W+A+E legitimately produces thrust = (1,1,1), length 1.73, and each axis uses a different power constant — thrust_power 150, maneuvering_thrust 75, vertical_thrust 120 (ship.gd:12-14). Normalising would silently change the flight model for honest players. Per-axis clamp combined with the i8 encoding is complete validation: the reachable value space is exactly what a legitimate client can produce.

3.2 Consumption — once per server physics tick, before the step

expected = last_applied_seq + 1
if ring holds expected:
    action = ring[expected % 32];  starved_ticks = 0
else:
    action = last_action           # REPEAT — do not zero
    starved_ticks += 1
    if starved_ticks > 30:         # 500 ms
        action = ZERO_ACTION;  flags.stalled = true
last_applied_seq = expected
last_action = action
remote_controller.action = action

Repeat-last, not zero. Player inputs are heavily autocorrelated at 60 Hz — the odds that a held thrust was released on exactly the dropped tick are low, and the client predicted with the real input either way, so repeating minimises expected divergence. It is also consistent with AIShipController, which already holds its action between decisions. Zeroing after 500 ms stops a disconnecting player's ship flying into a wall at full throttle forever.

3.3 Jitter buffer — one control loop, not three

An earlier draft had the server adapting target_depth, the server fast-forward-dropping queued actions, and the client slewing input_lead. Three integrators acting on one plant (buffer occupancy) with different time constants is a textbook oscillation; on a jittery link it hunts, and it presents to the player as intermittent sticky controls that are nearly impossible to attribute.

The server reports input_buffer_depth in every snapshot and does nothing else adaptive. The client owns input_lead exclusively.

• target_depth = 1 (16.7 ms), not 2. With redundancy-4 you have already bought the insurance depth 2 provides; depth 2 is 16.7 ms of pure input latency for nothing.
• Client input_lead clamp [1, 12], fast attack / slow release: on any starve, increase by up to 3 immediately; decrease by 1 per 60 ticks only after 2 s of clean surplus. A symmetric ±1-per-500 ms slew takes two seconds to absorb a wifi spike, during which the player steers and the ship does not turn — the most rage-inducing failure mode in any netcode.
• Changing input_lead means skipping or duplicating one tick's sequence number. Never change it more than once per 30 ticks.

Enforce input_lead server-side from observed arrival times. A client that fakes starvation to drive input_lead to 1 gets its inputs applied with less server-side buffering than honest players — a small but real responsiveness edge. The i8 encoding does nothing about this; only observing actual arrival timing does.

---

4. Prediction and reconciliation

4.1 Two clocks for remote entities — the load-bearing correction

The obvious design runs remote ships and the ball as frozen kinematic proxies at server_time_est - INTERP_DELAY while predicting the local ship to now. That is wrong, and it is wrong in a way that only shows up over real latency:

• Two ships closing at 50 m/s put the opponent's collider 3.5 m from truth. The hull is a BoxShape3D of (1.6, 0.6, 4) (ship.tscn:12) — that is most of a ship length of positional lie.
• A fast ball is 2.2 m off against a 0.5 m radius — four ball diameters.
• ship.tscn:16 has collision_mask = 7: ships collide with ships, the ball, and the arena. Ship-vs-ship contact is constant in vehicle soccer, not incidental.

So prediction would not diverge occasionally due to timing noise. It would diverge deterministically and in the same direction on essentially every contact, and the hard-snap threshold would become the steady state rather than a backstop.

Fix: separate the collider clock from the render clock.

	runs at	why
remote body collider	server_time_est, extrapolated forward from the newest snapshot by ~one-way + half a snapshot interval	Extrapolation error over ~45 ms at real accelerations (thrust_power 150 / mass 5 = 30 m/s², 75 m/s² on turbo — ship.gd:12,15, ship.tscn:17) is ~0.03–0.08 m. Two orders of magnitude better than 3.5 m.
remote $Visual	server_time_est - INTERP_DELAY	Smooth, jitter-free rendering.

This is the same trick applied to the local ship, pointed the other way. It costs one extra transform write per remote body per tick.

4.2 Where each piece lives

Concern	Location
sample + send input	LocalNetShipController._physics_process — runs before the physics step, guarantees exactly one sample/tick
record predicted state	same, at top of tick N (state = result of N−1)
apply velocity / teleport correction	Ship._integrate_forces, ~15 guarded lines — the only Jolt-safe place to write state.transform / state.linear_velocity
visual smoothing	Ship/$Visual.global_transform, set in _physics_process
snap-vs-blend decision	net_ship_predictor.gd (child node)
remote bodies	net_interpolator.gd

4.3 Per-tick, own ship

1. predicted[current_tick - 1] = {transform, linear_velocity, angular_velocity} — ring of 128.
2. var a := _player.get_action().copy() — must copy. player_ship_controller.gd reuses a single ShipAction across ticks (its own header warns about this); buffering it aliases every history entry to the same object. See task 0.1.
3. _action = a, returned by get_action() this tick so Ship._integrate_forces samples input exactly once.
4. input_history[seq] = a, seq = predicted_server_tick + input_lead.
5. Build and send the packet with the last 4 entries.

Ship._integrate_forces then runs completely unchanged.

4.4 On snapshot arrival

A = last_input_seq
if reset_gen changed OR predicted[A] missing OR flags.frozen != local frozen:
    HARD SNAP
else if pos_err > 2.0 m OR rot_err > 60°:
    HARD SNAP
else:
    SOFT CORRECT

Comparing server state at tick A against predicted[A] — the client's own state at that same tick — makes the delta latency-free by construction. That is the entire reason for keeping the prediction ring, and it is why this works acceptably without resimulation: never blend current state toward stale state.

SOFT CORRECT

• Velocity: applied in full, immediately. net_vel_correction += (srv.linvel - predicted[A].linvel), consumed once in _integrate_forces. Velocity error is invisible to the player but is the cause of future position error; blending it just prolongs divergence.
• Position/rotation: physics moves in full, rendering does not. Queue the body teleport, and simultaneously offset $Visual by the negation. Net visual movement at the instant of correction: zero. The body is where the server says; the rendered ship catches up.
• Decay each physics tick, reusing the existing convention at ship.gd:450:

  var k := _tick_scaled(0.88, delta)   # 63% gone in ~130 ms, 95% in ~280 ms
  

• MAX_VISUAL_OFFSET = 0.4 m, not 2.0. The hull is 4 m long; a 2 m offset means being rendered half a ship-length from your own collider for ~280 ms, so you clip walls you visibly cleared — a felt bug in a game built around wall-riding. Beyond 0.4 m, show the correction. A visible correction is honest; an invisible 2 m lie is not.

HARD SNAP

• Set body transform and velocities from the server values, caught up to the current tick (below), reset_physics_interpolation() on the body and on $Visual, zero the visual offset.
• Backfill the prediction ring for ticks A..current. Do not clear it — "missing predicted[A]" is itself a snap condition, so clearing guarantees the next snapshot also snaps, turning isolated snaps into bursts.

Catch-up replays the ship's own force formulas, not ballistic dead-reckoning. Input-free extrapolation is not unbiased: turbo acceleration is 150 × 2.5 / 5 = 75 m/s², so a 6-tick catch-up lands ~0.375 m short in the direction the player is accelerating, on every snap, and the ship feels permanently rubbery under sustained thrust. Replaying 6–12 stored ShipActions through apply_thruster_forces / apply_rotation_forces / apply_drag_and_limits / apply_righting_torque (ship.gd:361-486 — pure float math, no Jolt dependency) is ~30 lines and ~1000 float ops.

This is not world rollback and does not touch locked decision 1. It replays one body against a frozen world and needs no determinism guarantee.

4.5 Camera and visuals

The camera must follow $Visual, not the body. ship_camera.gd:115, :149, :150 read target.global_transform directly. Left as-is, every soft correct makes the camera jump the full error while the mesh smoothly lags — strictly worse than snapping, because the world lurches around a player whose ship slides inside the frame.

And it must read $Visual.get_global_transform_interpolated() from _process, not global_transform from _physics_process (task 0.16, rationale in §5.4). Node3D.get_global_transform_interpolated() exists precisely for a camera tracking a physics-interpolated body; global_transform returns the last physics tick's pose, so a _process camera reading it would chase a 60 Hz staircase at 240 fps.

Ordering hazard, straight from the engine docs: get_global_transform_interpolated() "creates an interpolation pump on the Node3D the first time it is called, which can respond to physics interpolation resets… be sure to call it at least once before resetting the Node3D physics interpolation." Every hard snap calls reset_physics_interpolation() on $Visual. Prime the pump when the camera's target is assigned, not lazily on the first frame, or the first snap of the match streaks the camera.

project.godot has physics_interpolation=true, and $Visual's own local transform is interpolated too — so reset_physics_interpolation() must be called on $Visual as well as the body, or every snap smears the mesh for a frame. (This is the same artefact game_mode.gd:263 already exists to prevent.)

4.6 Remote bodies on the client

• freeze = true, freeze_mode = FREEZE_MODE_KINEMATIC — not STATIC, or Jolt cannot derive contact velocity from the per-tick transform delta and your predicted ship hits a static wall instead of a moving ship.
• net_interpolator.gd samples the snapshot buffer (last 8 per body); collider at server_time_est (§4.1), $Visual at server_time_est - INTERP_DELAY.
• The two samples run on different clocks and different callbacks. The collider is a physics concern: _physics_process, 60 Hz. $Visual is a render concern: _process, sampled at true render time with physics_interpolation_mode = OFF so Godot does not interpolate an already-per-frame transform. On a 240 Hz client this is 240 distinct remote-ship positions per second instead of 60, and one fewer tick of lag, for no extra cost — the buffer lerp is happening either way (§5.4).
• INTERP_DELAY = one_way_ms + snapshot_interval * 1.5 + 2.5 * jitter_ewma, clamped [25, 200] ms. At 60 ms RTT / 60 Hz / 5 ms jitter that is 30 + 25 + 12.5 ≈ 68 ms.

The one_way_ms term is not optional, and omitting it is a silent architectural failure. server_time_est (§4.7) estimates what the server clock reads right now. The newest snapshot in hand was stamped one_way ago — §4.1 says exactly this when it extrapolates the collider forward "by ~one-way + half a snapshot interval". So rendering $Visual at server_time_est - INTERP_DELAY only interpolates if INTERP_DELAY ≥ one_way. Set it to the buffer alone (~38 ms at 60 Hz) and the render cursor lands on or past the newest sample: the bullet below about extrapolating past the newest snapshot becomes the steady state rather than the exception, and every remote entity is permanently dead-reckoned. The 25 ms clamp floor is reachable on LAN only.

• Past the newest snapshot, extrapolate on last known velocity for at most 150 ms, then hold. Never extrapolate indefinitely — a stuck ship reads better than one flying through a wall.
• Never write linear_velocity to a frozen body. Godot/Jolt zeroes and holds velocity on frozen bodies, so ball.gd:35's linear_velocity.length() trail driver will not work that way. Add Ball.set_visual_speed(speed) mirroring the Ship.set_visual_action(thrust_z, turbo) pattern. Don't route presentation data through a property the physics server owns.
• Call reset_physics_interpolation() on remote bodies at every kickoff.

4.7 Clock

server_time_est = local_ms + clock_offset, clock_offset from ping/pong on channel 0 every 1 s using the minimum-RTT sample in a rolling 5 s window (the min-RTT sample has the least queueing error).

Freeze tick_offset at match start. Seed it exactly from the handshake (server_tick + round(one_way / tick_ms)) and absorb all subsequent drift into input_lead alone. The prediction ring is indexed in server-tick space, so slewing tick_offset during play silently reinterprets every historical entry and produces sporadic, unreproducible false snaps. Re-seed only across a kickoff boundary.

---

5. Latency and frame-rate budget

Three of the largest terms are invisible to a netcode document that only counts network hops. Record the budget so future changes are argued against a number.

Client at 60 Hz physics, 60 ms RTT, 5 ms jitter, 60 Hz snapshots. Display at 60 Hz with vsync on — the Godot default, and the worst case. §5.4 redoes the display-dependent rows for 120/144/165/240/360 Hz.

5.1 Own ship (predicted) — input to pixel

Stage	ms		scales with fps?
OS input → Input.is_action_pressed	10	0.5 × frame interval + device polling	partly — see below
wait for next physics tick	8	avg of 0–16.7	no — 60 Hz physics
physics step applies force	0
Godot physics interpolation	8	physics_interpolation=true; mean, worst case 16.7	no — 60 Hz physics
render + vsync present	25	1.5 refresh intervals, vsync defaults on	yes
Total	≈52

This is the existing single-player floor, unchanged by netcode — and ~43 of those 52 ms are things no netcode document discusses. A low-latency present would take it to ~35 ms (§5.4).

Two notes on the model, both corrected from an earlier draft that read ≈45:

• Input freshness is 0.5 of a frame interval, not 0.25. Godot pumps OS input once per main-loop iteration and Ship._integrate_forces (ship.gd:347) consumes it once per physics tick; for arrivals distributed uniformly between pumps the mean staleness at the pump is half the interval. On top sits device polling, which does not scale with fps at all: ~1 ms at a 1000 Hz mouse or gamepad, ~8 ms at a 125 Hz USB device. The table assumes ~2 ms.
• Physics interpolation's 8 ms is a mean. Rendering happens between the two most recent completed ticks, so displayed pose lags the newest state by (1 − fraction) of a tick — 0 to 16.7 ms, averaging 8.3. The worst case matters for §5.4's discussion of frame-time variance.

Note the right-hand column: 16 of the 52 ms do not move no matter how many frames the client draws. That is the price of a 60 Hz simulation.

5.2 World response — the number that decides whether this ships

Stage	ms
input freshness	10	0.5 × frame interval + ~2 ms device polling
wait for next physics tick	8
manual multiplayer flush	~0	~8 with default idle-frame poll — see §7 task 1.3
client → server transit	30	RTT/2
jitter buffer, target_depth = 1	17
server tick + flush	8
server → client transit	30	RTT/2 — the return leg
interpolation buffer beyond arrival	38	interval × 1.5 + 2.5 × jitter; the one_way half of INTERP_DELAY is the row above
client physics interpolation	8
render + present	25	vsync on, 60 Hz display
World response, opponents	≈174
Ball, with local prediction	≈52	same as own ship
Both, at 144 Hz + low-latency present	148 / 26	§5.4

Correction — this table previously read ≈138 ms and omitted the server→client transit row entirely. INTERP_DELAY was quoted as 38 ms, which is the interpolation buffer measured from snapshot arrival, while §4.6 defines the render cursor relative to server_time_est — server-now. The 30 ms return leg fell between the two definitions and was never counted. §4.6's formula is corrected to include one_way; this table keeps the two terms on separate rows because that is clearer to budget against.

For reference, Rocket League runs 120 Hz physics and predicts both car and ball locally; its equivalent at 60 ms RTT is roughly 90–110 ms.

≈174 ms as designed here is not competitive, and this document should not pretend otherwise. It is also not the end state: §5.6 gets to ≈127 ms with two changes that touch no graphics setting and require no bot retrain, and to ≈103 ms with 120 Hz simulation — inside the reference band. Read §5.6 before treating this table as a verdict.

What is settled is the shape of the design: a locally-predicted ball and own ship at ≈52 ms is the difference between this being playable and not, and a 30 Hz / default-poll / interpolated-ball design would land near ≈250.

5.3 Why 60 Hz snapshots, not 30

• Interpolation buffer: the interval × 1.5 term is 50 ms at 30 Hz vs 25 at 60, on top of the one-way term both share (§4.6), plus a half-interval of cadence quantisation.
• Interpolation fidelity: at MAX_SPEED = 32 the ball moves 1.07 m between samples at 30 Hz — more than its own diameter, so any wall bounce landing between two samples gets lerped as a straight line through the wall. At 60 Hz it is 0.53 m.
• Cost: 300 kbit/s. Per §1.4, bandwidth is not the constraint.

Keep --snapshot-hz 30 as an explicit degraded mode.

5.4 High-refresh-rate clients — 120 / 144 / 165 / 240 / 360 Hz

Players on high-refresh displays are the ones most sensitive to everything in this document, and the current code has three places where the client draws 240 frames but only 60 of them contain new information. Those are bugs, not tuning.

What frame rate actually buys

Modelling present as ~1.5 refresh intervals with vsync on (§5.1), and input freshness as 0.5 of a frame interval plus ~2 ms of device polling:

Display	present	own ship / ball (§5.1)	world response (§5.2)	with low-latency present
60 Hz	25.0	52	174	35 / 157
120 Hz	12.5	35	158	27 / 149
144 Hz	10.4	33	155	26 / 148
165 Hz	9.1	31	153	25 / 147
240 Hz	6.3	27	149	23 / 145
360 Hz	4.2	24	146	21 / 144

This table assumes the client can actually produce those frames. It cannot — see §5.5. As configured today the project runs SDFGI, SSIL, SSAO, a 5-level glow pyramid, five shadow-casting lights, MSAA 4× and FXAA, and an unconditional full-screen backbuffer pass, none of which any player can switch off. Read §5.5 before treating any row below 60 Hz's as reachable.

Three conclusions to design around:

1. 60 → 144 Hz is worth ~19 ms on own-ship feel. 144 → 360 Hz is worth ~9. The curve flattens hard, because 16 ms of the remaining budget is the 60 Hz physics tick plus its interpolation and does not move.
2. A low-latency present is worth more at 60 Hz (−17 ms) than the entire jump from 144 to 360 Hz. It costs one settings dropdown.
3. Frame rate barely moves world response — 174 → 146 across the whole 60–360 range, because that budget is dominated by RTT and the interpolation buffer. Frame rate is an own-ship feel lever, not a netcode one. Say this to players plainly; someone who buys a 360 Hz monitor to see opponents sooner has been mis-sold.

Three things that must run per rendered frame, not per physics tick

a. The camera rig. ship_camera.gd:86 runs the entire rig in _physics_process. Global physics_interpolation=true smooths the resulting camera transform, so this is not visible as judder — but it costs an extra tick of camera latency on top of the ship's, and two things it does are not transforms and therefore not interpolated: camera.fov (:182) and the PostFX shader parameters (:186-187). At 240 fps those step at 60 Hz, which reads as a faint pulse in the turbo FOV kick.

The rig moves to _process, reading target.get_global_transform_interpolated() (and $Visual's, post-task 0.2) instead of target.global_transform, with physics_interpolation_mode = PHYSICS_INTERPOLATION_MODE_OFF on the rig itself so Godot does not re-interpolate an already-per-frame transform.

The move is cheap but it is not tuning-neutral. Cost first: one call is ~15 engine-bound operations (2 × get_noise_1d, 2 × set_shader_parameter, Basis.looking_at, slerp, orthonormalized, signed_angle_to, rotated, several global_basis accesses) plus ~60–100 bytecode ops — call it 5–15 µs. At 360 Hz that is 1.8–5.4 ms/s, under 0.5% of a core. Negligible, but negligible because the absolute work is tiny; 1-exp(-k·delta) is a correctness property, not a cost argument, and it does not license moving arbitrarily expensive code into _process.

The impact shake must be re-tuned, and in the opposite direction to what you would guess. ship_camera.gd:204 advances the noise coordinate by delta * 60.0, and :64 sets frequency = 2.5, so each sample steps delta × 150 noise units. At 60 fps that is 2.5 units per sample — simplex noise decorrelates over roughly 1 unit, so the shake is currently white noise, and physics interpolation is lerping between independent samples. At 360 fps in _process it becomes 0.42 units per sample, which is strongly correlated: the shake turns into a slow, smooth wobble that gets softer the better your monitor is. Re-derive frequency (or the * 60.0) for constant noise-units-per-second, then re-check amplitude by eye at 60 and 240 fps.

Everything else in the rig genuinely is rate-independent and needs no attention: 1.0 - exp(-k * delta) at :126, 137, 156, 172, 177 and move_toward(…, shake_decay * delta) at :212.

Two pre-existing bugs sit in the code this task touches, so fix them here rather than discovering them in Phase 5:

• The rig has no snap path. camera.global_position is smoothed at camera_smoothing = 10.0 (:14, 137, 156) with no reset anywhere in the file. At a kickoff teleport (game_mode.gd:256-263, becoming an _integrate_forces write under task 0.15) the camera lerps across the arena over ~300 ms. Add snap_to_target() — set global_position/global_basis directly, zero _last_shake_offset — and call it from the kickoff path.
• Shake decay stalls during a goal cut. :94-96 returns before _apply_shake, so _shake_strength's move_toward decay never runs for the length of the cinematic. Task 0.12 proposes building goal feel on exactly this system.

b. Remote-entity visuals. §4.6's interpolator samples a snapshot buffer between two known states. Driving that from _physics_process quantises every remote ship and the ball to 60 distinct positions per second and then leans on Godot to interpolate between them — an extra tick of lag for no benefit, since we are already interpolating. Sample the buffer at true render time in _process instead: 240 distinct positions per second and one fewer tick of lag.

The split is clean because the two consumers want different times anyway (§4.1): the collider is a physics concern and stays in _physics_process at server_time_est; $Visual is a render concern and moves to _process at server_time_est - INTERP_DELAY, with physics_interpolation_mode = OFF. Setting it OFF is coherent precisely because the node's global_transform is overwritten every rendered frame — there is nothing left for the engine to interpolate. Note this is the opposite of §4.5's rule for the local ship's $Visual, which is written per physics tick and therefore must stay interpolated and must be reset on snap. Same node name, two different regimes; task 0.16 lands in Phase 0 against local-ship semantics, task 2.4 adds the remote case.

It is not free, though it is cheap: per body per frame you bracket-search a ring of 8, run two Vector3.lerps and a Quaternion.slerp, build a Transform3D, and assign global_transform (which dirties and propagates to children). Estimate 3–6 µs per body → ~21–42 µs/frame for 7 bodies, ~1.5% of a core at 360 Hz. That is 4–6× the work of sampling at 60 Hz. Measure it in task 0.15b rather than asserting it.

c. Receive polling. Task 1.3 already flushes sends from _physics_process. Receiving is the other half: with (b) in place, a snapshot that lands 2 ms after a physics tick can be rendered 2 ms later at 240 fps instead of waiting 14 ms for the next tick. Poll for receive unconditionally at the top of both _process and _physics_process — no rate limiter. A zero-timeout enet_host_service on an empty socket is one non-blocking recvfrom returning EWOULDBLOCK, on the order of 1 µs; 360 of those per second costs ~0.36 ms/s. An earlier draft proposed a 2 ms limiter, which is worse than useless: at 240 fps the frame interval is already 4.17 ms so it never fires, and it only engages above ~500 fps where polling was already cheaper than the limiter.

Manual polling relocates the connection signals. With set_multiplayer_poll(false), peer_connected / peer_disconnected now fire from inside your poll() call — mid-_process, during a render frame — rather than on the idle-frame boundary. Any handler that mutates the scene tree must defer.

Frame-time variance, not mean frame rate, is the real target

At 240 fps the frame budget is 4.17 ms, and physics runs at 60 Hz — so one frame in four carries the entire physics tick and must still fit in 4.17 ms. On that frame the client pays, in one go: the Jolt step over 7 dynamic bodies against a 172-shape compound; 7 × Ship._integrate_forces (ship.gd:346-357), each running apply_thruster_forces, a full ArenaBoundary.get_surface_pull with five _falloff calls (arena_boundary.gd:183-198), apply_rotation_forces, apply_righting_torque and apply_drag_and_limits with two pow() calls via _tick_scaled (:450); 6 × _update_movement_vfx (:296-315, writing two material params and two OmniLight3D energies per ship); and on decision ticks, bot inference — policy_network.gd is a pure-GDScript MLP at 31→64→64→7 ≈ 6.5k multiply-accumulates per bot, so five bots landing together is ~33k GDScript float ops in one frame.

Task 0.8's decision stagger is framed above as a cosmetic hitch. It is not — the physics tick sets a floor on 1%-low frame time that no graphics setting can lower. A game that averages 240 fps but drops one frame in four to 8 ms is not a 240 fps game. Profile p99, not mean (task 0.15b).

The same term matters at the bottom of the range, where most players actually are: see gotcha 22 and task 0.22 for the client-side Engine.max_physics_steps_per_frame cap that stops a hitching client from spiralling.

What frame rate does not buy, so nobody optimises the wrong thing

Input sampling does not improve. player_ship_controller.gd:15-38 reads seven Input.is_action_pressed calls — all digital, all held-state — and Ship._integrate_forces pulls them once per physics tick. The state read at the tick is the freshest state; sampling it 240 times a second returns the same value 4 times in a row. The only thing lost is a press-and-release entirely inside one 16.7 ms tick, which is below human tap duration. Do not build a sub-tick input accumulator. If analog stick support is added later this changes, and the right answer is then a time-weighted average over the tick, not a higher sample rate.

Physics interpolation stays on. It costs ~8 ms (§5.1) and is the single largest fps-independent term after the tick wait, so it will look like a target. It is not: without it a 60 Hz simulation presents 60 distinct world states per second regardless of frame rate, which is precisely the stepping a 240 Hz display was bought to avoid. Leave it on; do not expose a toggle.

Why physics stays at 60 Hz, and what a bump would cost

The honest answer to "our players want 240 fps responsiveness" is that simulation rate, not frame rate, is the binding constraint — 16 ms of own-ship latency and ~33 ms of world response sit behind it, and §5.2 shows frame rate alone cannot get world response under ~146 ms. Doubling to 120 Hz (Rocket League's rate, with snapshots raised alongside) would take world response from ≈174 to ≈141 ms and own-ship from 52 to ≈44, at 60 Hz display — or ≈115 ms combined with a 144 Hz display and a low-latency present:

Term	60 Hz sim	120 Hz sim
wait for next tick	8.3	4.2
physics interpolation	8.3	4.2
jitter buffer, depth 1	16.7	8.3
server tick + flush	8	4
interpolation buffer	37.5	25.0	only the interval × 1.5 term halves; the jitter term does not
client ↔ server transit	60	60	does not move

That is a bigger win than every tuning parameter in §3 and §4 combined. It is nonetheless out of scope for v1, for reasons that are about the project rather than the netcode:

• Every policy in Game/bots/ is invalidated. ship.gd:450's _tick_scaled is defined against a 60 Hz reference and ai_ship_controller.gd's reaction_ticks counts ticks. A bump means a full retrain — and per TODO.md the generation-5 curriculum is still running.
• Server density halves, ~6–10 matches per core to ~3–5 (§1.4).
• Bandwidth roughly doubles: input 43 → 86 kbit/s up, snapshots 105 → 210 kbit/s per client, 631 kbit/s → 1.26 Mbit/s per 6-player match. Still not the constraint, but 100 concurrent matches becomes ~126 Mbit/s of server uplink, which is a hosting-plan question rather than a rounding error.

The consequence for this plan is a hard rule: 60 is a constant named NetCodec.TICK_HZ, never a literal. Ring sizes, INTERP_DELAY, input_lead clamps, seq-window bounds, snapshot cadence and the timeout constants all derive from it. Task 1.4's handshake already gates on physics_ticks_per_second, so a mismatched client is rejected rather than silently desynced. Done this way, a later bump is a config change plus a retrain — not a protocol rewrite. Done the other way, the literal 60 ends up in twelve files and the bump never happens.

Client display settings

project.godot sets neither display/window/vsync_mode (defaults to enabled/FIFO) nor application/run/max_fps (uncapped). video_settings.gd:14-16 persists only AA, glow and brightness, and settings_menu.gd exposes only those three. Task 0.17 adds:

VSync: Enabled (FIFO) · Adaptive (default) · Mailbox · Disabled.

• Adaptive (FIFO_RELAXED) is FIFO while the renderer keeps up and tears only on a missed vblank. That is the right default for a game that will sometimes drop below refresh, because it avoids FIFO's half-rate cliff — miss 144 Hz by one millisecond under strict FIFO and you are pinned to 72.
• Mailbox only lowers latency when the renderer sustains above the refresh rate; below it there is never a second frame to replace the queued one, so it degenerates to FIFO latency at Mailbox power draw. Per §5.5 this build will not sustain above 144 Hz on typical hardware today, which makes Mailbox an opt-in for players with headroom, not a default. Defaulting to it would be a thermal regression for most players in exchange for nothing.

FPS cap: derived from the display, not a fixed list. Query DisplayServer.screen_get_refresh_rate(DisplayServer.window_get_current_screen()) and offer "Match display" (default), the integer divisors of that rate, then Unlimited — 144 Hz → 144/72/48, 165 Hz → 165/82/55, 240 Hz → 240/120/80/60.

Non-divisor caps beat against scanout. A fixed 60/75/90/…/360 list is wrong on every panel that is not 60 or 120 Hz. Cap at 100 on a 144 Hz display and gcd(100,144) = 4: the pattern repeats every 25 frames across 36 refreshes, with frames held for one or two intervals in an irregular sequence — visible micro-stutter. 120 on a 165 Hz panel is 8 frames per 11 refreshes, same failure. Offer the free-form list only behind an Advanced toggle with a warning.

Three implementation constraints, all of which an earlier draft got wrong:

• Engine.max_fps is a throttle, not a pacer. It pads each frame with a post-frame sleep to hit 1/max_fps; it has no knowledge of scanout and never phase-locks to a vblank. (Sleep-granularity jitter of roughly ±0.5–1 ms is inferred, not measured — verify on target platforms. The absence of phase locking is structural.)
• Grey out the FPS cap whenever VSync is not Disabled. With both active, FIFO clamps presents to vblanks while max_fps pushes some frames past the next one and not others — frame pacing worse than either setting alone. The menu must not permit the combination.
• Godot cannot report the negotiated present mode. DisplayServer.window_get_vsync_mode() echoes back the mode you stored, not the VkPresentModeKHR the driver granted, and there is no GDScript API that exposes the latter. An earlier draft's "report what was actually applied" is not implementable, and neither is an in-engine present-latency measurement (that needs LDAT or a high-speed camera). Instead put a live Performance.get_monitor(Performance.TIME_FPS) readout next to the dropdown: whether the player is above or below their refresh rate is the fact every one of these settings depends on.

The renderer is Forward+ (project.godot:21, config/features=PackedStringArray("4.7", "Forward Plus")), so the usual "Mailbox is unavailable on Compatibility" caveat does not apply as written — but rendering/renderer/rendering_method is not pinned in project.godot, so a --rendering-method gl_compatibility launch or a driver fallback loses it silently. Mailbox is also commonly unavailable on macOS/MoltenVK. (Needs empirical verification on target OS versions.)

5.5 Can this build produce frames at all?

§5.4's table describes a machine this project is not. Nothing in the repo has ever been profiled, and the render configuration is a showcase build, not a competitive one. Every item below is on by default and none is reachable from video_settings.gd, which persists exactly three values (:14-16: aa_mode, glow_scale, brightness).

From scenes/arena_base.tscn, the Environment every arena inherits:

arena_base.tscn	Setting	Note
:47-50	sdfgi_enabled, sdfgi_use_occlusion, sdfgi_bounce_feedback = 0.5	Godot 4's most expensive GI path; cascades re-voxelise as the camera moves, and this camera never stops (ship_camera.gd:126,137,156)
:42-46	ssil_enabled, ssil_radius = 4.0	A full-resolution screen-space pass on top of SSAO
:34-41	ssao_enabled, ssao_radius = 2.5, ssao_detail = 0.75
:18-29	glow_enabled, 5 levels	Mip pyramid built and resolved every frame
:61, 78, 87, 96, 105	1 directional + 4 shadow-casting OmniLight3Ds	Omni shadows are cubemaps: 24 shadow-map faces per frame before the directional

Plus project.godot [rendering]: msaa_3d=2 (4×) and screen_space_aa=1 (FXAA) and use_debanding=true — mirrored by video_settings.gd:14 defaulting to MSAA_FXAA. Stacking FXAA on resolved MSAA is redundant blur, and the menu (settings_menu.gd) offers no 2× rung between "off" and "4×".

Plus shaders/post_process.gdshader:4, uniform sampler2D screen_texture : hint_screen_texture — a full-screen backbuffer copy every frame, unconditionally. The shader's comment notes that non-turbo frames skip two texture taps, but the copy and the full-screen pass happen regardless because vignette_strength never reaches zero (ship_camera.gd:187 writes 0.22 + …, :243 restores 0.22).

What is not the problem, so nobody optimises the wrong thing:

• The 168 colliders (§1.4) cost zero frame time. They are CollisionShape3Ds on a StaticBody3D — no draw calls, no vertices. The count is confirmed correct (168 generated + 4 authored slabs = 172 in objects/arena_boundary.tscn).
• The scene is not geometry- or draw-call-bound. arena_boundary.gd's visual shell is ~1450 triangles in two surfaces of one MeshInstance3D; the whole match is on the order of 100–150 draw calls and well under 50k vertices. That is nothing.

The project is bound entirely by full-screen passes the player cannot switch off. That inverts §5.4's conclusion about where the leverage is: the largest win per line of code is not a vsync dropdown, it is a graphics preset that gates SDFGI/SSIL/SSAO/omni shadows. Task 0.15b blocks 0.16 and 0.17 for exactly this reason — every number in §5.4 is a priori, and the first measurement may invalidate the fps list entirely.

One mitigating subtlety, which cuts both ways: project.godot [display] sets window/stretch/mode="viewport" with a 1920×1080 base and aspect="expand", so the 3D renders at a fixed ~1080p and is blitted to the window. A 1440p or 4K player therefore does not pay more for any of the above — but also cannot render at native resolution, and a 1080p player cannot render lower. Task 0.17c owns that decision; it interacts directly with render scaling (0.17b) and cannot be left implicit.

5.5.1 Measured (task 0.15b, 2026-08-18)

6-ship Match, 1080p, non-headless. Hardware: Apple M4 (Metal), 10-core — a development laptop, not a dedicated gaming reference machine; treat absolute fps as directional, not a promise to players on other hardware.

	p50	p99	fps (p50 / p99)
All effects on (project defaults)	17.93 ms	20.39 ms	55.8 / 49.0
All effects off	~17.2 ms	—	~58

This invalidates the a priori §5.4/§5.5 fps list exactly as flagged. Default settings cannot sustain even 60 fps on this hardware, let alone 144 — and the surprising part is why: turning every toggleable effect off (SDFGI, SSIL, SSAO, glow, all 5 shadow casters, MSAA, FXAA, PostFX) only recovers the difference between ~56 and ~58 fps. The ~17 ms floor is not made of the full-screen passes this section blamed — something else (base forward-clustered shading, the ~150 draw calls, per-ship VFX materials, or fixed engine/CPU overhead at 6 ships) dominates, and 5.4's framing ("the project is bound entirely by full-screen passes") is wrong as measured on this hardware.

Per-effect isolated cost (each toggled off individually against a fixed baseline sample), for reference — treat these as low-confidence: they cluster tightly at 2.9–3.8 ms each with no clear outlier, which is consistent with most of that spread being sampling noise from a ~1 ms-jittery baseline rather than real per-effect attribution:

Setting	Cost (ms)
SSAO	3.77
PostFX	3.82
Omni shadows (×4)	3.69
SSIL	3.44
FXAA	3.37
Directional shadow	3.30
SDFGI	3.24
MSAA 4×	3.12
Glow	2.89

Consequence for 0.17/0.26/0.28: a graphics preset alone will not reach a 144 fps target on hardware in this class — Low-preset gets to only ~58 fps by this measurement, not the 2×+ jump §5.4 assumed. 0.26 (bake GI) and 0.28 (separate physics thread) need to re-justify their expected win against this floor before implementation.

Root-cause follow-up, attempted and inconclusive (2026-08-18). Three further remote-automated profiling passes (via godot-mcp game_eval sampling Performance.get_monitor() against a live instance, no human at the editor) were run to find what the ~17 ms floor actually is. They did not converge:

Pass	Setup	Result
1 (above)	6-ship 3v3, sustained	17.93 / 20.39 ms (p50/p99), all-off floor ~17.2 ms
2	Reportedly 6-ship, actually 1v1 (misconfigured)	CPU 17.64 ms + frame 10.75 ms — internally inconsistent (CPU time exceeding frame time from non-atomic sampling); agent also reported the game becoming unresponsive mid-run
3	6-ship 3v3, atomic single-eval sampling, retried after pass 2's failures	8.7–10.2 ms (98–115 fps), reported CPU time 0.013 ms — implausibly low for a frame running Jolt physics + GDScript bot inference across 6 ships, so not trusted either

Passes 1 and 3 supposedly measured the same scenario and differ by ~2×. The likely explanation is the measurement method itself, not the game: each game_eval round-trip through the MCP bridge has its own latency and can perturb the very frame timing it's sampling, and nothing here confirms the scene state (ship count, bot activity, camera framing) was identical across passes. Read the specific numbers in this subsection as evidence a floor well under 144 fps exists, not as an attributed cause — the SSAO on/off screenshot check in pass 3 did confirm effect toggles are visually real (ruling out "the toggles are no-ops" as an explanation), which is the one finding that survived across passes.

What this needs next, and why an agent can't finish it remotely: a proper frame-time attribution needs either a human at the Godot editor reading the Debugger's built-in Monitors/Visual Profiler (which breaks GPU time down by pass — opaque, shadow, post-process, etc. — instead of one aggregate number), or an external GPU profiler (RenderDoc, Xcode GPU capture on this hardware). Both require eyes on a live UI, not remote eval polling. This is now the concrete blocker for 0.26/0.28, not further scripted measurement passes. 0.15b's original acceptance criterion (write a max-frame-rate number into §5.5) is still met by pass 1 — the floor is real and under both 60 and 144 fps — but the deeper "why" is open and parked here rather than guessed at.

Root cause of the pass-to-pass inconsistency, found (2026-08-18): a Godot editor and an orphaned headless training process had both been running on the profiling machine, untouched, for 11 days (since 2026-08-08) — leftover from earlier local work, unrelated to this investigation. godot-mcp's automated launches were plausibly contending with that stale editor instance rather than getting a clean process every pass, which is a much better explanation for a ~2× swing between "identical" scenarios than genuine frame-time variance. Both processes were killed and a clean re-check was run.

Is it just that we're on a Mac? Partly, but not via the mechanism first suspected. HiDPI/Retina resolution inflation was checked directly and ruled out: the live viewport renders at 2036×1080 against a target of 1920×1080 — about 6% more pixels, non-uniformly (width only; the 2× multiplier a true Retina backbuffer would apply is not happening, display/window/dpi/allow_hidpi=true notwithstanding). A 6% pixel-count difference cannot produce the ~2× frame-time swings seen above, so resolution is not the explanation for this session's inconsistency — that was the stale-process contention above. It's still worth a one-line fix later (0.17c owns display/stretch decisions) since 2036×1080 is a mildly wasteful, non-native render target.

What Mac hardware does plausibly bias is the shape of the result, not the run-to-run noise: Apple Silicon GPUs are tile-based deferred renderers (TBDR), architecturally unlike the immediate-mode AMD/Nvidia GPUs the target "reference hardware" (a Windows/Linux gaming PC) uses. TBDR keeps a frame in on-chip tile memory and is comparatively cheap at MSAA resolve, but any pass needing to read arbitrary neighbouring pixels across the whole frame — SSAO, SSIL, the glow downsample/upsample chain, the PostFX shader's screen_texture read — forces a break out of tile memory into a full system-memory resolve, an overhead that is largely constant per pass rather than proportional to what the pass computes. That lines up with pass 1's finding that SDFGI/SSIL/SSAO/MSAA/FXAA/shadows/PostFX all cost within a tight 2.9–3.8 ms band regardless of what each one actually does — consistent with a shared TBDR resolve tax dominating over each effect's real cost. Numbers measured on this machine should be treated as informative about relative ordering at best, not as a stand-in for target-platform (desktop GPU) behaviour — confirmed below.

5.5.2 Measured on real reference hardware — RTX 3090, Linux (2026-08-19)

Same 6-ship 3v3 Match, 1080p, via a purpose-built harness (Game/tools/gpu_profile_harness.gd) run directly against a real GPU-bound X session (not Xvfb — an earlier attempt through Xvfb silently fell back to Mesa's llvmpipe software rasterizer, ~35x slower and completely unrepresentative; caught via the harness's own adapter-name check, not assumed). This is the number that matters — an actual discrete immediate-mode GPU, the architecture players will actually have:

	p50	p99	fps (p50)
All effects on (project defaults)	1.85 ms	2.98 ms	540
All effects off	0.53 ms	1.53 ms	1883

This overturns §5.5.1's conclusion, not just its numbers. On real hardware, disabling every effect gives a 3.5× speedup — the opposite of the Mac's ~1.03× — and the per-effect breakdown finally makes physical sense instead of clustering suspiciously:

Setting off	Frame time	Implied cost
(baseline, all on)	1.85 ms	—
SDFGI	1.49 ms	0.36 ms
SSIL	1.60 ms	0.25 ms
Glow	1.75 ms	0.10 ms
Shadows (all 5 casters)	1.76 ms	0.09 ms
SSAO	1.82 ms	0.03 ms
MSAA 4×, FXAA, PostFX	1.87–2.12 ms	noise-level (see below)

SDFGI and SSIL alone account for over half of the effects' total cost, matching §5.4's original expectation (voxel cone tracing and a full-res screen-space GI pass being the expensive ones) — the Mac's flat, undifferentiated cost profile was the anomaly, not this one. MSAA/FXAA/PostFX show negative "costs" (disabling FXAA measured as slightly slower than leaving it on) — at ~1-2 ms absolute frame times, OS scheduling jitter is larger than the real signal for cheap passes; those three need a longer sampling window or a proper GPU profiler to resolve, not this harness's coarse get_process_delta_time() sampling. Note also that all-off (0.53 ms) is faster than baseline-minus-sum-of-individual-savings (1.85 − 0.36 − 0.25 − 0.10 − 0.09 − 0.03 ≈ 1.02 ms) — the combined removal saves more than the parts, consistent with each full-screen pass carrying some fixed per-pass overhead (pipeline barriers, render-target switches) on top of its own work, which compounds when several stack.

Consequence for 0.17/0.26/0.28, revised: at 540 fps p50 with every effect enabled, this scene is nowhere near GPU-bound on reference-class hardware — the entire "must hit 144 fps" framing in §5.4/§5.5 was solving a problem that doesn't exist on the hardware tier it was written for. That reframes the two gated tasks rather than clearing them outright:

• 0.26 (bake GI, retire SDFGI) — the relative win is real and correctly targeted (SDFGI is the single largest line item, ~19% of the effects-on budget), and the preset design already bets on this being right (Low/Medium turn SDFGI+SSIL off first, matching exactly what this data says to cut). But "largest frame-time reduction of any task here" (its acceptance bar) oversells it on a 3090 — 0.36 ms off an already-tiny budget is not the headline win §5.7 implied. The task is worth doing for lower-end/integrated GPUs, where the same relative cost almost certainly scales to something that matters — but that's now the open question, unmeasured on this pass.
• 0.28 (physics/3d/run_on_separate_thread) — its whole motivation is smoothing frame-time variance caused by the physics tick sharing the render thread; at a 1.85 ms p50 / 2.98 ms p99 baseline (both far under even a 240 Hz frame budget), there's no variance problem to fix on this hardware. Deprioritize below 0.26 unless a lower-end-hardware pass shows otherwise.
• The preset ladder itself (task 0.17, done) needs no changes — its bundle choices (drop SDFGI/SSIL first) are now empirically justified rather than just plausible-sounding.

Still open: no low/mid-tier GPU has been profiled. The 3090 result rules out "the game is GPU-bound on reasonable hardware" as a near-term concern, but says nothing about a GTX 1660 or an integrated Iris/Vega part, which is where a real preset ladder earns its keep. Re-run gpu_profile_harness.tscn on weaker hardware before spending more effort on 0.26/0.28.

5.6 Closing the gap to the reference — without lowering settings

§5.2 lands at ≈174 ms against a ~90–110 ms reference band. The instinct is that reaching it means trading visual quality for frames. It does not. Decompose the 174:

At 60 ms RTT, 60 ms is transit and irreducible in code. That leaves 114 ms of local overhead, of which frame rate governs only two terms — input freshness (10) and present (25) — and quality settings govern neither directly. Present latency is a function of vsync mode and swapchain depth, not of how many effects are enabled; a 60 fps client with a shallow present queue beats a 240 fps client with a deep one. The entire 60 → 240 fps range is worth ~12 ms once a low-latency present is in place (§5.4). The other ~100 ms is netcode time model and simulation rate.

Four levers, none of which touches a graphics setting:

	Lever	Saves	Risk
L1	Extrapolate remote visuals to present time instead of interpolating the past	−30	Mis-prediction pops
L2	120 Hz simulation	−21	Bot retrain, ½ server density, 2× bandwidth
L3	Adaptive jitter-buffer depth, 0 on clean links	−8	Starvation on jittery links
L4	Shallow present queue + Adaptive vsync	−17	Throughput loss if GPU-bound

L1 is the big one, and it is nearly free

§4.1 already computes remote entities' present-time state — that was the fatal correction that put the collider at server_time_est. $Visual is then deliberately rendered ~68 ms in the past for smoothness. Render it at present time too and the whole 37.5 ms interpolation buffer disappears, leaving only a residual for error smoothing.

The reason this is safe here is that ships have bounded acceleration and the hull is large. Extrapolating with known velocity, error is ½·a·t² over the full 68 ms horizon:

	max accel	error @ 38 ms	error @ 68 ms
position, cruise	30 m/s² (thrust_power 150 / mass 5)	0.022 m	0.069 m
position, turbo	75 m/s² (turbo_multiplier 2.5)	0.054 m	0.173 m
yaw	20 rad/s² (rotation_power 20 / inertia.y 1)	0.8°	2.6°
pitch / roll	2.9 rad/s² (inertia.x/z 7)	0.1°	0.4°

0.17 m and 2.6° worst case, against a 4 m hull. That is well under the width of the ship and an order of magnitude smaller than the 3.5 m staleness §4.1 was written to eliminate. Feed the residual through the same soft-correct pipeline already specified for the local ship (§4.4) and remote ships are visually at present time with a sub-decimetre wobble.

Two bonuses: it collapses §4.1's dual clock back into one — collider and visual both at server_time_est, so §5.4b's _process/_physics_process split and the two-regimes-for-one-node-name hazard both go away — and it applies to the ball, which is near-ballistic between contacts and therefore extrapolates better than ships do.

The cost is real but narrow: a remote ship that reverses input at the moment you sample it mispredicts by the numbers above and then visibly corrects. Interpolation never mispredicts; it is just always late. This is the genuine trade, and it is the one the reference class makes.

The reachable budget

Term	today	L1 + L4 (v1)	+ L2 + L3	at 144 fps
input freshness	10	10	10	5.5
wait for next tick	8.3	8.3	4.2	4.2
client → server	30	30	30	30
jitter buffer	16.7	16.7	4.2	4.2
server tick + flush	8	8	4	4
server → client	30	30	30	30
interp buffer → extrapolation residual	37.5	8	8	8
client physics interpolation	8.3	8.3	4.2	4.2
present	25	8.3	8.3	3.5
World response	≈174	≈127	≈103	≈94

≈103 ms at 60 fps with every effect enabled, and ≈94 at 144 fps. That is inside the reference band, reached without disabling SDFGI, SSIL, SSAO or shadows. Even a client struggling at 30 fps on maximum settings lands near ≈120 ms.

Sequencing follows ms-per-unit-of-risk: L4 then L1 for v1 (≈127 ms, no bot retrain, no protocol change); L2 and L3 after, when a retrain is affordable. §5.5's preset system remains worth building — but for frame rate and thermals, which is what it actually buys, not for latency.

The largest lever is not on this list. All of the above assumes 60 ms RTT. Regional server siting that puts most players on a 30 ms RTT takes ≈127 to ≈97 and ≈103 to ≈73 with no code at all. Phase 6 owns it, and it should be argued against these numbers.

Perspective on where this matters. Own ship and ball are already at ≈52 ms and are unaffected by every lever here — they are predicted locally. World response governs opponent ships. In a game whose subject is a ball, that ordering is favourable: the two objects a player tracks most closely are the two already at single-digit-tick latency.

5.7 The next tier — and where it stops paying

§5.5 and §5.6 are the first-order work. This section is what remains after them, and it is deliberately honest about the point where further effort stops being worth it.

Frame rate: SDFGI is the wrong tool for this arena

The single largest available win, and it costs no visual quality. arena.gd and goal.gd have no _process, no _physics_process, no AnimationPlayer and no Tween — the floor, walls, ceiling, goals and every light are static for the entire match. The only things that move are 6 ships and a ball, all small and all self-lit.

SDFGI exists to light dynamic worlds, and it pays for that by re-voxelising cascades as the camera moves — and this camera never stops moving (ship_camera.gd:126, 137, 156). It is the most expensive thing in the frame, doing continuous work to solve a problem this project does not have.

• Replace sdfgi_enabled with baked GI — LightmapGI for the static shell, or VoxelGI if bounce onto moving ships matters. Bake cost is offline; runtime cost is a texture fetch. The look is preserved or improved (baked bounce is higher quality than SDFGI's cascades), and it survives on the High preset rather than being the first thing a preset has to switch off.
• ssil_enabled becomes largely redundant once bounce is baked. It is a full-resolution screen-space pass duplicating information the lightmap already has.

This is the answer to "lowest lag and highest fps without lowering settings": the expensive setting was solving the wrong problem.

Frame rate: expensive defaults that project.godot never overrides

[rendering] contains exactly three keys (msaa_3d, screen_space_aa, use_debanding). Everything else runs at engine defaults, including:

Setting	Default	Note
lights_and_shadows/positional_shadow/atlas_size	4096	Shared by all shadowed positional lights; 2048 is usually indistinguishable here
lights_and_shadows/directional_shadow/size	4096
lights_and_shadows/directional_shadow/soft_shadow_filter_quality	high
occlusion_culling/use_occlusion_culling	off	Low value in an enclosed arena — measure before adding bake time
mesh_lod/lod_change/threshold	—	Irrelevant: the scene is ~1450 triangles of arena plus low-poly ships (§5.5)

Also worth counting: _build_movement_vfx creates two OmniLight3Ds per ship (ship.gd:270-278), so a 3v3 has 12 dynamic lights on top of the arena's 5. They are correctly shadow_enabled = false and omni_range = 3.5, so they are cheap — noted so nobody "discovers" them and disables engine glow for nothing.

Frame rate: the CPU side, which §5.5 does not cover

§5.5 establishes the project is GPU-bound on full-screen passes. Once those are fixed it becomes CPU-bound, and §5.4's frame-time variance becomes the ceiling. Three levers:

• physics/3d/run_on_separate_thread (not set; defaults off). This decouples the physics step from the render thread and directly attacks "one frame in four carries the whole tick." It is the highest-leverage item here and the riskiest — it changes when _integrate_forces runs relative to script code, and this project puts real logic there (ship.gd:346-357) plus an RL training path. Prototype and measure; do not enable on faith.
• ArenaBoundary.get_surface_pull has no early-out. It runs a to_local() plus five _falloff calls for every dynamic body every tick, including for a ball sitting in the middle of the arena where every term is zero. A single bounds check against wall_range/ceiling_range skips almost all of it in open play — 7 bodies × 120 Hz once L2 lands.
• Bot inference is ~6.5k GDScript multiply-accumulates per bot (policy_network.gd). Task 0.8 staggers them; beyond that, the lever is network width, which is a training decision, not a rendering one.

Latency: what is actually left

After L1–L4 and 120 Hz simulation, at 144 fps, the budget is ≈94 ms — and 60 of that is RTT. The remaining 34 ms of local overhead breaks down as input freshness 5.5, tick wait 4.2, jitter 4.2, server 4, extrapolation residual 8, physics interpolation 4.2, present 3.5. Every one of those is at or near a floor set by physics rate or hardware.

Two code ideas remain, both small and both with a cost:

• Forward-extrapolate the local $Visual instead of interpolating between the last two ticks — render the predicted ship at present time rather than up to one tick behind. Worth ~4 ms. Risk: overshoot at the moment of a collision, which is the most visually sensitive moment in the game.
• Tighten the extrapolation-error smoothing (§5.6's 8 ms residual). Worth ~4 ms, paid for in more visible correction pops.

That is the whole remaining code budget: ~8 ms, both items trading visual stability for it. Meanwhile:

• Regional server siting takes a 60 ms RTT to 30 for most players: −30 ms, four times the remaining code budget, no code at all.
• Ping-weighted matchmaking and a server browser sorted by measured ping convert that into something players actually experience rather than something that is true on average.
• Steam Datagram Relay (Phase 7) is planned for NAT traversal and DDoS protection, but Valve's backbone frequently routes better than raw BGP paths — for some player pairs SDR is a latency reduction, not a tax. Measure it both ways rather than assuming it costs.

Where this stops paying

Two limits worth writing down before someone spends a month on the last 5 ms:

1. Past ~100 ms, you are optimising 3–4 ms at a time against a 60 ms constant. The ratio of engineering effort to felt improvement collapses. Server siting and matchmaking dominate everything else from that point on.
2. "Lowest lag" and "best feel" diverge at the end. Both remaining code levers, and L1 itself, buy milliseconds by predicting further ahead and correcting harder. Past a point that makes the game feel worse — twitchier, less stable, more prone to visible snapping — while the latency number keeps improving. The number is a proxy, not the goal. Task 4.7's tuning pass, with a human in the seat, is the authority; the budget table is not.

---

6. Match lifecycle

6.1 State machine

LOBBY -> LOADING -> WARMUP -> PLAYING -> GOAL_PAUSE -> WARMUP -> ...
                                      -> FULL_TIME -> OVERTIME_WARMUP -> OVERTIME -> ...
                                      -> RESULTS -> LOBBY

Broadcast as the match_state byte in every snapshot, and on transition via state_change(state, at_tick).

6.2 Sequence

1. Connect. Client sends hello(protocol_version, physics_ticks_per_second, display_name, auth_ticket). Server rejects a mismatch on either version or tick rate, with a reason string, then disconnect_peer. (A client at 30 Hz advances its sequence numbers at half rate and confuses every control loop.) auth_ticket is an empty PackedByteArray until Phase 7 — reserve the field now.
2. Welcome. Server assigns player_id, balances teams, replies welcome(player_id, server_info, roster, match_state, server_tick, score, end_tick), broadcasts player_joined.
3. Lobby. ready_toggle(); start when all ready, or --auto-start after --min-players plus a countdown.
4. Config. match_config(match_id, arena_path, team_size, match_length_ticks, roster[], seed). roster[i] = {slot, team, spawn_index, player_id, name, is_bot} — slot order here is the snapshot's body order for the whole match. The client validates arena_path against ArenaRegistry.ARENAS before load(); a malicious or buggy server must not be able to make a client load an arbitrary res:// path.
5. Load. Both sides load networked_match.tscn. Each peer loads the arena and spawns the roster in slot order. Client additionally spawns a camera rig on its own ship and adds HUD.tscn in code — networked_match.tscn must have no HUD child, because GameMode._ready() (game_mode.gd:44-45) would pick it up server-side. Client sends scene_ready(match_id).
6. Kickoff. Server waits for all scene_ready (10 s timeout → proceed). Broadcasts kickoff(reset_transforms[], countdown_start_tick, reset_gen). Both sides freeze bodies. HUD counts down from server_tick, not a local Timer. At countdown_start_tick + 180 the server unfreezes and broadcasts state_change(PLAYING).
7. Play. Inputs up, snapshots down.
8. Goal. Server's Goal sensor fires → _handle_goal_scored debounce → goal_scored(scoring_team, score, goal_tick, resume_tick). Bodies freeze. Clients play the cinematic within [goal_tick, resume_tick]. At resume_tick: kickoff(...).
9. Clock. Tick-derived: remaining_ticks = end_tick - current_server_tick. end_tick and a running flag ship in match_config and in clock_state(running, end_tick, at_tick).
10. Full time / overtime / results. RESULTS holds, then state_change(LOBBY) and both sides load lobby.tscn. Clients return to the lobby, not the main menu — a community server that empties every 2.5 minutes is dead on arrival.

Every lifecycle message carries absolute ticks, never durations. That is what makes reliable-channel latency harmless: on a lossy link ENet's RTO can stretch a goal_scored → kickoff → state_change burst to ~600 ms. Specify the late-arrival case explicitly: a kickoff that lands after its own resume_tick must apply the reset immediately and skip the countdown, not schedule it into the past.

NetworkedMatch must declare all five signals HUDController duck-types on (HUDController.gd:65, 88, 100, 103, 106) — timer_updated, score_changed, match_ended, kickoff_countdown, overtime_started — and emit them from RPC handlers instead of from local logic. Otherwise the HUD silently omits rows.

6.3 Late joiners and spectators

welcome carries full state, so a late joiner reconstructs immediately.

• Free slot and state is LOBBY/WARMUP → join as a player now.
• Free slot mid-match → spectate now, take the slot at the next kickoff. Swapping a controller at a kickoff boundary is free; mid-play it is not.
• No free slot → spectator. A spectator receives identical snapshots (the snapshot is already a broadcast — zero extra server work), spawns no ship, and points a camera rig at a chosen ship or the ball. Cap with --max-spectators.

HUDController._initialize_hud() push_errors and bails when ship is null (HUDController.gd:41-46). Spectators need a path through that.

6.4 Disconnects — no ship is ever despawned

On peer_disconnected the server keeps the ship and swaps its controller:

1. --fill-bots: replace with an AIShipController on the server's configured model.
2. --no-fill-bots (default for public servers, see §1.4): swap to the base ShipController — inert but simulated, exactly the placeholder game_mode.gd:216 already uses.

Set flags.stalled so clients can grey out the nameplate. Reserve the slot for 30 s keyed by identity so a reconnect gets its ship back. If the last human leaves, abort to LOBBY.

Justification is wire-format simplicity, not the bot cache. Fixed slot order means the snapshot needs no add/remove machinery, no MultiplayerSpawner, and no re-indexing. That reason stands on its own.

ai_ship_controller.gd currently caches teammate/opponent lists once with the comment "rosters never change mid-match (no despawn path exists anywhere in this codebase)". Do not let that be the justification — protecting a bot's implementation detail is tail-wagging-dog, and taken as an architectural constraint it permanently forecloses 3v3→2v2 shrink, mid-match rebalancing, and join-onto-a-new-slot. Fix the cache anyway (task 0.9): filter(is_instance_valid) plus a roster_changed signal, ~5 lines of cheap insurance.

---

7. Phase and task breakdown

[P] parallelisable within its phase · [D:x.y] hard dependency

Phase 0 — Non-networked refactors

Every task lands on master independently, is verifiable in single-player today, and cannot break anything. Near-total parallelism.

#	Task	Files	Acceptance
0.1 [P]	DONE. Added ShipAction.copy(). Audit: the only get_action() call site (ship.gd:347) reassigns _current_action fresh each tick rather than buffering it, so no aliasing bug exists yet — copy() is a no-op today, ready for Phase 4's prediction ring	ship_action.gd, player_ship_controller.gd	Free Play unchanged; copy() returns a distinct object with equal fields
0.2 [P]	DONE. Inserted Visual (Node3D) into ship.tscn, reparented Nose/TailFin under it, redirected all four code-driven add_child calls onto $Visual (now a public @onready var visual), resolved _apply_team_color's lookup to "Visual/" + mesh_name	objects/ship.tscn, scripts/ship.gd	Child-type assertion holds; ship looks identical in Free Play; team colours still apply on both teams
0.3 [D:0.2]	DONE. ship_camera.gd's three target.global_transform reads (ball cam, ship cam ×2) now read target.visual.global_transform	scripts/ship_camera.gd	Camera behaviour unchanged in Free Play and Match — visual has identity transform relative to the body until Phase 4 writes an offset, so this is a no-op today
0.4 [P]	DONE. can_sleep = false on Ship and Ball	objects/ship.tscn, objects/ball.tscn	No behaviour change
0.5 [P]	DONE. continuous_cd = true on Ship (Ball already had it)	objects/ship.tscn	No tunnelling at max speed into the ball or walls
0.6 [P]	DONE. Spawned ships renamed to Ship_T%d_S%d	game_mode.gd	Names are (team, spawn_index)-derived, not insertion-order
0.7 [P]	DONE. _jittered now uses an owned RandomNumberGenerator, self-randomized in _ready() unless kickoff_rng_seed is set explicitly (a fresh RandomNumberGenerator defaults to a fixed internal state, unlike the global randf_range Godot auto-randomizes at startup — call this out for whoever reads the diff and expects .new() alone to be enough)	game_mode.gd	Kickoff jitter unchanged in feel; a fixed seed reproduces kickoffs exactly
0.8 [P]	DONE. _ticks_until_decision = randi_range(1, reaction_ticks) at spawn, after load_policy() (which still resets to 0 on later calls, e.g. league opponent swaps — harmless, those land at reset boundaries)	ai_ship_controller.gd	Six-bot Spectate shows no periodic frame spike
0.9 [P]	DONE. Roster validity checked (Array.any()) once per decision tick, not every physics tick; filter(is_instance_valid) + roster_changed signal only fire on an actual stale reference	ai_ship_controller.gd	Bots behave identically; freeing a ship mid-match no longer corrupts observations
0.10 [D:0.12] [P]	Add virtuals _owns_goal_logic(), _allows_time_scale_effects(), _goal_pause_seconds(), _owns_world_simulation() DONE, narrower than drafted. _allows_time_scale_effects() dropped: 0.12 deletes Engine.time_scale from the file entirely, so there is nothing left for it to gate. Implemented _owns_goal_logic(), _owns_world_simulation(), _goal_pause_seconds(), all behaviour-preserving (default true/GOAL_CELEBRATION_SECONDS), gating the goal-signal connection and _respawn_escaped_bodies()	game_mode.gd	Free Play, Match, Spectate and Training all behave identically — verified no other virtual was load-bearing today; these exist for a future networked-client mode
0.11 [P]	DONE. _handle_goal_scored checks is_inside_tree() after each await and bails before touching arena/hud state	game_mode.gd	A scene change mid-celebration cannot strand the flag
0.12 [P]	Replace Engine.time_scale hit-stop and goal slow-mo with camera-only effects DONE. Added ShipCameraRig's "Impact Punch" group (punch_fov_kick/punch_vignette_kick/punch_chroma_kick/punch_decay, applied additively after _update_speed_feel each tick, decaying via move_toward over real delta) triggered from the existing _on_target_ball_contact; goal moments now rely on the pre-existing begin_goal_cut/end_goal_cut cinematic cut alone, no separate slow-mo effect needed. All Engine.time_scale fields/methods deleted from game_mode.gd (_hit_stop_*, _goal_slowmo_active, _restore_hit_stop, _run_hit_stop, GOAL_SLOWMO_SCALE)	game_mode.gd, ship_camera.gd	Goal and impact feel is at least as good; Engine.time_scale is never written — confirmed via grep -rn time_scale scripts/
0.13 [P]	DONE. physics_jitter_fix = 0.0 set. CLAUDE.md's architecture section had stale prose dimensions ("inner x ±12, z ±18, height 12, goal lines z ±17") — corrected to reference the actual named constants (INNER_HALF_X 18, INNER_HALF_Z 27, INNER_HEIGHT 18, GOAL_LINE_Z = INNER_HALF_Z) instead of restating numbers that can drift out of sync again	project.godot, CLAUDE.md	Flight feel unchanged; CLAUDE.md matches arena_boundary.gd:8-14
0.14 [D:0.2]	DONE. Added Ship.set_visual_action(thrust_z, turbo), Ball.set_visual_speed(speed) (with a _visual_speed_override field the trail prefers when ≥0), and Ship.net_vel_correction/net_visual_offset fields plus the guarded hook at the top of _integrate_forces (decays net_visual_offset via _tick_scaled, writes it to visual.position)	ship.gd, ball.gd	No-op until Phase 4; single-player unchanged — nothing calls any of these yet
0.15 [P]	DONE. Ship/Ball gained queue_teleport(to); _integrate_forces applies it via state.transform + zeroed velocities + reset_physics_interpolation(). GameMode._reset_body now calls body.call("queue_teleport", to) (dynamic dispatch — RigidBody3D itself has no such method) instead of set_deferred	game_mode.gd, ship.gd, ball.gd	Kickoff resets in Match are visually identical, with no interpolation smear
0.15b	DONE, superseded by §5.5.2 — read that, not the Mac numbers below. First pass measured a live 6-ship Match, 1080p, on an Apple M4 dev laptop (§5.5.1): all-on p50 17.93 ms, all-off floor ~17.2 ms, with per-effect costs clustered suspiciously flat (2.9–3.8 ms each). That data turned out to be a poor stand-in for the target platform — Apple's tile-based GPU architecture, not a real bottleneck — and was superseded by a same-scenario re-run on real reference hardware (RTX 3090, §5.5.2): all-on p50 1.85 ms / all-off 0.53 ms, SDFGI+SSIL clearly dominant as originally expected, everything else cheap. Keep §5.5.1 for the record of what was tried and why it was distrusted, not as a performance reference	scenes/arena_base.tscn, shaders/post_process.gdshader, Game/tools/gpu_profile_harness.gd	Measured max frame rate written into §5.5.2 from real reference hardware. At 540 fps p50 with everything on, this scene is nowhere near GPU-bound on a 3090-class GPU — the a priori §5.4 fps list was solving for a constraint that doesn't hold at that hardware tier. 0.17 (done) needed no changes: its preset bundle choices are now empirically validated. 0.26 stays open (real but smaller win than assumed); 0.28 closed (no variance problem exists to fix)
0.16 [D:0.3]	DONE. Camera rig moved _physics_process → _process; reads target.visual.get_global_transform_interpolated() in both ball-cam and ship-cam; rig itself has physics_interpolation_mode = OFF (it writes its own transform every rendered frame now, so Godot's built-in interpolation would just fight the manual smoothing). target setter primes interpolation (target.visual.reset_physics_interpolation()) and calls the new snap_to_target() so a freshly-assigned target (or a Spectate switch) doesn't lerp in from wherever the rig was previously. Shake re-derivation, implemented differently than drafted: rather than rescale frequency, _apply_shake now quantizes the noise-domain input to whole 60Hz ticks (floori(_shake_time * SHAKE_UPDATE_HZ)) — every render frame within one 1/60s window reuses the identical noise sample, so consecutive distinct samples stay exactly frequency (2.5) domain-units apart at any render frame rate, reproducing 60fps's original jitter character everywhere instead of smoothing out at high fps. snap_to_target() is called from game_mode.gd's reset_ships(), not directly from ship_camera.gd's own kickoff-adjacent code — reset_ships() is now async and awaits one get_tree().physics_frame before snapping, because _reset_body's queue_teleport (task 0.15) defers the actual transform write to the ship's next _integrate_forces; snapping immediately would read the pre-teleport position. Goal-cut shake decay extracted into _decay_shake(), called from the _goal_cut_active branch. Validated: scripts compile, Free Play renders correctly non-headless, reset produces no camera jump, all three headless scenes exit clean	scripts/ship_camera.gd, scripts/game_mode.gd:reset_ships	Turbo FOV kick and post-process are smooth at an uncapped frame rate; shake reads the same at 60 and 240 fps; a kickoff cuts the camera rather than lerping it across the arena
0.17 [D:0.15b]	DONE. VideoSettings gains Preset (Low/Medium/High/Custom) driving a bundle (sdfgi_enabled, ssil_enabled, ssao_enabled, shadows_enabled, glow_enabled, aa_mode, resolution_scale) via apply_preset(); a settings_changed signal lets an already-loaded arena re-apply live (arena.gd connects in _ready()) rather than only affecting the next arena load — meets "settings persist and apply without a restart" without needing a scene reload. Shadow gating targets the actual Light3D nodes (found once at load via find_children, cached, re-applied on every settings change — deliberately not re-derived from current state each time, since a light this code just turned off would otherwise become indistinguishable from FillLight, which is authored shadow_enabled = false on purpose and must never be turned on by the preset ladder). vsync_mode (Disabled/Enabled/Adaptive, Adaptive default) and fps_cap_divisor (0 = uncapped, else divides the live refresh rate at apply time rather than storing a raw fps number, so the same preference re-derives correctly on a different display) added to the settings menu; FPS cap dropdown is disabled (greyed) unless VSync is Disabled; refresh-rate query ≤0 falls back to "Uncapped" only. Live fps readout via _process reading Performance.TIME_FPS. main_menu.gd's _leave_to_gameplay now calls VideoSettings.apply_fps_cap() instead of hardcoding Engine.max_fps = 0, so the player's cap actually reaches gameplay scenes. Acceptance numbers: not run as a literal Low-vs-High preset A/B, but strongly implied by §5.5.2 — real hardware (RTX 3090) runs the High-equivalent (all effects on) at 540 fps p50 already, so Low (which additionally turns off the two dominant costs, SDFGI+SSIL) clearing "≥2×" is close to guaranteed rather than measured directly; the flat-p99-histogram claim genuinely wasn't tested (gpu_profile_harness.gd measures per-toggle cost, not vsync/cap histograms)	scripts/video_settings.gd, scripts/settings_menu.gd, scenes/settings.tscn, scripts/arena.gd, scripts/main_menu.gd	Low preset ≥2× the frame rate of High on the same hardware; settings persist and apply without a restart; every offered cap gives a flat frame-time histogram (p99−p50 < 1 ms) with VSync disabled on a 144 Hz and a 165 Hz display; refresh-rate query returning -1 falls back cleanly
0.17b [D:0.15b] [P]	DONE. VideoSettings.resolution_scale (0.5–1.0, default 1.0) drives Viewport.scaling_3d_mode/scaling_3d_scale/fsr_sharpness via apply_resolution_scale() — SCALING_3D_MODE_FSR2 below 1.0 (chosen over bilinear: this project already gave up native resolution at the fixed-1080p blit per 0.17c, so FSR2's sharpening recovers more of that loss than a plain bilinear upscale at the same internal scale), SCALING_3D_MODE_BILINEAR with scale pinned to 1.0 at the top of the range (a no-op scaling mode when the scale is 1:1). Low preset defaults to 0.8. Exposed as a slider in the settings menu; not yet measured against the "0.7 scale gives a large, measurable frame-time drop" bar — same real-hardware caveat as 0.17	scripts/video_settings.gd, settings_menu.gd	0.7 scale gives a large, measurable frame-time drop with acceptable image quality; setting persists
0.17c [D:0.17b]	DONE — decided, not changed. Kept stretch/mode="viewport" fixed at 1080p rather than moving to "disabled", documented inline in project.godot [display] with rationale: 0.17b's scaling_3d_scale already covers "render lower than the window" independently of stretch mode (it scales the 3D viewport's internal resolution before this blit, not the window itself), and separately, task 0.15b found an unexplained ~6% non-uniform width scaling on the one machine this was tested on (2036×1080 measured against a 1920×1080 target — see §5.5.1) that needs understanding before stretch mode is touched, not blindly carried into a resolution-dependent change	project.godot	The decision and its rationale are written into §5.5; render resolution follows the player's setting
0.17d [P]	INVESTIGATED — no such lever exists in Godot 4.7. Searched the full project.godot schema (read_project_settings) for rendering/rendering_device/vsync/frame_queue_size and every variant (frame_queue, swapchain, present, present_queue) — none exist as a project-settable parameter in this engine version; the RenderingDevice backend may manage its own present queue internally but doesn't expose it. Adaptive vsync (task 0.17, done) is the only half of "L4" actually achievable through project settings. The §5.6 ~17 ms figure for a shallow present queue is therefore not obtainable as specced — closing this without a code change is correct here, not a shortfall; reaching it would need engine-level (C++/RenderingDevice) changes out of scope for a project-settings task
0.18 [P]	DONE, with one discovered GDScript constraint. New scripts/sim_constants.gd (class_name SimConstants, plain const TICK_HZ := 60, not an autoload) is the source of truth for ship.gd's _tick_scaled and training_mode.gd's TICKS_PER_SIM_SECOND — both reference it via const SimConstants = preload("res://scripts/sim_constants.gd") rather than the bare global class_name symbol, because a cross-script const X := f(OtherClass.CONST) initializer needs the reference resolved before the global class table is guaranteed populated. @export_range() upper bounds cannot take even a preloaded reference — export hint arguments must be true literals — so reaction_ticks/bot_*_reaction_ticks (ai_ship_controller.gd, match_mode.gd, spectate_mode.gd ×2) stay at a literal 60; these are editor-inspector slider bounds, not the timing math itself, so this doesn't reopen the bug the task exists to close, but it means the acceptance criterion below is met for tick-rate math and not for export-hint bounds	ship.gd, training_mode.gd, new scripts/sim_constants.gd	Tick-rate-derived timing math has no bare 60; changing TICK_HZ changes _tick_scaled and TICKS_PER_SIM_SECOND coherently. reaction_ticks export bounds remain literal by GDScript necessity
0.19 [P]	DONE. AAMode gained MSAA_2X, appended (not inserted) so existing user://settings.cfg ordinals keep their meaning; default aa_mode changed to FXAA; settings_menu.gd's AA_OPTIONS now lists five entries	video_settings.gd, settings_menu.gd	Five AA options; default is FXAA; existing saved preferences migrate without resetting
0.20 [P]	DONE. New autoload scripts/perf_overlay.gd (PerfOverlay), toggled by a new toggle_perf_overlay input action (F3 default). Headless-guarded; builds its own Label in code rather than touching HUD.tscn	new scripts/perf_overlay.gd, project.godot [input]	TIME_PROCESS vs total frame time tells the player whether they are CPU- or GPU-bound
0.21 [P]	DONE. Shared HudInstrument._throttled_redraw(delta) paces queue_redraw() to ~60/s; value smoothing itself still runs every _process call, only the repaint is throttled	scripts/hud_instrument.gd, scripts/hud_gauge.gd, scripts/hud_attitude_indicator.gd, scripts/hud_heading_tape.gd	HUD is visually identical; instrument _draw call count is capped at ~60/s regardless of frame rate
0.22 [P]	DONE. Engine.max_physics_steps_per_frame = 4 set in GameMode._ready(), applies to every mode including headless Training	scripts/game_mode.gd	A client throttled to 20 fps degrades smoothly instead of compounding
0.23 [P]	DONE. New autoload scripts/background_fps.gd (BackgroundFPS) drops to 30 fps on NOTIFICATION_APPLICATION_FOCUS_OUT / restores on focus-in, independent of scene. main_menu.gd/settings_menu.gd each cap to DisplayServer.screen_get_refresh_rate() in _ready() (falling back to uncapped on a -1 query); leaving the main menu for a gameplay scene uncaps again via a new _leave_to_gameplay() helper, since gameplay has no cap of its own yet (0.17)	new scripts/background_fps.gd, main_menu.gd, settings_menu.gd	An unfocused window and an idle menu both stop rendering at 900 fps
0.24 [P]	DONE. Both guarded with if DisplayServer.get_name() == "headless": return — arena.gd:_ready() skips the whole Environment block, video_settings.gd:_ready() skips apply_aa()	scripts/arena.gd, scripts/video_settings.gd	--headless allocates no Environment and no AA state
0.25 [P]	DONE. _process still calls to_local() every frame (needed for the comparison itself) but skips set_shader_parameter() — the actual GPU-facing cost — below a 0.05 m movement threshold	scripts/arena_boundary.gd	Field shader behaves identically; the expensive call is skipped on most frames
0.26 [D:0.15b]	Bake the arena GI and retire SDFGI (§5.7). arena.gd/goal.gd have no _process, no animation — the arena is fully static, and SDFGI is paying continuously to solve a dynamic-world problem this project does not have. Add UV2 to the arena shell, bake LightmapGI (or VoxelGI if bounce onto ships matters), disable sdfgi_enabled and re-evaluate ssil_enabled	scenes/arena_base.tscn, scenes/arena_0*.tscn, scripts/arena_boundary.gd	Largest frame-time reduction of any task here, with equal or better image quality; High preset keeps its look; bake is reproducible from a documented step
0.27 [P]	DONE. lights_and_shadows/positional_shadow/atlas_size and directional_shadow/size set to 2048 (from the 4096 engine default), soft_shadow_filter_quality=2	project.godot	Measurable frame-time reduction; no visible shadow-quality regression at 1080p
0.28 [D:0.15b]	CLOSED, not implemented — the problem it targets doesn't exist. Was: prototype physics/3d/run_on_separate_thread (§5.7) to attack frame-time variance from the physics tick sharing the render thread — the riskiest item in this phase, since it changes when _integrate_forces runs relative to script code, and both ship.gd:346-357 and the RL training path depend on that. §5.5.2's real-hardware measurement (RTX 3090) found a 1.85 ms p50 / 2.98 ms p99 baseline with every graphics effect enabled — both comfortably under even a 240 Hz frame budget, with no meaningful p99-over-p50 variance to explain away. Taking on this task's real risk (reordering _integrate_forces relative to script code, with the RL training path depending on today's ordering) for a variance problem that isn't measurably present is a bad trade. Reopen only if a lower-end-hardware pass (§5.5.2's "still open" item) finds real physics-tick-driven variance that 0.26 and the preset ladder don't already cover	—	(closed without a code change; see §5.5.2 for the evidence)
0.29 [P]	DONE. Bounds check against wall_range/ceiling_range at the top of get_surface_pull, returning Vector3.ZERO before to_local() and the five _falloff calls whenever every term would be zero mid-arena	scripts/arena_boundary.gd	Identical flight feel and identical RL observations; measurable tick-time reduction with 7 bodies

These tasks exist because of the high-refresh-rate mandate, and their order matters. 0.15b blocked everything else, and did invalidate the a priori fps list — but not in the direction first assumed (see §5.5.1 vs §5.5.2): on the Mac the game looked GPU-bound and undifferentiated; on real reference hardware (RTX 3090, §5.5.2) it runs at 540 fps p50 with everything on, nowhere near bound by anything. 0.17/0.17b/0.19 (done) are still the right frame-rate levers — SDFGI/SSIL genuinely dominate the optional-effects cost, exactly as originally assumed, just at a much smaller absolute scale than feared on this hardware tier. 0.16 and 0.20–0.25 are the per-frame hygiene that makes a high frame rate worth having. 0.18 buys nothing today — it is what keeps a future 120 Hz simulation a config change plus a retrain rather than a protocol rewrite. 0.28 closed without a code change (§5.5.2) — the frame-time variance it targeted isn't measurably present on reference hardware.

0.19–0.29 are all pure single-player wins with no netcode content. If the multiplayer effort is ever paused, they should still land. Within them, 0.26 (bake the GI) is the largest single frame-time win in the document and costs no image quality — the arena is fully static, so SDFGI is paying continuously for a problem this project does not have (§5.7). 0.28 is the riskiest; it is the only Phase 0 task that can plausibly need reverting.

Correction — task 0.2 is wider than an earlier draft claimed. That draft argued the refactor was "narrow" because _build_merged_hull and _build_movement_vfx "only add_child()". That is exactly the problem: they add_child() onto self, the RigidBody3D — ship.gd:208 (MergedHull: Hull, Canopy, EngineGlowL/R), :241 (engine cores), :268 (flames), :278 (lights). Leave those and §4.4's soft correct offsets only Nose and TailFin while the hull, canopy, glows, flames and lights stay welded to the corrected collider — every correction visibly tears the ship in half. The old acceptance criterion ("looks identical in Free Play") passes either way, which is why the criterion is now a child-type assertion. ship.gd:218's controller add_child correctly stays on the body; CollisionShape3D stays on the body.

Still true from that draft, and re-verified: ship.gd:44-47 documents why Nose/TailFin remain separate MeshInstance3Ds, and the RL path is untouched — ship_observations.gd reads only global_position, basis, velocities and PhysicsServer3D contacts, and training_mode.gd's only get_node is arena.get_node("Boundary").

Phase gate: the game plays identically to master in Free Play, Match, Spectate, and headless Training, with Engine.time_scale never written — and additionally: §5.5 contains a real measured frame-time table (0.15b), the Low preset roughly doubles the frame rate of High (0.17), and the game looks correct uncapped on a high-refresh display with no 60 Hz stepping in FOV, shake or post-process.

Phase 1 — Transport, connection, lobby

#	Task	Acceptance
1.0	DONE, two real bugs found and fixed after adversarial review. tests/test_runner.tscn + test_runner.gd: discovers every *.gd under tests/cases/, instances it, calls every test_*() method via get_method_list(), aggregates failures, get_tree().quit(1 if failed else 0). tests/test_case.gd is the assertion base (assert_true/assert_eq/assert_almost_eq); case scripts use extends "res://tests/test_case.gd" (path-based) and the runner uses preload(), not a bare class_name reference — the global script-class cache isn't guaranteed populated on a fresh headless run (same class of issue as task 0.18's SimConstants). tests/cases/test_smoke.gd proves discovery/dispatch/aggregation and is the first real case file. An Opus subagent's adversarial review found: (1) GDScript has no exceptions, so a test that hit a runtime error before its first assert_* call left failures empty — exactly like every assertion passing — and was silently counted as a PASS. Fixed: TestCase now tracks assertions_made, incremented by every assert_*; the runner treats zero assertions as a failure in its own right ("made no assertions"). (2) A case file with a parse/compile error hung the whole runner forever — load() on a broken script does not return null here, it returns a non-null but uninstantiable GDScript resource, so a plain null check doesn't catch it; calling .new() on it threw an error severe enough to abort _ready() before ever reaching quit(). Fixed with Script.can_instantiate() as the real guard	godot --headless --path Game res://tests/test_runner.tscn runs and exits 0; verified exit 1 with a deliberately-failing assertion, then removed. Re-verified both fixes with scratch case files (not committed): a test that null-derefs before asserting now correctly fails with "made no assertions" (exit 1, not a false pass); an uncompilable case file now fails loudly and promptly (exit 1, not a 124-timeout hang) while the other valid case files in the same run still execute normally
1.1 [D:1.0] [D:0.18]	DONE. scripts/net_codec.gd: protocol constants, PacketType enum, channel ids, i16/i8/thrust-z-bin quantisers, pack_input/unpack_input, pack_snapshot_body_segment/pack_snapshot_client_header/pack_snapshot/unpack_snapshot. New scripts/net_body_state.gd is the plain per-body data holder the snapshot functions read/write (not Ship/Ball themselves, so the codec stays callable with no scene tree). NetCodec.TICK_HZ derives from SimConstants.TICK_HZ via preload() (same cache-timing reason as 0.18); ring sizes / seq windows / INTERP_DELAY / timeouts don't exist as constants yet — they land with the tasks that consume them (3.1+), so "derives from TICK_HZ" is satisfied for what exists today	scripts/net_codec.gd, scripts/net_body_state.gd, tests/cases/test_net_codec.gd
1.2 [D:1.1]	DONE, strengthened after adversarial review. scripts/network_manager.gd autoload (NetworkManager in project.godot [autoload]): host(port, max_clients)/join(address, port)/shutdown(), client_connected/client_disconnected/connected_to_server/connection_failed/disconnected_from_server signals forwarded from multiplayer's own, server_relay = false set the moment a peer exists, is_server/is_client state. Gained a shutting_down() signal, emitted at the top of every shutdown() regardless of role or reason — see task 1.4's row for why	An Opus subagent's adversarial review (independently verified by the primary session before applying fixes) found the original tests/net_smoke.gd only proved each process exits cleanly on its own initiative, never that the OTHER peer actually observes the disconnect. Rewrote it: the host now waits for both client_connected and client_disconnected before passing; the client explicitly calls shutdown() mid-test (not just on process exit) and gives it a beat before quitting, same reasoning as §9 gotcha 26 for connects — a clean disconnect notice still needs a few poll() cycles to reach the wire, or the other side falls back to its ~5s peer timeout (gotcha 11) instead of a prompt one. Re-verified passing with both directions actually observed
1.3 [D:1.2]	DONE for what exists today. NetworkManager._ready() calls get_tree().set_multiplayer_poll_enabled(false) (Godot 4.7's actual method name — the doc's set_multiplayer_poll(false) was shorthand) and exposes NetworkManager.poll() as the one entry point every caller uses instead. Verified against tests/net_smoke.gd, updated to poll from both _process and _physics_process every frame — connect/disconnect still works cleanly under manual-only polling (§9 gotcha 26 still applies: give a beat after a connect signal before shutdown). The per-call-site placement this task specifies (client: end-of-physics-tick flush after input send, top-of-frame receive; server: tick-start drain, tick-end flush) has no real per-tick caller yet — there is no input/snapshot traffic until tasks 1.4+/Phase 2 exist to send any, so there's nothing to place a flush after. That placement, and the RTT/staleness measurement below, land with the input pipeline, not as a separate task	godot --headless two-process test still connects/disconnects cleanly with automatic polling off (verified). RTT/staleness improvement not yet measured — deferred until Phase 2/3's real per-tick traffic exists to measure against, same honesty as task 1.1's "constants that don't fully exist yet"
1.4 [D:1.2]	DONE. scripts/match_net.gd autoload (MatchNet): _hello/_welcome/_player_joined/_player_left/_rejected RPCs, protocol_version (NetCodec.PROTOCOL_VERSION) and physics_ticks_per_second (SimConstants.TICK_HZ) checked on the server before a peer is added to roster; on mismatch, server sends _rejected with a readable string then disconnect_peer()s after a 0.3s beat (§9 gotcha 26 applies here too — a bare RPC then immediate disconnect would drop the rejection message). roster: Dictionary[int, PlayerInfo] never contains peer 1 (§1.1 decision 2). A new peer is told about the existing roster via targeted RPCs before the broadcast that tells everyone (including itself) about the new peer, so no client ever observes an unexplained peer_id	Verified with a real two/three-process test (tests/match_net_smoke.gd/.tscn): matched client → both sides see player_joined/welcomed; deliberately wrong protocol version → client receives rejected("protocol version mismatch: server=1 client=100") and is disconnected. Caught and fixed one real bug in the process: the server's own roster update in _hello() didn't locally emit player_joined (the broadcast RPC is call_remote, never loops back to the sender)
—	Two more real bugs found by an Opus subagent's adversarial review, both confirmed independently and fixed. (1) _hello's player_name was completely unvalidated and broadcast verbatim to every peer — a demonstrated DoS: a multi-MB name relayed to all peers head-of-line-blocked the reliable control channel hard enough that a concurrently-joining client's own _welcome never arrived. Fixed with a hard MAX_INPUT_LENGTH = 256 reject (any legitimate client only ever sends local_player_name, which the UI already keeps short — anything past this is a bug or an attacker, not a name to politely truncate) followed by _sanitize_player_name(): strips control/formatting characters, clamps to MAX_PLAYER_NAME_LENGTH = 24, falls back to "Player" if empty. (2) MatchNet.roster was never cleared when a HOST stopped hosting — only the client-side disconnect path cleared it, so Host → Lobby → Leave → Host again left a phantom player in roster permanently, mis-balancing teams and getting broadcast to every future joiner. Fixed via NetworkManager's new shutting_down() signal (task 1.2), which MatchNet now clears roster on unconditionally, regardless of role or reason	_sanitize_player_name is static (pure function of its argument) with 5 dedicated unit tests in tests/cases/test_match_net.gd, plus a live rejection test (match_net_smoke.gd --role=client-longname, a 500 KB name, confirmed rejected before ever reaching a broadcast). New regression test match_net_smoke.gd --role=host_recycle: host, client joins (roster.size()==1), host leaves and re-hosts, confirms roster.is_empty() before any new connection — reproduced the bug pre-fix, confirmed fixed post-fix
1.5 [D:1.4]	DONE, strengthened after adversarial review. scenes/lobby.tscn + scripts/lobby.gd: roster split into two team columns (dynamically rebuilt Label rows on MatchNet.player_joined/player_left/player_state_changed/welcomed), Switch Team + Ready CheckButton (server process gets a read-only view — never a roster member, §1.1 decision 2), Leave. MatchNet grew team/ready fields on PlayerInfo, a balanced-team auto-assign on join (_pick_balanced_team), and request_set_team/request_set_ready + their server-authoritative RPCs, broadcasting _state_changed the same way _player_joined already did	Verified with a real two-process test (tests/lobby_smoke.gd/.tscn) that loads lobby.tscn via change_scene_to_file exactly as main_menu.gd's Host/Join flow (task 1.7) does, then presses the real %SwitchTeamButton/%ReadyButton nodes via a persistent test-only helper (tests/lobby_test_hooks.gd, not a project autoload — parented under get_tree().root so it survives the scene swap, never referenced by production code). An Opus subagent's adversarial review found the original test's host role never actually loaded lobby.tscn at all — it only hosted and waited, so lobby.gd's is_server branch (the read-only view a self-hosting player reaches via main_menu.gd's own Host button — a real, production-reachable path, not a hypothetical) had never run under this task's own suite. Fixed: the host role now loads lobby.tscn too and a new run_host_test() in the shared test helper verifies %ControlsRow is hidden, the roster row renders, and the status text is correct, holding the connection open long enough (MIN_HOST_LIFETIME_SECONDS) for the client's own longer flow to finish against it. Confirmed: roster renders correctly server- and client-side (now genuinely, not just asserted), team switch moves the row to the other column, ready toggle updates the checkbox and the label's ✓ marker, row count matches roster size on both peers
1.6 [D:1.4] [P]	DONE. scenes/server_boot.tscn + scripts/server_boot.gd: --port=/--max-clients=/--log-level= from OS.get_cmdline_user_args(), Engine.max_fps = 60, structured [elapsed] LEVEL event key=value… log lines for server_started/peer_connected/player_joined/player_left/peer_disconnected, and a physics-overrun watchdog comparing Engine.get_physics_frames() deltas frame-to-frame. Does not spawn a match yet — that's Phase 2's networked_match.gd — this is just the process shell: listen, log, idle cheaply. Two real bugs caught and fixed while verifying, both in the watchdog: (1) the very first _process() after boot compared against a pre-_ready() baseline and logged a spurious one-time steps=5; skip the first measurement. (2) the initial steps > 1 threshold fired continuously (every 30–100ms) on a perfectly idle, healthy server — because §9 gotcha 6 means frames legitimately alternate between 0 and 2 physics ticks under physics_jitter_fix = 0.0, not a flat 1/frame; that's quantisation, not backlog. Raised the threshold to steps > 2 (3+ ticks = the accumulator actually failing to drain), which produced zero false positives over a 4.8s idle run	Verified with real headless runs: idle CPU measured via ps -o %cpu at 0.0% (bar is <5%); a real client connect/disconnect via tests/net_smoke.gd --port= produces exactly the expected 4-line log sequence with no spurious warnings
1.7 [D:1.5] [P]	DONE. main_menu.tscn gained a Multiplayer section (Host button; Join row with an IP LineEdit, default 127.0.0.1; inline error label) and a full-screen ConnectingOverlay (status label + Cancel). main_menu.gd: _on_host_pressed calls NetworkManager.host() then goes straight to lobby.tscn (synchronous — no overlay needed); _start_join calls NetworkManager.join(), shows the overlay, and starts an app-level CONNECT_TIMEOUT_SECONDS = 6.0 timer; _on_connected_to_server/_on_connection_failed/Cancel/timeout each resolve to the overlay hiding and either lobby.tscn or a visible error, gated by a token counter so a late/stray signal after the attempt was already resolved is a no-op	Verified with real multi-process runs of scenes/main_menu.tscn itself (not a wrapper — driven by a temporary-autoload test helper, tests/main_menu_test_hooks.gd, pressing the real HostButton/JoinButton/ConnectingCancelButton) across all four paths: Host → lobby.tscn; Join → connects → lobby.tscn; Join with nothing listening → times out → error shown, stays on menu; Join → Cancel → overlay hidden, stays on menu, is_client false. Two real bugs found and fixed in the process, both pre-existing from earlier Phase 1 tasks, not new to 1.7: (1) NetworkManager's clock ping (task 1.8) gated only on is_client, which turns true the instant join() is called — a slow or refused connect attempt spammed "Trying to call an RPC via a multiplayer peer which is not connected" every frame; fixed by also requiring _peer.get_connection_status() == CONNECTION_CONNECTED. (2) ENet's own connection_failed proved unbounded in practice — verified empirically against a genuinely refused loopback connection, it hadn't fired even 14s in — which would have left a player staring at "Connecting…" indefinitely; task 1.7's own CONNECT_TIMEOUT_SECONDS is what actually satisfies "connection-refused reaches a sane UI state", not the built-in signal alone
1.8 [D:1.2] [P]	DONE, strengthened after adversarial review. Folded into network_manager.gd: client pings the server once a second (_ping/_pong RPCs, reliable, channel 0); clock_offset_ms is the min-RTT sample in a rolling 5s window (_clock_samples, pruned by wall time); get_server_time_estimate_ms() is the public API later phases (INTERP_DELAY, tick_offset seeding) will actually call; clock_updated(rtt_ms, offset_ms) signal for observers. New scripts/net_debug_overlay.gd autoload (F4, toggle_net_overlay input action) mirrors perf_overlay.gd's headless-guarded pattern, shows RTT + offset client-side or peer count server-side	Verified with a real two-process test (tests/clock_smoke.gd/.tscn) on localhost: first sample at t=0.95s, offset converged to 1534.50ms by t=2.0s (well inside the 2s bar), and stayed within 1.5ms of that value through t=3.96s — comfortably under the ±1 tick (16.67ms) bar. An Opus subagent's adversarial review correctly pointed out this self-consistency check couldn't have caught a systematically-wrong-but-stable offset (e.g. a missing /2 on RTT, or a sign flip — it would converge just as cleanly). Fixed by adding an independent ground-truth cross-check: both host and client compute Time.get_unix_time_from_system()*1000.0 - Time.get_ticks_msec() (each process's own offset from the shared OS wall clock — the same real clock on both, since they're on the same machine), exchanged via a shared temp file written by the host, purely for test orchestration and touching no production code. The true required offset is just the difference of those two numbers; re-run measured the converged offset against it and found 0.99ms of error, comfortably inside a deliberately loose 250ms tolerance (OS wall-clock read resolution and sampling-instant skew, not NetworkManager's own precision, is what sets the tolerance floor here). Note the converged offset value itself is large and arbitrary (~1.5s) because Time.get_ticks_msec() counts from each process's own start, not a shared epoch — expected, and exactly what clock_offset_ms exists to absorb

main_menu.gd gains its first async flow. Every existing handler is GameSettings.x = y; change_scene_to_file(...) — there is no loading screen, no error state, and no back-navigation state machine to extend. Budget for that.

Phase gate: two clients connect to a headless server, appear in a shared lobby, ready up, and disconnect cleanly.

Phase 2 — Server-authoritative simulation, dumb client

No own-ship prediction yet: the client renders everything, including its own ship, from the interpolation buffer. Unplayable over the internet, fine on LAN, and it proves the whole state pipeline before prediction complicates the picture.

This phase is load-bearing, not throwaway — the codec, slot mapping, snapshot pipeline, interpolator and HUD signal surface all survive into Phase 4. Roughly ten lines get discarded.

#	Task	Acceptance
2.1 [D:1.4]	DONE. New MatchSim autoload (scripts/match_sim.gd) carries all Phase 2 hot-path RPCs (match_config, input, snapshot, score_update) per §1.1's "hot RPCs live on autoloads" decision — NetworkedMatch itself (scripts/networked_match.gd + scenes/networked_match.tscn, no HUD child) stays a plain scene node with no networking identity of its own. Server builds deterministic team/spawn-index slots by iterating MatchNet.roster.keys() sorted, loads a random arena via ArenaRegistry.random_path(), spawns ball/ships, then send_match_config()s. Client validates the received arena_path against ArenaRegistry.ARENAS before loading it	Both peers spawn an identical tree in real two-process runs (tests/networked_match_smoke.gd/.tscn); an invalid arena path is refused before load
2.2 [D:2.1]	DONE. Server reuses RLShipController as the remote-input controller exactly as the architecture doc anticipated — each connected peer's real Ship is driven by one, fed by MatchSim.input_received. _broadcast_snapshot() runs every physics tick (60 Hz), packing NetBodyState for every ship + ball via NetCodec.pack_snapshot_body_segment and sending per-slot, filtered through multiplayer.get_peers() so a disconnected peer doesn't get an RPC send attempt	Server-side snapshot cadence confirmed stable at 60 Hz across multiple two-process runs; no "unknown peer ID" spam after the get_peers() filter fix (found via a real disconnect-mid-test case)
2.3 [D:2.2]	DONE. New scripts/net_interpolator.gd (class_name NetInterpolator, RefCounted) buffers up to MAX_SAMPLES=16 timestamped NetBodyStates per remote body and produces interpolated (or clamped-extrapolated, MAX_EXTRAPOLATION_MS=150) states at any fractional server tick via sample_at(). Client-side _on_snapshot_received feeds each body's decoded state into its interpolator; ships/ball spawn FREEZE_MODE_KINEMATIC so they never call _integrate_forces/get_action()	Client observed 31.43 m of real, physics-verified movement over a 2s held-thrust drive purely from interpolated snapshots, no local simulation
2.4 [D:2.3]	DONE — dual-time remote entities (§4.1). Collider updates happen in _physics_process at server_time_est (present-time, correct contact resolution); $Visual updates happen separately in _process at server_time_est - INTERP_DELAY (physics_interpolation_mode = OFF, since the node's transform is overwritten every rendered frame). _current_interp_delay_ms() computes a simplified INTERP_DELAY (one_way + interval*1.5, clamped [25,200] ms) — no jitter term yet, that lands with Phase 3's jitter buffer	Verified via the smoke test's separate collider/visual checks; Engine.get_physics_frames()/Time.get_ticks_msec() epoch correlation (NetInterpolator.to_tick()) confirmed working with no extra sync handshake needed
2.5 [D:2.3] [P]	DONE. _send_local_input() samples via a stateless, never-added-to-tree PlayerShipController instance (reading real Input state) and sends the resulting ShipAction every physics tick, no redundancy/buffering yet (Phase 3)	Input reaches the server and visibly moves the ship — confirmed via a real held move_forward keypress driving 31.43 m of server-authoritative movement
2.6 [D:2.3] [P]	DONE, and empirically verified, not just inferred — turned out to already be satisfied as a natural consequence of 2.1–2.5's implementation (_apply_ship_visual_state already calls set_visual_action for remote ships; _process's ball branch already calls set_visual_speed)	Smoke test explicitly reads interpolator.latest().thrust_z mid-drive and asserts >0.5 while move_forward is held (not inferred from movement alone) — measured thrust_z=1.00
2.7 [D:2.3] [P]	DONE, also a natural consequence of the above — spawn_camera_rig(_my_slot.ship) and _spawn_hud() are called once the client's own ship is identified in _on_match_config_received	Smoke test asserts _camera_rig and hud both is_instance_valid() on the client; confirmed true in every clean run
2.8 [D:1.1] [P]	DONE. New NetSim autoload (scripts/net_sim.gd): seeded (--net-sim-seed=, fixed default so a bad run reproduces), CLI-driven (--net-sim-latency=/--net-sim-jitter=/--net-sim-loss=/--net-sim-dup=), a pure passthrough (send() calls the dispatch immediately) unless at least one flag is non-zero — confirmed byte-for-byte inert against every Phase 1/2 regression test with no flags set. Wraps MatchSim.send_input/send_snapshot per this row's original scope, plus NetworkManager's _ping/_pong dispatch — a deliberate scope addition, since that's the only RTT measurement that already exists and is already tested (task 1.8), so it's what makes this task's own acceptance criterion checkable today without waiting on Phase 3's per-peer snapshot echo. "Asymmetric-capable" needs no special-case code: each process reads only its own CLI args and delays only its own outgoing sends, so hosting and joining with different flags is already asymmetric. One correctness subtlety, caught before it shipped: callers that embed a timestamp in a wrapped RPC (_ping/_pong) must capture Time.get_ticks_msec() before calling NetSim.send(), not inside the wrapped Callable — capturing it inside would silently absorb that process's own added delay out of the round-trip measurement instead of adding to it, since the timestamp would then reflect "after my delay" rather than "when I actually tried to send". A second real bug, found by actually running Phase 2's own milestone gate (a full networked_match_smoke run under --net-sim-latency=80 --net-sim-jitter=20, not just the isolated ping/pong test above): a delayed send can outlive the window its target was valid in — the host hit "Attempt to call RPC with unknown peer ID" (the client had disconnected during the ~80-100ms hold, after _broadcast_snapshot's existing get_peers() filter had already passed at schedule time) and the client hit "'_recv_input' on yourself is not allowed by selected mode" (its own shutdown() had already reset multiplayer_peer to a fresh OfflineMultiplayerPeer before a still-pending delayed send fired, so peer id 1 now meant itself). Fixed by having send() accept an optional target_peer_id and re-validating it — plus that this process still has a real (non-Offline) peer at all — at fire time inside a new _fire(), not just at schedule time; the synchronous/inactive path is deliberately left unvalidated so NetSim stays a true no-op when idle	Verified with a real two-process test (tests/net_sim_smoke.gd/.tscn): baseline (no flags) observed rtt_ms=7.00 on loopback; --net-sim-latency=80 on the host alone raised the client's observed rtt_ms to 83.00 (want ≥70, confirmed measurably higher than baseline); --net-sim-loss=1.0 on the host produced zero pong samples over 7s (rtt_ms stayed -1, confirmed the drop path actually drops rather than relabels). Phase 2's own milestone gate re-run and passing: networked_match_smoke under --net-sim-latency=80 --net-sim-jitter=20 on both peers — client still observed 26.08m of clean server-authoritative movement via interpolation, thrust_z=1.00 confirmed mid-drive, zero RPC errors (the fire-time-revalidation fix above). Re-ran the full Phase 1 + Phase 2 regression suite (test_runner, net_smoke, match_net_smoke, clock_smoke, lobby_smoke, server_boot, networked_match_smoke) with NetSim present but inactive — all still pass with unchanged behaviour (clock offset converged to the same value, networked_match_smoke still showed clean server-authoritative movement)

net_sim.gd belongs in this phase, not Phase 3. A LAN-only phase gate passes even with §4.1's flaw fully present, because LAN INTERP_DELAY sits at the clamp floor and closing-speed error is small. Phases 2 and 3 would both go green and Phase 4 would discover the architecture is wrong.

Phase gate — MILESTONE: a real 1v1 at --net-sim-latency 80 --net-sim-jitter 20, not just on LAN. Ships fly, the ball moves, goals detect server-side.

Phase 3 — Input pipeline hardening

#	Task	Acceptance
3.1 [D:2.5]	Input redundancy (last 4) and sequence numbering in server-tick space	A 3-packet burst loss produces no starvation
3.2 [D:3.1]	Server jitter buffer: fixed 32-entry ring, repeat-last on starve, zero after 500 ms, target_depth = 1, depth reported in every snapshot	Starvation events logged and visible in the overlay
3.3 [D:3.2] [P]	Client-owned input_lead control loop: fast attack (+3 immediate), slow release (−1 per 60 ticks after 2 s clean)	A simulated 60 ms latency spike is absorbed within ~200 ms
3.4 [D:3.1] [P]	Rate limiting, malformed-packet counting, seq > server_tick + 20 rejection, server-side input_lead enforcement from arrival times, disconnect policy	A flooding or seq-poisoning client is disconnected; honest clients unaffected
3.5 [D:3.2] [P]	Unit tests: jitter-buffer policy against scripted arrival traces	Starvation, surplus, and reorder traces all produce the specified actions
3.6 [D:2.8]	--test-bot client mode driven by the existing AIShipController, plus a CI driver launching a headless server and two headless test-bot clients	Exits 0 on a clean run; asserts snapshot count, p95/p99 prediction error, snap count, cross-peer score agreement, and clean stderr
3.7 [D:2.8] [P]	Debug net overlay: RTT, jitter, loss, buffer depth, snapshot age, bandwidth, prediction error	All values live and plausible

AIShipController runs a policy in pure GDScript with no Python or ONNX dependency, so 3.6 gets a competent automated player for free.

Phase gate: the match stays smooth at --net-sim-latency 80 --net-sim-loss 0.05; the CI smoke test is green.

Phase 4 — Prediction and reconciliation, ship and ball

#	Task	Acceptance
4.1 [D:3.1]	LocalNetShipController: single sample per tick, copy(), input history ring	Exactly one get_action() per tick; no aliasing in the history
4.2 [D:4.1]	Prediction state ring (128) and snapshot→predicted[A] matching	predicted[A] resolves for every snapshot on a clean link
4.3 [D:4.2, 0.14]	net_ship_predictor.gd: snap-vs-blend decision, full-immediate velocity correction, teleport queue, reset_gen handling, ring backfill after a snap	A snap is never followed by an immediately-forced second snap
4.4 [D:4.3, 0.2]	Visual offset with _tick_scaled(0.88) decay, MAX_VISUAL_OFFSET = 0.4, reset_physics_interpolation() on body and $Visual	No mesh smear on snap; no visible offset beyond 0.4 m
4.5 [D:4.3] [P]	Catch-up by replaying stored ShipActions through the ship's own force formulas	No directional bias under sustained turbo; ship does not feel rubbery
4.6 [D:4.3]	Ball local prediction: dynamic locally from the tick your predicted ship contacts it for min(RTT, 250 ms); server ball applied to a shadow copy throughout; blend back over 150 ms, hard-snap past 3 m. Triggered by the existing Ship.ball_contact (ship.gd:115)	Your own touches register visually on contact, not ~RTT later; behind a setting
4.7 [D:4.4] [P]	Tuning pass with debug-menu sliders: snap thresholds, decay k, MAX_VISUAL_OFFSET, INTERP_DELAY	Values recorded in this document once settled
4.8 [D:4.4] [P]	Prediction-error telemetry (p50/p95/p99, snap rate) into the overlay and the CI assertions	Snap rate <1/min in normal 1v1 play at 80 ms simulated RTT
4.9 [D:4.4]	L1 — extrapolate remote $Visual to present time (§5.6): render remote ships and the ball at server_time_est rather than server_time_est - INTERP_DELAY, feeding the residual through 4.4's soft-correct pipeline. Collapses §4.1's dual clock — collider and visual share one time, so §5.4b's _process/_physics_process split for remote bodies is removed. Keep interpolation behind a flag for A/B	≈30 ms off world response (174 → ~144 before L4). Measured p99 extrapolation error < 0.3 m and < 5°; correction pops are visible on hard direction changes and nowhere else; A/B against the interpolated path is a deliberate, recorded judgement
4.10 [D:4.9] [P]	L3 — adaptive jitter-buffer depth: target 0 on links with jitter below a threshold, rising to 1+ under jitter, replacing §3.3's fixed target_depth = 1	≈8 ms off world response on clean links with no increase in starve rate; degrades to today's behaviour under --net-sim-jitter 20

Ball prediction is not optional and not Phase 8. With §4.1 in place the touch registers correctly on the server, but the ball still renders a third of a beat late — your ship visibly passes through it before it moves. In a game whose entire point is hitting a ball, that is the difference between "networked" and "broken", and it is the same machinery as own-ship prediction applied to one more body. Do it while the prediction code is warm. Buffering server ball state into a shadow copy (rather than discarding it) is what lets you measure disagreement continuously instead of discovering a 3 m error at window end.

Phase gate — MILESTONE: at simulated 100 ms RTT both the ship and the ball feel local; corrections are invisible in free flight and read as bumps on contact. World response measures ≤130 ms at 60 ms RTT (§5.6's L1 + L4 target), on whatever graphics settings the machine is running.

Phase 5 — Match lifecycle

#	Task	Acceptance
5.1 [D:2.1]	Server state machine, state_change broadcast, match_state snapshot byte	Clients follow every transition
5.2 [D:5.1]	Tick-derived clock replacing the Timer + _process polling; clock_state RPC; goal-time freeze as end_tick += (resume_tick - goal_tick)	Clocks agree across peers to within a tick; no float drift across 10 goals
5.3 [D:5.1]	kickoff RPC with broadcast transforms, freeze/unfreeze, reset_gen, countdown derived from server_tick, and the specified late-arrival behaviour	A kickoff delayed past resume_tick applies immediately without a negative countdown
5.4 [D:5.1]	goal_scored RPC; server-side pause window via _goal_pause_seconds() and _set_frozen() (never Engine.time_scale); client cinematic split from timing	Server reset no longer fires while clients are mid-celebration
5.5 [D:5.1] [P]	Full time, overtime, results, return-to-lobby; remove get_tree().paused	Clients keep sending inputs and processing snapshots throughout the results screen
5.6 [D:5.1] [P]	Disconnect → controller swap; 30 s identity-keyed slot reservation and reconnect; --fill-bots / --no-fill-bots; stalled flag and nameplate	A disconnect never despawns a ship; reconnect within 30 s restores the slot
5.7 [D:5.6]	Null MatchNet's controller reference in the same transaction as the swap, and is_instance_valid-guard every use	No freed-object access on repeated disconnect/reconnect
5.8 [D:5.1] [P]	Spectators and late join; spectator-safe HUDController path; camera target cycling	A spectator can watch a live match and cycle targets
5.9 [D:5.3] [P]	Server-only _respawn_escaped_bodies() with a reset_gen bump	Clients hard-snap on an escape respawn instead of fighting it
5.10 [D:5.1] [P]	Server replay log: append-only binary (tick, inputs received, snapshot sent)	A recorded match replays deterministically enough to reproduce a reported snap

Ship.set_controller (ship.gd:213-218) calls queue_free() on the outgoing controller. Task 5.7 exists because the takeover path in 5.6 otherwise leaves MatchNet holding a freed reference — the exact class of bug that surfaces as a random server crash weeks later.

Task 5.10 is the highest-value debuggability investment here. The packets are already flat bytes, so it is ~50 lines. Without it, "my ship snapped" is permanently unreproducible from a field report — the CI gate catches regressions, but it cannot debug a player's bad night.

Phase gate: a full 3v3 start-to-finish including a mid-match disconnect and a late joiner.

Phase 6 — Dedicated server productionisation

#	Task	Acceptance
6.1 [P]	Export preset (dedicated_server=true, custom_features="dedicated_server") and run/main_scene.dedicated_server, mirroring the existing run/main_scene.training mechanism	Preset builds
6.2 [D:6.1]	Verify the stripped export boots and scores a goal	Exported binary runs a full match headless
6.3 [P]	Full CLI surface plus a config-file fallback	--help documents every flag
6.4 [P]	Structured logging (join, leave, goal, kick, rate-limit, tick overrun) with --log-level	Logs are greppable and rotate sanely
6.5 [P]	Arena rotation between matches; --max-matches N drain-and-exit	Server cycles arenas and exits cleanly after N
6.6 [P]	systemd unit, Dockerfile, SERVER.md (ports, firewall, sizing per §1.4, and the SIGTERM caveat)	A third party can host from the docs alone
6.7 [D:3.6] [P]	CI builds the server export and runs the smoke test against the exported binary, not source	Green on a clean checkout

dedicated_server=true enables Godot's strip-visuals export mode, which replaces meshes and textures with placeholders per resource. Every relevant site is already headless-guarded — ship.gd:167, ball.gd:25, goal.gd, arena_boundary.gd — so the code should be safe. Verify it against a real stripped build anyway; this is the kind of thing that fails silently.

Docker/VPS is the primary v1 deployment path. Raw ENet self-hosting needs port forwarding, and SDR is Phase 7 — so Phases 1–6 ship something that works on LAN or a VPS and nowhere else. That is fine, but say it out loud rather than letting a player discover it.

Godot 4 gives GDScript no SIGTERM hook. SIGTERM/Ctrl-C kills the process immediately and clients see an ENet timeout (~5 s). Acceptable — but document it rather than letting it be discovered. --max-matches N under a process supervisor covers planned drains.

Rcon is deferred past v1. An authenticated remote command channel is a real security surface, and --max-matches plus a supervisor covers most of the need with none of it.

Phase gate: docker run a server, connect from another machine over the internet, play a full match.

Phase 7 — Steam transport, browser, identity

#	Task	Acceptance
7.1 [D:1.2]	GodotSteam integration and custom export templates — client and headless server	Both templates build and run
7.2 [D:7.1]	Extract a NetTransport boundary now, concretely, from two working implementations; add steam_transport.gd (SteamMultiplayerPeer, SDR, advertise() via ISteamGameServer)	Transport swap is one line in NetworkManager
7.3 [D:7.2] [P]	server_browser.tscn via ISteamMatchmakingServers	Internet, LAN, favourites and history lists all populate
7.4 [D:7.2] [P]	Auth tickets in hello → BeginAuthSession; Steam identity in the roster; persistent ban list	Ownership, VAC and ban state verified server-side
7.5 [D:7.2] [P]	Feature-gate every Steam call behind OS.has_feature("steam") and ClassDB.class_exists("SteamMultiplayerPeer"); verify the ENet path end to end	Non-Steam build is fully functional

The transport interface is written here, not in Phase 1. Eight virtual methods (begin_auth, advertise, get_identity, supports_server_browser…) designed against an API nobody on the project has used will be wrong. Write NetworkManager._make_peer() concretely in Phase 1 and extract the boundary once there are two real implementations. Locked decision 3 guarantees the ENet path is never deleted, so there is no migration risk in waiting.

GodotSteam requires custom engine builds and export templates — including for the headless server. That is the part people discover three weeks in. Budget for it.

---

8. What needs refactoring, not extending

#	Location	Why extension is insufficient
1	objects/ship.tscn, ship.gd:175-180, 189-208, 241-278	No node exists to carry a render-only offset — meshes hang directly off the RigidBody3D. Needs $Visual.
2	ship_camera.gd:115, 149, 150	Camera reads the body's transform, so it would jump the full correction error while the mesh smoothly lags.
3	match_mode.gd:36, 59-64, 76-82, 93-96, 107-109	The Timer + _process clock is frame-rate and time_scale coupled. Must become tick-derived. Five call sites.
4	match_mode.gd:162-171	get_tree().paused = true stops the client's own send loop and snapshot processing, and the return-to-lobby RPC lands in a tree that cannot act on it.
5	game_mode.gd:95-121, 171-194	Engine.time_scale is fundamentally incompatible with a shared tick clock — sequence numbers ride on Engine.get_physics_frames(), so a hit-stop at 0.06 starves the jitter buffer within a few frames. The effects must be reimplemented, not merely disabled.
6	game_mode.gd:85-92	_handle_goal_scored interleaves timing with presentation. On a headless server _play_goal_celebration returns synchronously, so the reset fires on the same frame as the goal — while clients are 1.6 s into a cinematic.
7	game_mode.gd:248-263	_jittered uses global RNG; _reset_body uses set_deferred. Both must become authoritative-broadcast plus a Jolt-correct teleport.
8	game_mode.gd:54-55, 284-285	Unconditional goal-signal connection (an interpolated ball entering a client's local Goal would score locally) and unconditional escape-respawn both write authoritative state on clients.
9	main_menu.gd (all handlers)	Every mode launch is a synchronous change_scene_to_file. Connecting is async and can fail — a genuinely new UI state, not another button.
10	HUDController.gd:41-46	Hard-requires a ship; spectators have none.
11	player_ship_controller.gd	Single reused ShipAction instance; buffering aliases every history entry.
12	ship_camera.gd:86 (whole rig)	Runs in _physics_process, so on a 240 Hz display the FOV kick (:182) and PostFX parameters (:186-187) step at 60 Hz — neither is a transform, so global physics interpolation does not cover them — and the shake noise (:200-212) loses its high-frequency character. Must become _process + get_global_transform_interpolated() (§5.4a, task 0.16).
13	video_settings.gd:14-16, settings_menu.gd	Persists AA, glow and brightness only — three values. The three genuinely expensive settings (SDFGI, SSIL, SSAO) and the five shadow-casting lights are unreachable, and neither vsync_mode nor max_fps is set anywhere. A player chasing 240 fps has exactly one lever: turn glow off. Needs a preset system, not another checkbox (§5.5, tasks 0.17/0.17b).
14	scenes/arena_base.tscn:18-50, 61-105	The Environment every arena inherits enables SDFGI + SSIL + SSAO + a 5-level glow pyramid simultaneously, with four shadow-casting OmniLight3Ds (24 cubemap faces/frame). Not tunable per-arena around a preset; the preset must gate the shared base (§5.5).
15	shaders/post_process.gdshader:4	hint_screen_texture forces a full-screen backbuffer copy every frame, not only during turbo — vignette_strength never reaches 0 (ship_camera.gd:187, 243). Either bake the static vignette into Environment.adjustment_* and hide PostProcess when chromatic_aberration is at rest, or drop the screen read for a plain gradient overlay and keep it only for the turbo chroma.
16	project.godot [display]	stretch/mode="viewport" + 1920×1080 base + aspect="expand" fixes the 3D render at ~1080p and blits. A 4K player cannot render native; a 1080p player cannot render lower. Blocks any render-scaling setting until decided (task 0.17c).

On Engine.time_scale: replace hit-stop and goal slow-mo with the camera-based effects in single-player as well (task 0.12), so there is one code path and one game feel to maintain rather than a networked variant that drifts away from the single-player one. ShipCameraRig already has _shake_strength, shake_decay, max_shake_offset and a PostFX ShaderMaterial to build on.

What does not need surgery: the ShipController seam, the Arena/GameMode split, code-driven spawning, group-based discovery, and the dumb Goal sensor all extend cleanly. CLAUDE.md's claim about the three load-bearing seams is accurate — they hold. rl_ship_controller.gd is already the remote-input controller (a public action field that something else writes, pulled each tick), so no new class is needed for it.

---

9. Godot 4.7 + Jolt gotchas

1. ENetMultiplayerPeer.server_relay defaults to true — clients can RPC each other through your server. Set it false.
2. MultiplayerAPI.poll() runs on the idle frame, so an rpc() from _physics_process waits up to a full frame — and Engine.max_fps = 60 on the server is what creates that delay on the return leg. Take manual control (task 1.3). ~16–33 ms of round-trip, for ~10 lines.
3. Jolt sleeps bodies. A ship corrected to near-zero velocity can sleep and then ignore state.linear_velocity writes. can_sleep = false on Ship and Ball.
4. Teleporting a rigid body: state.transform inside _integrate_forces is the only path with no frame of lag. set_deferred("global_transform", …) lands between frames and interacts badly with Jolt's sleep/wake ordering.
5. reset_physics_interpolation() is not automatic for state.transform writes (it is when you set global_transform directly). Call it explicitly, on the body and on $Visual.
6. physics_jitter_fix = 0.0 does not give you "a flat 60 Hz." You still get occasional 0-tick and 2-tick frames, because frame time is never exactly 16.667 ms. The real reason to set it to 0 is that you never want a tick's input delayed by the accumulator smoother. The send path must therefore transmit both ticks' actions on a 2-tick frame — redundancy-4 covers this, but only if you actually send both.
7. _integrate_forces is not called on frozen bodies, so remote ships never pull get_action() — hence set_visual_action. Use FREEZE_MODE_KINEMATIC, not STATIC, or contact velocity transfer breaks.
8. Never write linear_velocity to a frozen body — Godot/Jolt zeroes and holds it.
9. Engine.max_physics_steps_per_frame defaults to 8. If a server tick overruns 16.7 ms the accumulator backs up and the next frame runs multiple ticks, spiking CPU further. Log overruns (task 1.6).
10. ENet channel indices are offset by Godot's reserved system channels — verify the mapping empirically.
11. ENet peer timeout defaults to ~5 s. Tune via ENetPacketPeer.set_timeout() for faster drop detection.
12. Jolt is not bit-deterministic across platforms or across differing contact orderings. Never rely on it anywhere, including in "obviously safe" places like a client-side goal check.
13. dedicated_server=true exports strip visual resources. Verify against a real stripped build (task 6.2).
14. MTU: ENet fragments above ~1400 B. At 219 B/snapshot there is ~6× headroom; recheck if per-body cosmetic state is ever added.
15. RPC NodePath caching: the first rpc() to a node sends the full path, later calls send a cached int. Routing hot paths through autoloads warms the cache once at connect and never invalidates it on scene change.
16. Physics tick rate is 60 for v1 — and must never be a literal. Every policy in Game/bots/ is tick-coupled through ship.gd:450's _tick_scaled (defined at a 60 Hz reference) and ai_ship_controller.gd's reaction_ticks, so raising it toward Rocket League's 120 invalidates every trained model and halves server density. But it is the largest single latency term left (§5.4), so it will be revisited: derive everything from TICK_HZ (tasks 0.18, 1.1) so that day is a config change plus a retrain.
17. Node3D.get_global_transform_interpolated() is the only correct way to track a physics-interpolated body from _process. global_transform returns the last physics tick's pose, so a per-frame camera reading it chases a 60 Hz staircase. Per the engine docs the method "creates an interpolation pump… the first time it is called" — call it once before any reset_physics_interpolation() on that node, or the first hard snap streaks (§4.5).
18. Physics interpolation covers transforms only. camera.fov, shader parameters, light energy and anything else written from _physics_process steps at 60 Hz on a 240 Hz display. Either write them from _process or accept the stepping deliberately.
19. display/window/vsync_mode defaults to enabled (FIFO) and max_fps to uncapped. Neither is set in project.godot. FIFO present latency is 1.5–3 refresh intervals depending on swapchain image count (2 vs 3) and whether the present queue is full — §5's tables use the optimistic 1.5, which assumes the renderer is not GPU-bound. The model does not hold below refresh, where a missed vblank under strict FIFO halves the effective rate and roughly doubles present latency. Prefer Adaptive as the default, not Mailbox (§5.4). (Swapchain image count per platform needs empirical verification.)
20. Engine.max_fps is a throttle, not a frame pacer. It pads each frame with a post-frame sleep; it has no vblank phase lock. Caps that are not integer divisors of the refresh rate beat against scanout, and combining a cap with an active vsync paces worse than either alone (§5.4). Derive the offered caps from DisplayServer.screen_get_refresh_rate().
21. DisplayServer.window_get_vsync_mode() echoes your request, not the driver's grant. There is no GDScript API for the negotiated VkPresentModeKHR, so a UI cannot honestly report what was applied. Show a live fps readout instead and let the player infer it.
22. Engine.max_physics_steps_per_frame = 8 is a client problem too, not just a server one (gotcha 9). A client hitching to 20 fps runs 3 ticks per frame, and each of those frames also runs the per-frame camera rig and remote-visual sampling. Set it to 4 client-side (task 0.22). On a multi-tick frame the send path must transmit every tick's action (gotcha 6) — §4.3's _physics_process sampling does this naturally, but nothing else guarantees it.
23. hint_screen_texture forces a full-screen backbuffer copy on every frame the node is drawn, regardless of what the shader then does with it. Branching inside the shader saves taps, not the copy. Hide the node when the effect is at rest.
24. physics_jitter_fix matters less the higher the frame rate. Its purpose is smoothing when frame rate ≈ tick rate; at 240 fps against 60 Hz physics most frames run zero ticks and the accumulator is never near an edge. Gotcha 6's reasoning for setting it to 0.0 still holds, but do not expect a visible difference on a high-refresh machine — test that change at 60 fps.
25. MultiplayerAPI.multiplayer_peer's default value is an OfflineMultiplayerPeer sentinel, not null. Resetting it with multiplayer_peer = null (rather than a fresh OfflineMultiplayerPeer.new()) leaves the API in a state distinct from its own default and is a known source of "the server never sees peer_connected, get_peers() stays empty" bugs (godotengine/godot#81540) — confirmed the hard way while building task 1.2's NetworkManager.shutdown(). Always reset to a real OfflineMultiplayerPeer.
26. Don't tear down a peer the instant its own connect signal fires. connected_to_server (client-side) fires once the client's local view of the handshake completes, but the final ACK the server needs to consider its side complete may not have hit the wire yet — closing the peer or quitting the process in the same callback can drop it, and the other side then never sees peer_connected/connected_to_server at all, even though your own side looked successful. This isn't a corner case: it reproduced on every attempt until fixed, is easy to misdiagnose as a server-side bug (the server-side symptom — get_peers() staying empty — is identical to gotcha 25's), and cost significant debugging time before the actual cause (client-side premature teardown) was found. Give at least one frame — in practice tests/net_smoke.gd uses 0.3 s — between a fresh connect signal and calling shutdown()/quit(). Directly relevant to task 5.6's disconnect/reconnect controller swap and any CLI test client that connects, asserts, and exits quickly.
27. change_scene_to_file() must be called on (or from a descendant of) the actual get_tree().current_scene, and never synchronously from _ready(). Both failure modes were hit building task 1.5's lobby.tscn/tests/lobby_smoke.gd: (a) a test harness that instantiated lobby.tscn as a plain child of a driver node — rather than loading it as the real current scene, the way main_menu.gd's Host/Join flow will — caused lobby.gd's own (entirely correct, standard-pattern) change_scene_to_file(ScenePaths.MAIN_MENU) disconnect handler to hang the process completely on a real disconnect, with near-zero CPU (blocked, not spinning) and no error output; the fix was to load the scene the way production actually will, not to change the production code. (b) calling change_scene_to_file() (or add_child() on get_tree().root) synchronously from inside _ready() throws "Parent node is busy … Consider using .call_deferred()", because the tree is still mid-traversal adding the very node whose _ready() is running; main_menu.gd's real button-press handlers won't hit this (they run outside any _ready()), but anything that needs to trigger a scene change during its own initialization must .call_deferred() it.
28. ENetMultiplayerPeer's connection_failed signal is not bounded to anything a UI should make a player wait for. Verified empirically (task 1.7): against a genuinely refused loopback connection (nothing listening on the target port), connection_failed had still not fired 14 seconds in. Don't rely on it alone to end a "Connecting…" state — run your own app-level timeout (main_menu.gd's CONNECT_TIMEOUT_SECONDS = 6.0) that shuts the peer down and shows an error regardless of whether ENet ever gets around to reporting failure itself.
29. A MultiplayerPeer's "am I a client" flag (however you track it — NetworkManager.is_client here) turns true the instant join()/create_client() is called, not once the connection actually completes. Anything gated on that flag alone (task 1.8's clock ping, in network_manager.gd's _process) will try to rpc_id() on a peer that's still CONNECTING — or has already failed — during a slow or refused connect attempt, and Godot logs "Trying to call an RPC via a multiplayer peer which is not connected" every single frame until it resolves. Gate on the peer's actual get_connection_status() == MultiplayerPeer.CONNECTION_CONNECTED, not just the higher-level intent flag.
30. load() on a .gd file with a parse/compile error does not return null. Found via adversarial review of tests/test_runner.gd: it returns a non-null but uninstantiable GDScript resource, so if script == null silently fails to catch the failure — and the natural next line, script.new(), throws "Invalid call: Nonexistent function 'new'", severe enough to abort the entire calling function (not just that statement) without ever reaching whatever cleanup/exit code follows. In a loop over multiple files with no per-iteration error boundary, this reads as a hang: the loop that would have moved to the next file, and the code that would have called quit(), both never run. The real guard is Script.can_instantiate().
31. An @rpc method named _input collides with Node's built-in _input(event: InputEvent) virtual. Found building task 2.1's MatchSim autoload: naming the client→server input RPC _input(bytes: PackedByteArray) produced a parse error ("function signature doesn't match the parent") — and because this was on an autoload, the error broke the entire autoload from loading, cascading into unrelated failures across every scene that touched MatchSim at all, none of which mentioned RPCs or _input in their own error output. Renamed to _recv_input. General lesson: on an autoload especially, treat any bare virtual-sounding method name (_input, _process, _ready, _unhandled_input, …) as reserved regardless of what you intend it to do — a signature mismatch there doesn't fail locally, it fails the whole autoload.
32. Disabling automatic multiplayer polling (task 1.3) is global, not autoload-scoped — every scene that touches an RPC, not just NetworkManager-adjacent code, must call NetworkManager.poll() itself every frame it wants traffic to move. Building task 2.1–2.3, networked_match.gd's _physics_process/_process sent and listened for RPCs (MatchSim.request_match_config, send_input, snapshot RPCs) but never called poll() — nothing sent via rpc() in this scene ever reached the wire in either direction, silently, with no error in either process's log. Confirmed via debug prints: the client's request fired, but the host's handler print never appeared. The first (wrong) hypothesis was a startup race between the server's broadcast and the client's listener connecting — that fix (a request/response retry pattern, still worth keeping for the genuine late-join case) didn't resolve it alone. The real fix was adding NetworkManager.poll() at the top of both _physics_process and _process in the new scene. If a scene sends or receives RPCs and nothing arrives with no errors at all, check for a missing poll() before anything else.
33. A request/response fallback for a one-shot broadcast can double-deliver, and the receiving handler must be idempotent. Once gotcha 32's fix made polling actually work, _on_match_config_received ran twice per client — once from the server's original one-shot _match_config.rpc() broadcast (queued the whole time, since it had been sent before polling was fixed) and again from the request/response retry — producing two arenas, two ship sets, two HUDs (_slots.size() == 2 instead of 1). Any handler reachable via both an original broadcast and a "resend on request" path needs its own guard (here: if not _slots.is_empty(): return at the top) rather than assuming "only sent once" from the RPC design alone.
34. Anything that deliberately delays an RPC dispatch (task 2.8's net_sim.gd) must re-validate its target at fire time, not just at the moment it was scheduled. Found by actually running Phase 2's own gate (networked_match_smoke under --net-sim-latency=80 --net-sim-jitter=20), not the isolated ping/pong test alone: _broadcast_snapshot's existing get_peers() filter (gotcha from task 2.2's own fix) only proves the target was valid when the send was queued — a target that legitimately disconnects during the ~80–100ms hold produces "Attempt to call RPC with unknown peer ID" anyway, and if the delay outlives this process's own shutdown(), multiplayer_peer has already been reset to a fresh OfflineMultiplayerPeer (§9 gotcha re: never resetting to raw null), so a stale rpc_id(1, …) now means "call yourself" and Godot rejects it. Any deliberate-delay layer needs to re-check both "do I still have a real peer at all" and "is this specific target still in get_peers()" inside the delayed callback itself, immediately before dispatching — not reuse whatever validation the caller did before the delay was added.

---

10. Testing

Editor. Debug → Run Multiple Instances, 2–3 instances with per-instance args (-- --server, -- --connect 127.0.0.1:27015) and --position so windows don't stack.

CLI.

godot --headless --path Game res://scenes/server_boot.tscn -- --port 27015 --team-size 1 --auto-start
godot --path Game -- --connect 127.0.0.1:27015 --name Alice

CI smoke test (task 3.6). Headless server plus two headless --test-bot clients, driven by the existing AIShipController. Asserts:

• snapshots received ≥ N * snapshot_hz * 0.9
• own-ship prediction error p95 < 0.5 m, p99 < 2.0 m, hard-snap count < 3
• final score identical on the server and both clients
• no push_error emitted (scrape stderr)

Network conditions. net_sim.gd (task 2.8) is first-class: seeded so failures reproduce, works in CI, needs no display, and can be applied asymmetrically — which OS tools make painful. tc netem / Network Link Conditioner / clumsy for a pre-release realism pass only. A real remote host once per phase from Phase 4 onward is the only true test of the jitter buffer's adaptivity.

Unit tests (task 1.0). No test framework exists today, so keep it minimal — a scene that runs pure-function assertions and exits with a code. High-value targets, all zero-engine-state: codec quantise/dequantise round-trip and bounds; quaternion max error; snapshot pack→unpack identity; input packet framing; jitter-buffer policy against scripted arrival traces; ShipAction.copy() non-aliasing. These are exactly where a bug is invisible in play and catastrophic in aggregate.

---

11. Flagged, not solved

Low-latency present and graphics presets — now specified, see §5.4, §5.5 and tasks 0.17/0.17b. Left here as a pointer because they are the largest wins in the document per line of code changed, and they are video settings rather than netcode.

120 Hz simulation — deliberately deferred, not dismissed. §5.4 and §5.6 record what it would buy (≈21 ms of world response once L1 has taken the interpolation buffer out, plus ≈8 ms of own-ship feel — the difference between ≈127 ms and ≈107 ms), what it costs (a full bot retrain, half the server density, double the bandwidth), and the one rule that keeps the door open: TICK_HZ, never 60.

The latency gap to the reference has a plan but not yet a measurement. §5.2 lands at ≈174 ms as designed; §5.6 routes that to ≈127 ms (tasks 0.17d, 4.9) and ≈103 ms (tasks 4.10 plus 120 Hz simulation), against ~90–110 ms for the reference class at the same RTT. Every figure in §5.6 is arithmetic on the budget, not a measurement — task 4.9's acceptance criterion exists to make it one. Beyond that the residual is RTT, which is a server-siting problem (§6) rather than a code one and is worth more than every remaining code lever combined.

Audio. TODO.md records that there is none. set_visual_action / set_visual_speed (task 0.14) is precisely where remote-ship engine audio will hang, and "ball feel" (task 4.6) is half auditory. Design those hooks with that in mind rather than retrofitting.

Split-screen. Tracked separately in TODO.md; unrelated to this effort, though the camera-outside-the-ship structure that enables it is the same structure this plan relies on.