From 9d8a8080baeab241515e8441139a0fa080dfd3ab Mon Sep 17 00:00:00 2001 From: Josh Creek <8179928+jcreek@users.noreply.github.com> Date: Thu, 20 Aug 2026 13:32:16 +0100 Subject: [PATCH] feat(multiplayer): Phase 3 task 3.7 - debug net overlay extension Extends net_debug_overlay.gd (Phase 1's RTT/offset display) with the rest of task 3.7's list: jitter (new RFC3550-style EWMA in NetworkManager, computed from raw per-sample RTT before Phase 1's own min-filtering, since that filter is deliberately jitter-insensitive by design), input buffer depth and input_lead (both already tracked client-side for task 3.3), snapshot loss (a new EWMA in networked_match.gd over each received snapshot's own server_tick gap - snapshots go out at a steady one-tick cadence, so a gap is direct evidence of a drop or reorder), snapshot age (computed on demand from the same bias-corrected tick estimate the interpolator itself uses), and bandwidth (new rolling per-second byte counters in MatchSim, on the two 60Hz hot-path channels only). Prediction error is deliberately omitted with a comment explaining why: there's no client-side prediction to measure until Phase 4. Verified values are live and plausible, not just present, by calling get_net_debug_stats() directly in a real two-process test and checking the numbers make sense: bandwidth matched the wire format's own byte math almost exactly (measured ~2400 B/s sent against a computed 40B x 60Hz, ~3540 B/s received against 59B x 60Hz), and buffer depth/lead/loss all moved in the correct direction between a clean LAN run and one under simulated 60ms latency + 10% loss. Full regression suite re-run clean. --- Game/scripts/match_sim.gd | 36 +++++++++++++++++++++++++++++++ Game/scripts/net_debug_overlay.gd | 23 ++++++++++++++++++-- Game/scripts/network_manager.gd | 14 ++++++++++++ Game/scripts/networked_match.gd | 31 ++++++++++++++++++++++++++ 4 files changed, 102 insertions(+), 2 deletions(-) diff --git a/Game/scripts/match_sim.gd b/Game/scripts/match_sim.gd index 82b0f385..a4449e3d 100644 --- a/Game/scripts/match_sim.gd +++ b/Game/scripts/match_sim.gd @@ -52,10 +52,42 @@ class _PeerInputState: var _peer_input_state: Dictionary = {} # peer_id -> _PeerInputState, server only +# Bandwidth (task 3.7's debug overlay): only the two 60Hz hot-path channels +# (input, snapshot) — match_config/score_update are low-frequency control +# messages, not what §2's byte-budget analysis or a live overlay cares +# about. Rolling per-second counters, recomputed opportunistically on each +# send/receive rather than on a timer — nothing needs the rate outside of +# an on-demand overlay read anyway. +const BANDWIDTH_WINDOW_MS := 1000 +var bytes_sent_per_sec := 0.0 +var bytes_received_per_sec := 0.0 +var _sent_window_start_ms := 0 +var _sent_window_bytes := 0 +var _received_window_start_ms := 0 +var _received_window_bytes := 0 + func _ready() -> void: NetworkManager.client_disconnected.connect(func(peer_id: int) -> void: _peer_input_state.erase(peer_id)) + +func _track_sent(n: int) -> void: + var now := Time.get_ticks_msec() + if now - _sent_window_start_ms >= BANDWIDTH_WINDOW_MS: + bytes_sent_per_sec = _sent_window_bytes * 1000.0 / maxf(1.0, float(now - _sent_window_start_ms)) + _sent_window_start_ms = now + _sent_window_bytes = 0 + _sent_window_bytes += n + + +func _track_received(n: int) -> void: + var now := Time.get_ticks_msec() + if now - _received_window_start_ms >= BANDWIDTH_WINDOW_MS: + bytes_received_per_sec = _received_window_bytes * 1000.0 / maxf(1.0, float(now - _received_window_start_ms)) + _received_window_start_ms = now + _received_window_bytes = 0 + _received_window_bytes += n + # Server only: the last match_config actually sent, so a client whose own # scene load (and therefore its match_config_received listener) finishes # AFTER the server already broadcast can still get it — a one-shot @@ -80,12 +112,14 @@ func request_match_config() -> void: func send_input(bytes: PackedByteArray) -> void: + _track_sent(bytes.size()) # bytes is already fully packed (any timestamps it carries are already # fixed), so wrapping the dispatch itself is enough — task 2.8. NetSim.send(func() -> void: _recv_input.rpc_id(1, bytes), 1) func send_snapshot(peer_id: int, bytes: PackedByteArray) -> void: + _track_sent(bytes.size()) NetSim.send(func() -> void: _snapshot.rpc_id(peer_id, bytes), peer_id) @@ -113,6 +147,7 @@ func _request_match_config() -> void: func _recv_input(bytes: PackedByteArray) -> void: if not multiplayer.is_server(): return + _track_received(bytes.size()) var peer_id := multiplayer.get_remote_sender_id() var state: _PeerInputState = _peer_input_state.get(peer_id) @@ -173,6 +208,7 @@ func _disconnect_abusive_peer(peer_id: int, reason: String) -> void: @rpc("authority", "call_remote", "unreliable_ordered", 2) func _snapshot(bytes: PackedByteArray) -> void: + _track_received(bytes.size()) var decoded := NetCodec.unpack_snapshot(bytes) snapshot_received.emit(decoded) diff --git a/Game/scripts/net_debug_overlay.gd b/Game/scripts/net_debug_overlay.gd index 4f5718f8..da94569c 100644 --- a/Game/scripts/net_debug_overlay.gd +++ b/Game/scripts/net_debug_overlay.gd @@ -33,11 +33,30 @@ func _process(_delta: float) -> void: if not _label or not _label.visible: return if NetworkManager.is_server: - _label.text = "NET: server, %d peer(s)" % (MatchNet.roster.size()) + _label.text = "NET: server, %d peer(s) out %s in %s" % [ + MatchNet.roster.size(), _format_kbps(MatchSim.bytes_sent_per_sec), _format_kbps(MatchSim.bytes_received_per_sec), + ] elif NetworkManager.is_client: if NetworkManager.rtt_ms < 0.0: _label.text = "NET: client, connecting (no clock sample yet)" else: - _label.text = "NET: client RTT %.1fms clock offset %.1fms" % [NetworkManager.rtt_ms, NetworkManager.clock_offset_ms] + # task 3.7: RTT, jitter, loss, buffer depth, snapshot age, + # bandwidth all live here now. Prediction error is intentionally + # absent — there is no client-side prediction until Phase 4, so + # there is nothing honest to show for it yet. + var stats := {} + var game := get_tree().get_first_node_in_group("game") + if game and game.has_method("get_net_debug_stats"): + stats = game.get_net_debug_stats() + _label.text = "NET: client RTT %.1fms jitter %.1fms offset %.1fms\nbuf depth %s lead %s loss %.1f%% snap age %.1fms\nout %s in %s" % [ + NetworkManager.rtt_ms, NetworkManager.jitter_ms, NetworkManager.clock_offset_ms, + str(stats.get("input_buffer_depth", -1)), str(stats.get("input_lead", "-")), + stats.get("snapshot_loss_pct", 0.0), stats.get("snapshot_age_ms", 0.0), + _format_kbps(MatchSim.bytes_sent_per_sec), _format_kbps(MatchSim.bytes_received_per_sec), + ] else: _label.text = "NET: offline" + + +func _format_kbps(bytes_per_sec: float) -> String: + return "%.2f KB/s" % (bytes_per_sec / 1000.0) diff --git a/Game/scripts/network_manager.gd b/Game/scripts/network_manager.gd index 413c02ff..971f6703 100644 --- a/Game/scripts/network_manager.gd +++ b/Game/scripts/network_manager.gd @@ -71,6 +71,14 @@ var clock_offset_ms := 0.0 # add to a local Time.get_ticks_msec() reading to var _clock_samples: Array[Dictionary] = [] var _ping_accum_sec := 0.0 +# Jitter (task 3.7's debug overlay): RFC3550-style EWMA of the deviation +# between consecutive RAW (not min-filtered) RTT samples — rtt_ms itself is +# a min-RTT, deliberately insensitive to jitter by design (§4.7), so a +# separate, unfiltered running estimate is needed to actually see it. +const JITTER_EWMA_ALPHA := 1.0 / 16.0 # matches RFC3550's own smoothing factor +var jitter_ms := 0.0 +var _last_raw_rtt_ms := -1.0 + func _ready() -> void: get_tree().set_multiplayer_poll_enabled(false) @@ -162,6 +170,8 @@ func shutdown() -> void: clock_offset_ms = 0.0 _clock_samples.clear() _ping_accum_sec = 0.0 + jitter_ms = 0.0 + _last_raw_rtt_ms = -1.0 @rpc("any_peer", "call_remote", "reliable") @@ -192,6 +202,10 @@ func _pong(client_send_ms: int, server_now_ms: int) -> void: var now_ms := Time.get_ticks_msec() var sample_rtt := float(now_ms - client_send_ms) var sample_offset := float(server_now_ms) + sample_rtt / 2.0 - float(now_ms) + if _last_raw_rtt_ms >= 0.0: + var deviation := absf(sample_rtt - _last_raw_rtt_ms) + jitter_ms += (deviation - jitter_ms) * JITTER_EWMA_ALPHA + _last_raw_rtt_ms = sample_rtt _clock_samples.append({"t": now_ms, "rtt": sample_rtt, "offset": sample_offset}) var cutoff := now_ms - int(CLOCK_WINDOW_SEC * 1000.0) diff --git a/Game/scripts/networked_match.gd b/Game/scripts/networked_match.gd index 7195a2fe..93fc083e 100644 --- a/Game/scripts/networked_match.gd +++ b/Game/scripts/networked_match.gd @@ -91,6 +91,15 @@ var _input_history: Array[ShipAction] = [] var _last_received_snapshot_tick := 0 # client only: echoed back as ack_snapshot_tick var _input_lead_controller := InputLeadController.new() # client only (§3.3) var _last_known_input_buffer_depth := -1 # client only: -1 = no snapshot with this field yet +# Loss estimate (task 3.7's debug overlay), client only: snapshots go out +# at a steady one-tick cadence, so a server_tick that jumps by more than 1 +# since the last received one is direct evidence of a dropped or reordered +# snapshot on the unreliable channel. EWMA over each reception's own +# "missed / (missed + 1)" fraction rather than a flat drop-count, so it +# reads as a live percentage and decays naturally once loss stops. +const SNAPSHOT_LOSS_EWMA_ALPHA := 1.0 / 16.0 +var _snapshot_loss_ewma := 0.0 +var _expected_next_snapshot_tick := -1 # §3.1 step 4. Not 120: InputLeadController.LEAD_MAX is 12, so anything # claiming to be further ahead of the current server tick than this is # broken or hostile, not just an honest client running a legitimately fast @@ -405,6 +414,11 @@ func _on_snapshot_received(decoded: Dictionary) -> void: var server_tick: int = decoded["server_tick"] var reset_gen: int = decoded["reset_gen"] var bodies: Array = decoded["bodies"] + if _expected_next_snapshot_tick >= 0: + var missed := maxi(0, server_tick - _expected_next_snapshot_tick) + var sample := float(missed) / float(missed + 1) + _snapshot_loss_ewma += (sample - _snapshot_loss_ewma) * SNAPSHOT_LOSS_EWMA_ALPHA + _expected_next_snapshot_tick = server_tick + 1 _last_received_snapshot_tick = server_tick # Per-client header (§2.4): unlike the shared body segment, this is # genuinely this recipient's own — input_buffer_depth is THIS client's @@ -468,6 +482,23 @@ func _current_interp_delay_ms() -> float: return clampf(one_way + SNAPSHOT_INTERVAL_MS * 1.5, INTERP_DELAY_MIN_MS, INTERP_DELAY_MAX_MS) +# Client-only stats for task 3.7's debug overlay, discovered via the "game" +# group the same way HUDController finds this node — no direct reference +# needed, and the overlay degrades gracefully (has_method check) against +# any mode that doesn't implement this at all. +func get_net_debug_stats() -> Dictionary: + var snapshot_age_ms := 0.0 + if NetworkManager.rtt_ms >= 0.0: + var estimated_now_tick := _estimated_tick(NetworkManager.get_server_time_estimate_ms()) + snapshot_age_ms = (estimated_now_tick - float(_last_received_snapshot_tick)) * NetInterpolator.TICK_MS + return { + "input_buffer_depth": _last_known_input_buffer_depth, + "input_lead": _input_lead_controller.lead, + "snapshot_age_ms": snapshot_age_ms, + "snapshot_loss_pct": _snapshot_loss_ewma * 100.0, + } + + # Collider time: present-time estimate, applied once per physics tick. func _physics_process(_delta: float) -> void: # Automatic multiplayer polling is disabled project-wide (task 1.3) —