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
+89
View File
@@ -0,0 +1,89 @@
## Decides which tick a client's next command is for.
##
## Commands have to reach the server before the tick they name runs, so the client's
## tick runs ahead of the server's by the trip there plus a small margin. Nobody tells
## the client how long the trip is. Instead every snapshot echoes the newest command
## tick the server had received when it was built, next to the tick the server was on:
## the difference is how many commands were waiting. The clock holds that at
## Tuning.NET_COMMAND_MARGIN_TICKS. If commands arrive late two snapshots running it
## jumps ahead (once is more likely a burst of lost packets, which no clock can fix);
## if far too early it waits; small errors are worked off by running a little fast or
## slow.
class_name ClientClock
extends RefCounted
## More than this many commands waiting beyond the margin, and the clock waits for
## the server instead of drifting back.
const FAR_AHEAD_TICKS: float = 6.0
## How much of each new measurement goes into the smoothed margin.
const SMOOTHING: float = 0.1
## The clock runs at most this much fast or slow.
const MAX_RATE_CHANGE: float = 0.02
var running: bool = false
## Commands waiting at the server, smoothed over recent snapshots.
var margin: float = Tuning.NET_COMMAND_MARGIN_TICKS
## Times the clock had to jump, for tests and the network graph.
var jumps: int = 0
var _time: float = 0.0
var _rate: float = 1.0
## Echoes of commands older than this were sent before the last jump and say nothing
## about the clock as it is now.
var _settle_tick: int = 0
## Snapshots in a row that said commands were arriving late.
var _late: int = 0
## Starts the clock from the first snapshot of a match the client plays in.
func start(sim_tick: int) -> void:
running = true
_time = float(sim_tick + Tuning.NET_COMMAND_LEAD_START_TICKS)
_rate = 1.0
margin = Tuning.NET_COMMAND_MARGIN_TICKS
_settle_tick = tick()
_late = 0
jumps = 0
func stop() -> void:
running = false
func advance(delta: float) -> void:
if running:
_time += delta * Tuning.TICK_RATE_HZ * _rate
## The newest tick a command should exist for by now.
func tick() -> int:
return floori(_time)
## How far the clock is into the tick after tick(), from 0 to 1.
func fraction() -> float:
return _time - floorf(_time)
## Takes a snapshot's word on how the clock is doing: the server was about to run
## `sim_tick`, and the newest command it had from this client was for `command_tick`
## (-1 if it had none).
func observe(sim_tick: int, command_tick: int) -> void:
if not running or command_tick < _settle_tick:
return
var waiting: float = float(command_tick - sim_tick + 1)
var wanted: float = Tuning.NET_COMMAND_MARGIN_TICKS
_late = _late + 1 if waiting <= 0.0 else 0
if _late == 1:
return
if _late > 1 or waiting > wanted + FAR_AHEAD_TICKS:
var before: int = tick()
_time += wanted - waiting
_settle_tick = maxi(before + 1, tick())
_rate = 1.0
_late = 0
margin = wanted
jumps += 1
return
margin = lerpf(margin, waiting, SMOOTHING)
_rate = 1.0 + clampf((wanted - margin) * 0.01, -MAX_RATE_CHANGE, MAX_RATE_CHANGE)