N3: Client prediction, reconciliation and interpolation

The client's side of a networked match, in src/net/:

- ClientGame takes the server's notices and snapshots, generates the island
  from the seed and answers with commands. It works on packets, so it runs
  over a NetClient or a test's simulated link.
- ClientClock decides which tick the next command is for, from the server's
  echo of the newest command tick it has received, holding three commands
  waiting at the server.
- ClientPrediction runs each command on a copy of the client's own player
  with the server's movement code, and compares every snapshot with what it
  predicted. A difference is replayed from the server's state and eased in.
- SnapshotInterpolator draws everyone else four ticks in the past, between
  snapshots, on a clock steered gently by arrivals.

Snapshots now carry the client's own block: exact position and velocity,
the water around the player, stamina and state flags, so a prediction can
match the server to the bit. The command echo is now the newest tick
received rather than taken. Protocol version 2.

Snapshots go out every second tick. The interval was three ticks, which is
10 a second, not the 20 the documents claimed; 15 a second is the nearest
even spacing and what interpolation is tuned for.

Drop.ride() holds the barge ride for the server and the client alike, and
NetGame's joining, input and snapshot steps can be called without a socket.

Measured in test/net/test_prediction_link.gd over a simulated link with
100 ms each way, 20 ms jitter and 2% loss: no corrections to own movement
in about 1,400 snapshots per client, and the other player drawn 0.4 mm on
average from where a perfect link would draw them.

Closes #34

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-12 11:30:00 -05:00
co-authored by Claude Opus 5.5
parent b4548d91f5
commit 4111a285f0
32 changed files with 1932 additions and 89 deletions
+60 -7
View File
@@ -33,8 +33,8 @@ Net ──┘ └─ UI / HUD
The simulation runs at `Tuning.TICK_RATE_HZ` (30 Hz, 33.33 ms). The server runs a fixed
accumulator and may run several ticks to catch up, with no more than 5 per frame.
Snapshots go out at 20 Hz. The client renders at any frame rate and interpolates
remote entities roughly 100 ms in the past.
Snapshots go out every second tick, 15 a second. The client renders at any frame rate,
predicts its own player and draws everyone else about 130 ms in the past.
## Player command stream
@@ -154,8 +154,9 @@ A snapshot is a binary, little-endian packet on channel 1, unreliable:
| Part | Contents |
|---|---|
| Header | Message type (u8), server tick (u32), baseline tick (u32, 0 = builds on nothing), simulation tick (u32), last command tick taken from this client (u32), the entity the client is watching (varint) |
| Header | Message type (u8), server tick (u32), baseline tick (u32, 0 = builds on nothing), simulation tick (u32), the newest command tick received from this client plus one (u32, 0 = none yet), the entity the client is watching (varint) |
| Match and tide | Match phase (u8), tide phase (u8), sea level in centimetres (s16) |
| Own block | A flag (u8), then, while the client's own player is alive and is who it watches, 37 bytes nobody else is sent: position and velocity as f32, the water level around the player as f64, which of the nine flood cells around the player that water reaches (u16), swimming stamina (u16) and state flags (u8) |
| Removed | Count (u8), then IDs (varint) |
| Entities | Count (u16), then records of ID (varint), archetype and changed-group mask (u8), then only the groups that changed |
@@ -180,15 +181,16 @@ items on the ground within `NET_INTEREST_PICKUPS_METRES` (90 m), measured on the
An entity that leaves range is removed from the client's picture and nothing more is
said about it. Outside a match there is no viewer and a snapshot is only its header.
**Budget.** A snapshot is at most `Tuning.NET_SNAPSHOT_MAX_BYTES` (1,200), so 20 a
second is at most 24 KB/s before packet headers and never fragments. When more has
**Budget.** A snapshot is at most `Tuning.NET_SNAPSHOT_MAX_BYTES` (1,200), so 15 a
second is at most 18 KB/s before packet headers and never fragments. When more has
changed than fits, the client's own player goes first, then the nearest, and each
snapshot an update has waited counts as 6 m closer, so nothing waits for ever. What
didn't fit is still owed and goes in a later snapshot.
**Input.** The client answers on channel 1 with the snapshot tick it holds and its
last few commands (`Tuning.NET_INPUT_REDUNDANCY`), oldest first. `NetGame`
(`src/server/`) offers each tick's command to `ServerLoop.submit()` once.
(`src/server/`) offers each tick's command to `ServerLoop.submit()` once, and echoes
the newest tick it has received in every snapshot, taken or not.
**Match notice.** On joining and at every change of phase the server sends, reliably
on channel 0, the match phase, index and seed, so the client can generate the island.
@@ -196,13 +198,64 @@ 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.
## The client: prediction, reconciliation and interpolation
`ClientGame` (`src/net/`) is a client's side of a match. It works on packets, so it
runs the same over a `NetClient` or a test's simulated link. From the seed in the
MATCH notice it generates the island itself (a `Simulation` it never steps) and plans
the same barge route, so it can run the server's movement code on the server's ground.
**The command clock.** A command must reach the server before the tick it names, so
the client's tick runs ahead of the server's by the trip there plus a margin. Nobody
measures the trip. Each snapshot says which tick the server was about to run and the
newest command tick it had received; the difference is how many commands were
waiting. `ClientClock` holds that at `Tuning.NET_COMMAND_MARGIN_TICKS` (3): it jumps
ahead if commands arrive late two snapshots running, waits if they are far too early,
and otherwise runs up to 2% fast or slow. With three commands waiting and each packet
repeating the last three, jitter and a lost packet or two cost nothing.
**Prediction.** `ClientPrediction` keeps a copy of the client's own player and runs
every command on it as it is made, through `Movement.step`, `Water.update` and
`Drop.ride`, the same code the server runs. The player moves at once, not a round trip
later.
**Reconciliation.** The own block in each snapshot is the player's exact state before
the snapshot's simulation tick: 32-bit floats, as the server holds them, not the
quantized record. If that equals what was predicted before that tick, nothing happens,
which is the normal case. If not, the copy is put where the server says, every command
since is run again, and the distance the player's present position moved is the
correction. A correction is never shown at once: the drawn position keeps an offset
that fades at `NET_CORRECTION_SMOOTH_RATE`, unless it is over 3 m, which is shown as
the teleport it is. What the client can't predict yet: built pieces and broken props
(not replicated until N5), a basin still filling after a breach, and anything another
player does to it.
**Interpolation.** `SnapshotInterpolator` draws every other entity
`Tuning.NET_INTERP_DELAY_TICKS` (4 ticks, two snapshots) in the past, on a straight
line between the snapshots either side of that moment, with yaw turning the short way.
The moment drawn is a clock of its own, steered gently towards where arrivals say it
should be, so jitter in the network never becomes jitter on screen. When a snapshot is
lost the entity carries on along its last heading for up to 3 ticks; if that guess was
wrong, the difference is blended away when the news arrives.
**Measured** (`test/net/test_prediction_link.gd`, simulated link, headless): two
players through the drop and 75 s of walking, sprinting, strafing, jumping and
crouching on a real island, each with 100 ms of latency each way, 20 ms of jitter and
2% loss. Own movement: about 1,400 snapshots compared per client and none needed a
correction. The other player was drawn on average 0.4 mm from where a perfect link
would draw them, and 9 mm from where the server had them at that moment; a lost
snapshot during a sudden stop or start showed as at most 13 cm of drift, eased out. At
150 ms, 40 ms and 10% loss a client took 3 to 7 corrections of at most 22 cm, all
blended. These are measurements of the netcode's arithmetic, not of how it feels in
the hand, which needs a real playtest.
## Module map
| Path | Holds | May depend on |
|---|---|---|
| `src/sim/` | Tick loop, entities, RNG, commands, tide, combat, building | `src/sim/` only |
| `src/bots/` | Bot brains that produce `PlayerCommand`s | `src/sim/` |
| `src/net/` | Transport, snapshot encoding, prediction, lag compensation | `src/sim/` |
| `src/net/` | Transport, snapshot encoding, the client's side of a match (prediction, interpolation), lag compensation | `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/` |