CosmicClash/Game/scripts/input_lead_controller.gd

class_name InputLeadController
extends RefCounted

# Client-owned input_lead control loop (multiplayer-todo.md §3.3, task 3.3).
# Standalone RefCounted, same reason as input_jitter_buffer.gd — scene-free
# so it's directly unit-testable against scripted depth traces.
#
# §3.3's own rationale for why this is the CLIENT's job alone, not shared
# with any server-side adaptation: three control loops acting on one plant
# (buffer occupancy) with different time constants is a textbook
# oscillation, and on a jittery link it presents to the player as
# intermittent sticky controls that are nearly impossible to attribute.
# The server (InputJitterBuffer, §3.2) only ever reports input_buffer_depth
# — it does nothing adaptive with it.
#
# "Lead" is realized concretely as extra distance between this client's own
# outgoing sequence numbers and what the server has actually consumed:
# skipping a sequence number (jumping the client's own seq counter by more
# than 1 for one tick) buys the server one more tick of buffered depth
# before it would starve; duplicating one (not incrementing the seq counter
# for one tick — the same seq gets sent again) narrows that margin by one
# tick of latency. The server's own ring buffer doesn't need to know this
# happened: a skipped seq just means "the redundant copies of it never
# existed, it's an ordinary drop" (already handled), and a duplicated seq
# is a same-seq resend, already discarded harmlessly once consumed
# (InputJitterBuffer.ingest()'s "seq <= last_applied_seq" check).
#
# Fast attack, slow release — a symmetric ±1-per-N-ticks slew would take
# two full seconds to absorb a single wifi spike, during which the player
# steers and the ship does not turn, "the most rage-inducing failure mode
# in any netcode" per §3.3's own words.

const LEAD_MIN := 1
const LEAD_MAX := 12
# "Never change it more than once per 30 ticks" (§3.3) — the floor that
# binds the fast-attack side; slow-release's own 60-tick cadence already
# exceeds it, so this one constant covers both.
const MIN_CHANGE_INTERVAL_TICKS := 30
const RELEASE_INTERVAL_TICKS := 60
const CLEAN_SURPLUS_TICKS := 120   # 2s at 60Hz

var lead := LEAD_MIN

var _ticks_since_change := 0
var _clean_surplus_ticks := 0


# Call once per client physics tick with the most recently known server-
# reported input_buffer_depth for THIS client's own slot (echoed in every
# snapshot, §3.2) — or -1 if no snapshot carrying that field has arrived
# yet. Returns the seq delta the caller should add for this tick's
# outgoing packet: ordinarily 1 (ship normally increments its send
# sequence by exactly one tick's worth), or 1+N / 0 on a tick where a lead
# change actually fires (skip N extra / duplicate the current one).
func update(input_buffer_depth: int) -> int:
	_ticks_since_change += 1
	if input_buffer_depth < 0:
		return 1

	if input_buffer_depth <= 0:
		# A starve: the server's ring was empty for this player when it
		# built that snapshot. React immediately, not after 2 seconds of
		# evidence like release requires — but still debounced against
		# MIN_CHANGE_INTERVAL_TICKS so a burst of consecutive starve
		# reports doesn't compound into repeated, overlapping jumps.
		_clean_surplus_ticks = 0
		if _ticks_since_change >= MIN_CHANGE_INTERVAL_TICKS and lead < LEAD_MAX:
			var new_lead := mini(lead + 3, LEAD_MAX)
			var delta := new_lead - lead
			lead = new_lead
			_ticks_since_change = 0
			return 1 + delta
		return 1

	_clean_surplus_ticks += 1
	if _clean_surplus_ticks >= CLEAN_SURPLUS_TICKS and _ticks_since_change >= RELEASE_INTERVAL_TICKS and lead > LEAD_MIN:
		lead -= 1
		_ticks_since_change = 0
		return 0   # duplicate this tick's seq — one tick of latency recovered
	return 1