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
+93 -24
View File
@@ -8,9 +8,10 @@
##
## server -> SNAPSHOT (channel 1, unreliable)
## u8 type, u32 server tick, u32 baseline tick (0 = none), u32 simulation tick,
## u32 last command tick taken from this client, varint the entity the client is
## watching (its own player, or the one it spectates; 0 = none), u8 match
## phase, u8 tide phase, s16 sea level in centimetres,
## u32 newest command tick received from this client plus one (0 = none yet),
## varint the entity the client is watching (its own player, or the one it
## spectates; 0 = none), u8 match phase, u8 tide phase, s16 sea level in centimetres,
## u8 1 if the client's own block follows, then that block (see SELF_BYTES),
## u8 removed count, then entity IDs as varints,
## u16 record count, then per record: varint ID, u8 (archetype << 5 | group mask),
## then the fields of each group in the mask
@@ -32,6 +33,14 @@ const MSG_INPUT: int = 17
## orders snapshots across matches. The simulation tick is the one commands name.
const HEADER_BYTES: int = 17
const MATCH_BYTES: int = 14
## The client's own block: what it needs to predict its own player and nobody else is
## told. Exact, not quantized, so a prediction made from it matches the server's to the
## bit: position and velocity (three f32 each, which is all a Vector3 holds), the water
## level around the player (f64), which of the nine flood cells around the player that
## water reaches (u16), swimming stamina in ticks (u16) and the player's FLAG_ bits (u8).
const SELF_BYTES: int = 37
## Every bit of the nine-cell water mask.
const WATER_EVERYWHERE: int = 0x1FF
## The most commands one INPUT may carry. Clients send fewer; see Tuning.
const MAX_INPUT_COMMANDS: int = 8
@@ -117,20 +126,7 @@ static func record_of(entity: SimEntity) -> PackedInt32Array:
record[R_PITCH] = clampi(roundi(float(entity.pitch) / PlayerCommand.PITCH_MAX * 127.0), -127, 127)
record[R_HEALTH] = clampi(entity.health, 0, 255)
record[R_ARMOR] = clampi(entity.armor, 0, 255)
var flags: int = (entity.drop_state & 3) << FLAG_DROP_SHIFT
if entity.on_ground:
flags |= FLAG_ON_GROUND
if entity.crouching:
flags |= FLAG_CROUCHING
if entity.swimming:
flags |= FLAG_SWIMMING
if entity.eliminated:
flags |= FLAG_ELIMINATED
if entity.reload_ticks > 0:
flags |= FLAG_RELOADING
if entity.use_ticks > 0:
flags |= FLAG_USING
record[R_FLAGS] = flags
record[R_FLAGS] = flags_of(entity)
var held: int = -1
if entity.selected >= 1 and entity.selected <= entity.slot_items.size():
held = entity.slot_items[entity.selected - 1]
@@ -145,6 +141,47 @@ static func record_of(entity: SimEntity) -> PackedInt32Array:
return record
## A player's FLAG_ bits.
static func flags_of(entity: SimEntity) -> int:
var flags: int = (entity.drop_state & 3) << FLAG_DROP_SHIFT
if entity.on_ground:
flags |= FLAG_ON_GROUND
if entity.crouching:
flags |= FLAG_CROUCHING
if entity.swimming:
flags |= FLAG_SWIMMING
if entity.eliminated:
flags |= FLAG_ELIMINATED
if entity.reload_ticks > 0:
flags |= FLAG_RELOADING
if entity.use_ticks > 0:
flags |= FLAG_USING
return flags
## The client's own block for `player`. `water` is the level of the water around it and
## `water_mask` says which of the nine flood cells around it that water reaches: bit
## (dz + 1) * 3 + (dx + 1) for the cell dx, dz away from the player's.
static func self_of(player: SimEntity, water: float, water_mask: int) -> Dictionary:
return {
"position": player.position, "velocity": player.velocity, "water": water,
"water_mask": water_mask, "stamina": player.stamina_ticks, "flags": flags_of(player),
}
## Puts a client's own block into `player`: everything movement depends on.
static func apply_self(player: SimEntity, own: Dictionary) -> void:
var flags: int = own["flags"]
player.position = own["position"]
player.velocity = own["velocity"]
player.stamina_ticks = own["stamina"]
player.on_ground = flags & FLAG_ON_GROUND != 0
player.crouching = flags & FLAG_CROUCHING != 0
player.swimming = flags & FLAG_SWIMMING != 0
player.eliminated = flags & FLAG_ELIMINATED != 0
player.drop_state = (flags >> FLAG_DROP_SHIFT) & 3
## Where a record's entity is, to the nearest 1/64 m.
static func position_of(record: PackedInt32Array) -> Vector3:
return Vector3(
@@ -203,11 +240,22 @@ static func encode_snapshot(header: Dictionary, removed: PackedInt32Array, recor
out.put_u32(int(header["tick"]) & 0xFFFFFFFF)
out.put_u32(int(header.get("baseline", 0)) & 0xFFFFFFFF)
out.put_u32(int(header.get("sim_tick", 0)) & 0xFFFFFFFF)
out.put_u32(int(header.get("command_tick", 0)) & 0xFFFFFFFF)
out.put_u32((int(header.get("command_tick", -1)) + 1) & 0xFFFFFFFF)
_put_varint(out, int(header.get("own_id", 0)))
out.put_u8(int(header.get("match_phase", 0)))
out.put_u8(int(header.get("tide_phase", 0)))
out.put_16(clampi(int(header.get("sea_cm", 0)), -32768, 32767))
var own: Dictionary = header.get("self", {})
out.put_u8(0 if own.is_empty() else 1)
if not own.is_empty():
for vector: Vector3 in [own["position"], own["velocity"]]:
out.put_float(vector.x)
out.put_float(vector.y)
out.put_float(vector.z)
out.put_double(own["water"])
out.put_u16(int(own["water_mask"]) & WATER_EVERYWHERE)
out.put_u16(clampi(int(own["stamina"]), 0, 65535))
out.put_u8(int(own["flags"]) & 0xFF)
out.put_u8(removed.size())
for entity_id: int in removed:
_put_varint(out, entity_id)
@@ -237,24 +285,45 @@ static func encode_snapshot(header: Dictionary, removed: PackedInt32Array, recor
## Reads a SNAPSHOT's header and lists, without applying them: {"tick", "baseline",
## "sim_tick", "command_tick", "own_id", "match_phase", "tide_phase", "sea_cm", "removed":
## "sim_tick", "command_tick" (-1 = none yet), "own_id", "match_phase", "tide_phase",
## "sea_cm", "self": the client's own block as self_of() made it, or empty, "removed":
## PackedInt32Array, "records": [[entity ID, archetype, mask, values]]}, where `values`
## holds the fields present, in record order. Empty if malformed.
static func decode_snapshot(bytes: PackedByteArray) -> Dictionary:
if bytes.size() < HEADER_BYTES + 7 or bytes[0] != MSG_SNAPSHOT:
if bytes.size() < HEADER_BYTES + 8 or bytes[0] != MSG_SNAPSHOT:
return {}
var cursor: Array[int] = [HEADER_BYTES]
var own_id: int = _read_varint(bytes, cursor)
if own_id < 0 or cursor[0] + 5 > bytes.size():
if own_id < 0 or cursor[0] + 6 > bytes.size():
return {}
var at: int = cursor[0]
var result: Dictionary = {
"tick": bytes.decode_u32(1), "baseline": bytes.decode_u32(5), "sim_tick": bytes.decode_u32(9),
"command_tick": bytes.decode_u32(13),
"command_tick": bytes.decode_u32(13) - 1,
"own_id": own_id, "match_phase": bytes[at], "tide_phase": bytes[at + 1], "sea_cm": bytes.decode_s16(at + 2),
}
var removed_count: int = bytes[at + 4]
cursor[0] = at + 5
var own: Dictionary = {}
at += 5
if bytes[at - 1] > 1:
return {}
if bytes[at - 1] == 1:
if at + SELF_BYTES + 1 > bytes.size():
return {}
own = {
"position": Vector3(bytes.decode_float(at), bytes.decode_float(at + 4), bytes.decode_float(at + 8)),
"velocity": Vector3(bytes.decode_float(at + 12), bytes.decode_float(at + 16), bytes.decode_float(at + 20)),
"water": bytes.decode_double(at + 24),
"water_mask": bytes.decode_u16(at + 32) & WATER_EVERYWHERE,
"stamina": bytes.decode_u16(at + 34),
"flags": bytes[at + 36],
}
for value: float in [own["position"].x, own["position"].y, own["position"].z, own["velocity"].x, own["velocity"].y, own["velocity"].z, own["water"]]:
if not is_finite(value):
return {}
at += SELF_BYTES
result["self"] = own
var removed_count: int = bytes[at]
cursor[0] = at + 1
var removed: PackedInt32Array = PackedInt32Array()
for _index: int in removed_count:
var entity_id: int = _read_varint(bytes, cursor)