N4: Lag-compensated hit validation

A network client draws other players in the past and its commands take time
to arrive, so by the time the server fires a shot the target has moved on:
8 ticks at a 50 ms round trip, 12 at 200 ms.

Each PlayerCommand now carries view_lag: how far back its player was seeing
everyone else, in quarter ticks. The simulation keeps where every player's
body has been for the last 15 ticks (HitHistory), and a hitscan shot is
traced against other players where they were at the moment the shooter saw,
and against the world as it is now. Projectiles aren't rewound.

The client claims only when it was looking and where it aimed; the server
works out the hit from its own record. The moment is never more than
Tuning.LAG_COMPENSATION_MAX_TICKS back, never in the future, and never
earlier than a moment the same player has already claimed.

Commands are 15 bytes, so the command log's version is 2. The lag is in the
log, and replays judge every shot as the match did.

Measured in test/net/test_lag_compensation_link.gd over a simulated link:
a client firing at a walking target as drawn on its own screen hits 41 of
41 shots at 50, 100 and 200 ms round trips, 0 of 41 with the lag ignored,
and 0 of 41 at 500 ms, past the cap.

Closes #35

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-12 11:45:23 -05:00
co-authored by Claude Opus 5.5
parent 4111a285f0
commit 5e1704e224
16 changed files with 510 additions and 15 deletions
+129
View File
@@ -0,0 +1,129 @@
extends TestCase
## Issue N4 end to end: a client aims at another player where it draws them, through a
## link with latency, and the server judges the shots.
##
## The shooter stands still with a signal revolver. The target walks back and forth
## across its view 25 m away at 4 m/s. Once a second the client fires at the middle of
## the target as its SnapshotInterpolator shows it. With the client's view_lag honoured
## the shots should land; with it ignored they should fall behind the target.
const HANDLE: int = 1
const SEED: int = 12
const TICK_MS: float = 1000.0 / Tuning.TICK_RATE_HZ
const FRAME_MS: float = 1000.0 / 60.0
const SHOOTER_FEET: Vector3 = Vector3(500.0, 0.0, 500.0)
const RANGE: float = 25.0
const SECONDS: int = 45
## Ticks the target walks each way.
const LEG_TICKS: int = 75
## Plays `SECONDS` of it with `one_way_ms` of latency in each direction. Returns
## {"shots", "hits", "lag": the mean view lag the client reported, in ticks}.
func _play(one_way_ms: float, compensate: bool) -> Dictionary:
var sim: Simulation = Simulation.new(SEED, SimGround.flat())
var shooter: SimEntity = sim.entities.find(sim.add_player())
shooter.position = SHOOTER_FEET
shooter.on_ground = true
var revolver: int = ItemCatalog.code_of("signal_revolver")
Inventory.give(shooter, revolver, 1)
Inventory.give(shooter, ItemCatalog.get_def(revolver).ammo_code, 200)
shooter.selected = 1
var target: SimEntity = sim.entities.find(sim.add_player())
target.position = SHOOTER_FEET + Vector3(-5.0, 0.0, RANGE)
target.on_ground = true
var sender: SnapshotSender = SnapshotSender.new()
sender.add_client(HANDLE)
var client: ClientGame = ClientGame.new()
client.make_world = func(match_seed: int) -> Simulation: return Simulation.new(match_seed, SimGround.flat())
client.receive(NetProtocol.CHANNEL_CONTROL, NetSnapshot.encode_match(Match.PLAY, 0, SEED))
client.sample_input = func(tick: int) -> PlayerCommand:
var shown: Dictionary = client.remote.sample(target.id)
if shown.is_empty():
return null
var eye: Vector3 = Harvest.eye(client.prediction.player)
var to: Vector3 = (shown["position"] as Vector3) + Vector3(0.0, 1.0, 0.0) - eye
var buttons: int = PlayerCommand.BUTTON_AIM
if tick % Tuning.TICK_RATE_HZ == 0 and tick > 3 * Tuning.TICK_RATE_HZ:
buttons |= PlayerCommand.BUTTON_FIRE
return PlayerCommand.from_input(tick, Vector2.ZERO, atan2(to.x, to.z), atan2(to.y, Vector2(to.x, to.z).length()), buttons, 1)
var down: LinkSim = LinkSim.new(one_way_ms, 5.0, 0.0, 31)
var up: LinkSim = LinkSim.new(one_way_ms, 5.0, 0.0, 32)
var shots: int = 0
var hits: int = 0
var lag_sum: float = 0.0
var lag_count: int = 0
var last_command: int = -1
var server_ticks: int = 0
var next_tick_ms: float = 0.0
var next_frame_ms: float = 5.0
var now: float = 0.0
while sim.tick < SECONDS * Tuning.TICK_RATE_HZ:
if now >= next_tick_ms:
next_tick_ms += TICK_MS
for bytes: PackedByteArray in up.receive(now):
var input: Dictionary = NetSnapshot.decode_input(bytes)
sender.acknowledge(HANDLE, int(input["ack"]))
for command: PlayerCommand in input["commands"]:
if command.tick <= last_command:
continue
last_command = command.tick
sender.note_command(HANDLE, command.tick)
lag_sum += float(command.view_lag) / PlayerCommand.VIEW_LAG_STEPS_PER_TICK
lag_count += 1
if not compensate:
command.view_lag = 0
sim.submit_command(shooter.id, command)
# Facing +z, right is -x.
var strafe: float = -1.0 if (sim.tick / LEG_TICKS) % 2 == 0 else 1.0
sim.submit_command(target.id, PlayerCommand.from_input(sim.tick, Vector2(strafe, 0.0), 0.0, 0.0))
sim.step()
server_ticks += 1
for event: Dictionary in sim.events:
if event["type"] == "shot" and event["player"] == shooter.id:
shots += 1
elif event["type"] == "player_hit" and event["victim"] == target.id:
hits += 1
target.health = Tuning.PLAYER_MAX_HEALTH
if shooter.slot_rounds[0] == 0:
shooter.slot_rounds[0] = 6
if server_ticks % Tuning.NET_SNAPSHOT_INTERVAL_TICKS == 0:
down.send(sender.build(HANDLE, sim, shooter.id, server_ticks, Match.PLAY, shooter.id), now)
if now >= next_frame_ms:
next_frame_ms += FRAME_MS
for bytes: PackedByteArray in down.receive(now):
client.receive(NetProtocol.CHANNEL_STATE, bytes)
client.advance(FRAME_MS / 1000.0)
for bytes: PackedByteArray in client.outbox:
up.send(bytes, now)
client.outbox.clear()
now += 1.0
var result: Dictionary = {"shots": shots, "hits": hits, "lag": lag_sum / maxi(lag_count, 1)}
# The sampler holds the client and the client holds the sampler: let both go.
client.sample_input = Callable()
print(" %3.0f ms round trip, view lag %s: %d of %d shots hit; the client drew the target %.1f ticks (%.0f ms) behind the tick its commands were for" % [
one_way_ms * 2.0, "honoured" if compensate else "ignored", hits, shots, result["lag"], float(result["lag"]) * TICK_MS,
])
return result
func test_shots_land_at_50_100_and_200_ms() -> void:
for round_trip: float in [50.0, 100.0, 200.0]:
var with: Dictionary = _play(round_trip * 0.5, true)
assert_true(with["shots"] >= 38, "%d shots fired" % with["shots"])
assert_true(with["hits"] >= with["shots"] - 1, "%.0f ms: %d of %d hit" % [round_trip, with["hits"], with["shots"]])
assert_true(with["lag"] <= Tuning.LAG_COMPENSATION_MAX_TICKS, "%.0f ms needs %.1f ticks of rewind, inside the cap" % [round_trip, with["lag"]])
# The same shots judged against the present fall behind a walking target.
var without: Dictionary = _play(round_trip * 0.5, false)
assert_true(without["hits"] <= without["shots"] / 4, "%.0f ms uncompensated: %d of %d hit" % [round_trip, without["hits"], without["shots"]])
func test_beyond_the_cap_the_shooter_has_to_lead() -> void:
# A 500 ms round trip needs more rewind than the server allows.
var result: Dictionary = _play(250.0, true)
assert_true(result["lag"] > Tuning.LAG_COMPENSATION_MAX_TICKS + 4.0, "needs %.1f ticks" % result["lag"])
assert_true(result["shots"] >= 38)
assert_true(result["hits"] <= result["shots"] / 4, "%d of %d hit" % [result["hits"], result["shots"]])
@@ -0,0 +1 @@
uid://bt1u386uvlyer