feat(multiplayer): Phase 4 prediction correctness + two input-death fixes

Closes Phase 4's outstanding action-sequence-correctness invariant, then
fixes two server-side bugs an adversarial review of that work uncovered.
Server simulation, bot observations, collision resources and tick rate are
unchanged: the server_physics_parity trace is byte-for-byte identical to
HEAD across 360 ticks including both ships' full observation vectors.

4.11 - prediction history filed under the ISSUING sequence

_send_local_input filed each post-step predicted state under the timeline's
estimate of the sequence the server would consume this tick, trailing
issuance by input_lead. The body had integrated the intent issued under
_input_seq, so predicted[S] held "state after the intent from now" while
the server's authority for S is "state after action(S)". They agree only
while the stick is still. Filing under _input_seq costs nothing: which
action the ship uses is decided in LocalNetShipController.get_action() and
is untouched.

Every prior Phase 4 gate held its input steady, and a steady input cannot
falsify a sequence label - the 60s runs honestly reported marker=0/3784.
New --exercise-input-transitions role toggles thrust every 6 ticks; it is
the only gate that can catch a label regression. Verified non-vacuous: the
old label fails it at 50%.

4.12 - issued-but-unsimulated sequences, and the release path

An attack (delta > 1) issues and sends several sequences for one local
physics step. Those gap sequences had no recorded prediction, so a server
ack of one reported missing_not_recorded - indistinguishable from ring
loss, costing a teleport and resync suppression several times a minute.
They are now recorded stateless via record_unsimulated() and answered with
a new "skip" decision mode. Free-flight hard snaps: 25/8/4 -> 0/0/0.

A release (delta == 0) re-recorded at the unchanged _input_seq, filing the
current intent under a sequence that went out carrying a different action;
LocalInputTimeline deliberately refuses to mutate an issued sequence, so
the ring contradicted the wire. Recording is now skipped on release ticks.

4.13 - two Phase 3 bugs silently killing player input

(a) InputJitterBuffer.consume() advanced last_applied_seq on every tick
including a starve. Since ingest() discards seq <= last_applied_seq, one
starve on a sequence the client had not sent yet stranded the stream one
ahead of arrivals permanently - both sides advancing in lockstep, every
honest packet discarded on arrival. The client's own input_lead release is
enough to trigger it, so input died for ~30 ticks roughly every 6.5s on a
clean LAN. Now only gives up on a sequence once strictly newer data proves
it lost. Silent-client stall and ring-overflow resync are unchanged.

(b) The seq-range guard bounded incoming seq against highest_ingested_seq,
which only advances inside ingest(), which that guard gates. After a ~2s
host hitch every packet was rejected forever with no diagnostic (600+
consecutive rejections reproduced via SIGSTOP). Third iteration of this
guard; each previous version bounded against a value only the accepted
path could advance. Adds an escape after 10 consecutive rejections, which
grants an attacker nothing the rate limiter does not already bound.

(c) The transitions gate reported PASS at 3.76% while input was completely
dead, because suppression stops _record_metrics - a worse outage yields
fewer samples and a LOWER rate. Now scales the required sample count with
run length and asserts the wire's server_stalled bit. Reverting both fixes
makes it fail at samples 292/600, server_stalled=true, input_lead=12.

Fixing (a) also explained a residual the review had already traced: 151 of
151 action-marker mismatches were the server repeating a stale action on a
starve, not a prediction defect. Marker is now 0.00% in all three
conditions (was 1.7-2.5%), and free-flight p99 improved to
0.141/0.168/0.154m from 0.170/0.176/0.184m.

Two pre-existing test defects fixed alongside: the ball gate asserted
RTT-masking on a link with no RTT (flaked 2 in 5; now asserted only at
rtt >= 20ms, 5/5 under latency), and the two-bot CI compared scores across
a 3-5s window (now polls the scores the server actually held; note
score_changed is emitted only on the client path).

QA: 72 unit tests; 60s free-flight at LAN/80+-20ms/5% loss; transition
gate in all three; 2.0s and 3.5s host-freeze recovery; ball contact x5;
two-bot CI x3; all three abuse roles; net/match_net/clock/lobby smokes.

Phase 4 sign-off still pending a human playtest at ~100ms RTT - the
milestone asks how it feels, which no gate here answers.
This commit is contained in:
Josh Creek
2026-08-21 09:17:19 +01:00
parent 3d3024ae8a
commit 75f485667b
70 changed files with 2212 additions and 272 deletions
+52 -3
View File
@@ -109,6 +109,9 @@ var _boundary: ArenaBoundary
var _pending_teleport: Transform3D
var _has_pending_teleport := false
var _pending_teleport_linear_velocity := Vector3.ZERO
var _pending_teleport_angular_velocity := Vector3.ZERO
var _pending_teleport_has_velocity := false
# Queues an authoritative teleport, applied at the top of the next
@@ -118,6 +121,18 @@ var _has_pending_teleport := false
func queue_teleport(to: Transform3D) -> void:
_pending_teleport = to
_has_pending_teleport = true
_pending_teleport_has_velocity = false
# Network hard snaps need the server velocity as their new starting point,
# unlike gameplay resets which deliberately zero it. Keep the write queued:
# Jolt only permits state mutation from _integrate_forces.
func queue_teleport_with_velocity(to: Transform3D, new_linear_velocity: Vector3, new_angular_velocity: Vector3) -> void:
_pending_teleport = to
_pending_teleport_linear_velocity = new_linear_velocity
_pending_teleport_angular_velocity = new_angular_velocity
_pending_teleport_has_velocity = true
_has_pending_teleport = true
# --- Netcode correction hooks (Phase 4; see multiplayer-todo.md §4.4) ---
@@ -133,7 +148,19 @@ var net_vel_correction := Vector3.ZERO
# visibly teleporting the mesh. Same decay convention as drag/righting
# torque (_tick_scaled) above.
var net_visual_offset := Vector3.ZERO
var net_visual_rotation_offset := Quaternion.IDENTITY
const NET_VISUAL_OFFSET_DECAY := 0.88
const MAX_VISUAL_OFFSET := 0.4
var net_prediction_contact_window := false # client telemetry only
var net_visual_offset_decay := NET_VISUAL_OFFSET_DECAY
var net_visual_offset_max := MAX_VISUAL_OFFSET
func set_network_visual_tuning(decay: float, max_offset: float) -> void:
# Called only by the local client debug overlay. Server/training ships keep
# the constants above and therefore retain their exact existing behavior.
net_visual_offset_decay = clampf(decay, 0.5, 0.99)
net_visual_offset_max = clampf(max_offset, 0.05, 2.0)
# Feeds thrust_z/turbo into the movement VFX for a ship with no local
@@ -144,6 +171,14 @@ func set_visual_action(thrust_z: float, turbo: bool) -> void:
_current_action.thrust.z = thrust_z
_current_action.turbo = turbo
# The local network sender reads this after this tick's _integrate_forces,
# rather than pulling PlayerShipController a second time. That preserves the
# one get_action() call per physics tick contract.
func get_current_action_copy() -> ShipAction:
return _current_action.copy()
# Instrument signals for efficient data distribution
signal speed_changed(speed: float)
signal attitude_changed(pitch: float, roll: float, yaw: float)
@@ -389,12 +424,20 @@ func _has_telemetry_listeners() -> bool:
func _integrate_forces(state):
# Reconciliation telemetry needs to distinguish genuine free flight from
# Jolt contact windows. This is read only by the locally predicted client;
# it never changes forces, actions, collision state, or server behavior.
if not multiplayer.is_server():
net_prediction_contact_window = state.get_contact_count() > 0
if _has_pending_teleport:
_has_pending_teleport = false
state.transform = _pending_teleport
state.linear_velocity = Vector3.ZERO
state.angular_velocity = Vector3.ZERO
state.linear_velocity = _pending_teleport_linear_velocity if _pending_teleport_has_velocity else Vector3.ZERO
state.angular_velocity = _pending_teleport_angular_velocity if _pending_teleport_has_velocity else Vector3.ZERO
_pending_teleport_has_velocity = false
reset_physics_interpolation()
if is_instance_valid(visual):
visual.reset_physics_interpolation()
# --- Netcode correction hook (Phase 4) --- guarded: both fields default
# to Vector3.ZERO and nothing writes them yet, so neither branch runs
@@ -403,10 +446,16 @@ func _integrate_forces(state):
state.linear_velocity += net_vel_correction
net_vel_correction = Vector3.ZERO
if net_visual_offset != Vector3.ZERO:
net_visual_offset *= _tick_scaled(NET_VISUAL_OFFSET_DECAY, state.step)
net_visual_offset = net_visual_offset.limit_length(net_visual_offset_max)
net_visual_offset *= _tick_scaled(net_visual_offset_decay, state.step)
if net_visual_offset.length_squared() < 0.0001:
net_visual_offset = Vector3.ZERO
visual.position = net_visual_offset
if net_visual_rotation_offset != Quaternion.IDENTITY:
net_visual_rotation_offset = net_visual_rotation_offset.slerp(Quaternion.IDENTITY, 1.0 - _tick_scaled(net_visual_offset_decay, state.step))
if absf(net_visual_rotation_offset.angle_to(Quaternion.IDENTITY)) < 0.001:
net_visual_rotation_offset = Quaternion.IDENTITY
visual.basis = Basis(net_visual_rotation_offset)
# One action per physics tick, pulled from the controller (deterministic)
_current_action = controller.get_action() if controller else _inert_action