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
+38 -4
View File
@@ -50,6 +50,7 @@ produce the same struct, so the simulation can't tell them apart.
| `buttons` | u16 | Bit flags: fire, aim, jump, crouch, sprint, reload, interact, build |
| `selection` | u8 | Active inventory slot or build piece |
| `material` | u8 | Active build material |
| `view_lag` | u8 | How far in the past the player was seeing everyone else, back from `tick`, in quarter ticks. 0 for bots and local play |
Clients stamp commands for the tick they predict, and each packet repeats recent
commands to survive loss. The server applies the command for each tick, or a neutral
@@ -61,7 +62,7 @@ frame, so turning right *decreases* yaw. Positive pitch looks up. `Movement` and
client's `CameraRig` both follow this, and a test checks that strafing right moves
towards the camera's screen-right.
The binary encoding is a fixed 14 bytes per command, little-endian, in the order of
The binary encoding is a fixed 15 bytes per command, little-endian, in the order of
the table above. See `src/sim/player_command.gd`. Decoding a truncated buffer returns
nothing, and out-of-range values are clamped, so bad input can't reach the simulation.
The player a command belongs to comes from its connection, never from the packet.
@@ -97,7 +98,7 @@ with the server. Reconciliation corrects any difference.
`CommandLog` (`src/server/`) holds a match's seed, its rules and every command the
server was given: the simulation tick it arrived on, the handle it came from and the
command's 14 bytes. `ServerLoop.submit()` is the one way commands get in, for people,
command's 15 bytes. `ServerLoop.submit()` is the one way commands get in, for people,
scripts and bots alike, so a recording server logs them all, accepted or not. On disk
it is a JSON header and the records compressed with Zstandard, about 0.6 MB for a
24-player match.
@@ -198,6 +199,39 @@ on channel 0, the match phase, index and seed, so the client can generate the is
Building changes will also travel on a reliable ordered event stream (N5), since a
dropped wall is a gameplay lie.
## Lag compensation
A client draws other players about 130 ms in the past, and its commands take the
trip to the server and wait their turn, so when the server fires a shot the target is
no longer where the shooter saw it: 8 ticks on at a 50 ms round trip, 12 at 200 ms.
Without help, nobody could hit a walking target.
So every command says how far back its player was seeing (`view_lag`), and the
simulation keeps where every player's body has been for the last
`Tuning.LAG_COMPENSATION_MAX_TICKS` (15 ticks, half a second) in `HitHistory`
(`src/sim/`). A hitscan shot is traced against other players where they were at the
moment the shooter saw, between ticks if need be, and against terrain, props and built
pieces as they are now. Projectiles fly in the server's present and aren't rewound.
The client claims only *when* it was looking and where it aimed. Whether that is a
hit is worked out by the server, from its own record. Three limits bound the claim:
- Never more than the cap back. A round trip much over 300 ms needs more than the
cap, and that shooter has to lead the target.
- Never the future: the lag can't be negative.
- Never earlier than a moment the same player has already claimed. A view only moves
forward, so nobody can fire at the present and the past by turns and keep whichever
hits.
Because the lag travels in the command, it is in the command log, and a replay
judges every shot exactly as the match did. `HitHistory` itself isn't in the state
hash: a replay rebuilds it from the same ticks.
Measured (`test/net/test_lag_compensation_link.gd`, simulated link, headless): a
client firing a signal revolver once a second at the middle of a target walking
across at 4 m/s, 25 m away, as drawn on its own screen. At 50, 100 and 200 ms round
trips, 41 of 41 shots hit; with the lag ignored, 0 of 41. At 500 ms, past the cap,
0 of 41.
## The client: prediction, reconciliation and interpolation
`ClientGame` (`src/net/`) is a client's side of a match. It works on packets, so it
@@ -253,9 +287,9 @@ the hand, which needs a real playtest.
| Path | Holds | May depend on |
|---|---|---|
| `src/sim/` | Tick loop, entities, RNG, commands, tide, combat, building | `src/sim/` only |
| `src/sim/` | Tick loop, entities, RNG, commands, tide, combat and its lag compensation, building | `src/sim/` only |
| `src/bots/` | Bot brains that produce `PlayerCommand`s | `src/sim/` |
| `src/net/` | Transport, snapshot encoding, the client's side of a match (prediction, interpolation), lag compensation | `src/sim/` |
| `src/net/` | Transport, snapshot encoding, the client's side of a match (prediction, interpolation) | `src/sim/` |
| `src/server/` | Headless and listening servers, joining the network to the match | `src/sim/`, `src/bots/`, `src/net/` |
| `src/client/` | World rendering, camera, input, effects | `src/sim/`, `src/net/` |
| `src/ui/` | HUD, menus, map | `src/sim/` (read only), `src/client/` |