Files
tidewall/test/net/test_prediction_link.gd
T
claudeandClaude Opus 5.5 4111a285f0 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>
2026-11-12 11:30:00 -05:00

319 lines
16 KiB
GDScript

extends TestCase
## Issue N3's numbers: two people play the start of a real match on a real island,
## each through a link with 100 ms of latency each way, 20 ms of jitter and 2% loss.
## They ride the barge, leap, glide down and then walk, sprint, strafe, jump and crouch
## about the middle of the island. Measures how far the server ever had to correct
## each one's own predicted movement, and how evenly each is drawn on the other's
## screen, against where the server really had them.
const TICK_MS: float = 1000.0 / Tuning.TICK_RATE_HZ
const FRAME_MS: float = 1000.0 / 60.0
## Play measured once both are on the ground, in ticks.
const GROUND_TICKS: int = 75 * Tuning.TICK_RATE_HZ
const LIMIT_TICKS: int = 200 * Tuning.TICK_RATE_HZ
var loop: ServerLoop
var game: NetGame
var clients: Array[ClientGame] = []
var leap_tick: int = 0
## Per client: the tick it first stood (or swam) after the drop, or -1.
var landed: Array[int] = []
func _input(tick: int, index: int) -> PlayerCommand:
var me: SimEntity = clients[index].prediction.player
var centre: Vector3 = Vector3(Tuning.WORLD_SIZE_METRES * 0.5, 0.0, Tuning.WORLD_SIZE_METRES * 0.5)
var move: Vector2 = Vector2.ZERO
var buttons: int = 0
var goal: Vector3 = centre
var wander: float = 0.0
if me.drop_state == Drop.ABOARD:
if tick >= leap_tick:
buttons |= PlayerCommand.BUTTON_JUMP
elif me.drop_state != Drop.NONE:
move = Vector2(0.0, 1.0)
else:
if landed[index] < 0:
landed[index] = tick
var since: int = tick - landed[index] + index * 7 * Tuning.TICK_RATE_HZ
var seconds: float = fmod(float(since) / Tuning.TICK_RATE_HZ, 24.0)
var lap: float = floorf(float(since) / Tuning.TICK_RATE_HZ / 24.0)
var angle: float = lap * 1.3 + index * PI
goal = centre + Vector3(cos(angle), 0.0, sin(angle)) * 40.0
wander = sin(float(since) * 0.05) * 0.8
if seconds < 4.0:
move = Vector2(0.0, 1.0)
elif seconds < 9.0:
move = Vector2(0.0, 1.0)
buttons |= PlayerCommand.BUTTON_SPRINT
elif seconds < 11.0:
move = Vector2(1.0, 0.3)
elif seconds < 12.0:
pass
elif seconds < 16.0:
move = Vector2(0.0, 1.0)
buttons |= PlayerCommand.BUTTON_SPRINT
if since % 45 < 2:
buttons |= PlayerCommand.BUTTON_JUMP
elif seconds < 19.0:
move = Vector2(0.2, 1.0)
buttons |= PlayerCommand.BUTTON_CROUCH
elif seconds < 22.0:
move = Vector2(-0.7, -0.7)
else:
move = Vector2(0.0, 1.0)
buttons |= PlayerCommand.BUTTON_SPRINT
var yaw: float = atan2(goal.x - me.position.x, goal.z - me.position.z) + wander
return PlayerCommand.from_input(tick, move, yaw, sin(float(tick) * 0.02) * 0.4, buttons)
## What a link with no jitter and no loss would draw at that moment: a straight line
## between the two snapshots around it, which are of every second tick, with positions
## as coarse as the wire makes them.
func _ideal(history: Array, time: float) -> Vector3:
var step: int = Tuning.NET_SNAPSHOT_INTERVAL_TICKS
var from: int = clampi(floori(time / step) * step, 0, history.size() - 1 - step)
var steps: float = NetSnapshot.POSITION_STEPS_PER_METRE
var a: Vector3 = (history[from] as Vector3 * steps).round() / steps
var b: Vector3 = (history[from + step] as Vector3 * steps).round() / steps
return a.lerp(b, clampf((time - from) / step, 0.0, 1.0))
## Where the server had an entity at a moment between ticks.
func _truth(history: Array, time: float) -> Vector3:
var index: int = clampi(floori(time), 0, history.size() - 2)
return (history[index] as Vector3).lerp(history[index + 1], clampf(time - index, 0.0, 1.0))
## Plays the match through links with `latency_ms` each way, plus or minus
## `jitter_ms`, losing `loss` of all packets. Returns what each client measured once
## both were on the ground, or nothing if they never got there.
func _play(latency_ms: float, jitter_ms: float, loss: float) -> Array[Dictionary]:
var results: Array[Dictionary] = []
loop = ServerLoop.new(7, 2, 0)
game = NetGame.new(loop, NetServer.new())
var flow: Match = loop.match_flow
assert_eq(flow.phase, Match.DROP)
var sim: Simulation = loop.sim
# Leap once the barge is over land.
leap_tick = sim.drop.duration_ticks / 2
for tick: int in range(30, sim.drop.duration_ticks):
var under: Vector3 = sim.drop.barge_position(tick)
if sim.ground.terrain_height(under.x, under.z) > Tuning.ISLAND_BEACH_TOP + 2.0:
leap_tick = tick
break
# Both clients generate the island once between them: it's the same island.
var mirror: Simulation = Simulation.new(flow.current_seed())
clients.clear()
landed.clear()
var down: Array[LinkSim] = []
var up: Array[LinkSim] = []
var entity: Array[int] = []
# Per entity: where the server had it before each simulation tick.
var history: Dictionary = {}
# Per client, in ground play: metres the server moved its player, and ticks it
# spent in the air, crouched and standing still.
var travelled: Array[float] = [0.0, 0.0]
var airborne: Array[int] = [0, 0]
var crouched: Array[int] = [0, 0]
for index: int in 2:
var handle: int = index + 1
game.adopt(handle)
var client: ClientGame = ClientGame.new()
client.make_world = func(_seed: int) -> Simulation: return mirror
client.sample_input = _input.bind(index)
client.receive(NetProtocol.CHANNEL_CONTROL, game.match_notice())
clients.append(client)
landed.append(-1)
down.append(LinkSim.new(latency_ms, jitter_ms, loss, 100 + index))
up.append(LinkSim.new(latency_ms, jitter_ms, loss, 200 + index))
entity.append(int(flow.entity_of[handle]))
history[entity[index]] = [sim.entities.find(entity[index]).position]
var planned: Drop = Drop.plan(mirror.ground, SimRng.new(flow.current_seed()), 0)
assert_eq(planned.start, sim.drop.start, "the client plans the server's barge route")
assert_eq(planned.finish, sim.drop.finish)
assert_eq(planned.duration_ticks, sim.drop.duration_ticks)
var next_tick_ms: float = 0.0
var next_frame_ms: Array[float] = [3.0, 11.0]
var ground_from: int = -1
# Own movement: every correction, as [metres, during ground play].
var corrections: Array = [[], []]
var own_step_max: Array[float] = [0.0, 0.0]
var own_hidden_max: Array[float] = [0.0, 0.0]
var own_last: Array = [null, null]
# The other player as drawn: [error sum, error max, frames, sum and max of how far
# off a perfect link's drawing, sum and max of how far each frame's step was off a
# perfect link's, stalls, slowest and fastest the drawing clock ran in a frame].
var seen: Array = [[0.0, 0.0, 0, 0.0, 0.0, 0.0, 0.0, 0, INF, 0.0], [0.0, 0.0, 0, 0.0, 0.0, 0.0, 0.0, 0, INF, 0.0]]
var shown_last: Array = [null, null]
var time_last: Array[float] = [0.0, 0.0]
var now: float = 0.0
while sim.tick < LIMIT_TICKS and (ground_from < 0 or sim.tick < ground_from + GROUND_TICKS):
if flow.phase == Match.RESULTS:
fail("the match ended at tick %d" % sim.tick)
break
if now >= next_tick_ms:
next_tick_ms += TICK_MS
for index: int in 2:
for bytes: PackedByteArray in up[index].receive(now):
game.take_input(index + 1, bytes)
loop.run_tick()
game.after_tick()
for index: int in 2:
var player: SimEntity = sim.entities.find(entity[index])
var track: Array = history[entity[index]]
if ground_from >= 0 and sim.tick >= ground_from:
travelled[index] += player.position.distance_to(track[track.size() - 1])
airborne[index] += 0 if player.on_ground or player.swimming else 1
crouched[index] += 1 if player.crouching else 0
track.append(player.position)
if game.snapshot_due():
for index: int in 2:
down[index].send(game.snapshot_for(index + 1), now)
if ground_from < 0 and landed[0] >= 0 and landed[1] >= 0:
ground_from = sim.tick + 2 * Tuning.TICK_RATE_HZ
for index: int in 2:
if now < next_frame_ms[index]:
continue
next_frame_ms[index] += FRAME_MS
var client: ClientGame = clients[index]
var measuring: bool = ground_from >= 0 and sim.tick >= ground_from
for bytes: PackedByteArray in down[index].receive(now):
client.receive(NetProtocol.CHANNEL_STATE, bytes)
if client.prediction.last_correction > 0.0:
(corrections[index] as Array).append([client.prediction.last_correction, measuring])
client.prediction.last_correction = 0.0
client.advance(FRAME_MS / 1000.0)
for bytes: PackedByteArray in client.outbox:
up[index].send(bytes, now)
client.outbox.clear()
if not measuring:
own_last[index] = null
shown_last[index] = null
continue
# This client's own player, as drawn.
var own: Vector3 = client.own_position()
if own_last[index] != null:
own_step_max[index] = maxf(own_step_max[index], own.distance_to(own_last[index]))
own_last[index] = own
own_hidden_max[index] = maxf(own_hidden_max[index], client.prediction.hidden_correction())
# The other player, as drawn here, against where the server had them then.
var other: int = entity[1 - index]
var shown: Dictionary = client.remote.sample(other)
if shown.is_empty():
fail("client %d can't see the other player at tick %d" % [index, sim.tick])
continue
var stats: Array = seen[index]
var track: Array = history[other]
var truth: Vector3 = _truth(track, client.remote.time)
var error: float = (shown["position"] as Vector3).distance_to(truth)
stats[0] += error
stats[1] = maxf(stats[1], error)
stats[2] += 1
var ideal: Vector3 = _ideal(track, client.remote.time)
var off: float = (shown["position"] as Vector3).distance_to(ideal)
stats[3] += off
stats[4] = maxf(stats[4], off)
if shown_last[index] != null:
var step: float = (shown["position"] as Vector3).distance_to(shown_last[index])
var ideal_step: float = ideal.distance_to(_ideal(track, time_last[index]))
var roughness: float = absf(step - ideal_step)
stats[5] += roughness
stats[6] = maxf(stats[6], roughness)
if ideal_step > 0.04 and step < ideal_step * 0.25:
stats[7] += 1
var ran: float = client.remote.time - time_last[index]
stats[8] = minf(stats[8], ran)
stats[9] = maxf(stats[9], ran)
shown_last[index] = shown["position"]
time_last[index] = client.remote.time
now += 1.0
assert_true(ground_from >= 0, "both players landed (leapt at tick %d, landed %s)" % [leap_tick, landed])
if ground_from < 0:
return results
print(" link: %.0f ms each way, +-%.0f ms jitter, %.0f%% loss; %d ticks, leapt at %d, ground play from %d" % [latency_ms, jitter_ms, loss * 100.0, sim.tick, leap_tick, ground_from])
for index: int in 2:
var client: ClientGame = clients[index]
var prediction: ClientPrediction = client.prediction
var worst: float = 0.0
var worst_ground: float = 0.0
var count_ground: int = 0
for entry: Array in corrections[index]:
worst = maxf(worst, entry[0])
if entry[1]:
worst_ground = maxf(worst_ground, entry[0])
count_ground += 1
var stats: Array = seen[index]
print(" client %d's player on the server, in ground play: moved %.0f m, %d ticks in the air, %d crouched" % [index, travelled[index], airborne[index], crouched[index]])
print(" client %d own player: %d snapshots compared, %d corrected (%d in ground play), largest %.3f m (%.3f m in ground play), largest hidden offset %.3f m, largest drawn step %.3f m; clock jumps %d, margin %.2f ticks; packets lost %d of %d down, %d of %d up" % [
index, prediction.reconciles, (corrections[index] as Array).size(), count_ground, worst, worst_ground,
own_hidden_max[index], own_step_max[index], client.clock.jumps, client.clock.margin,
down[index].lost, down[index].sent, up[index].lost, up[index].sent,
])
var frames: int = maxi(stats[2], 1)
print(" client %d sees the other: %d frames; against the server, off by mean %.3f m, max %.3f m; against a perfect link, off by mean %.4f m, max %.3f m, and each frame's step off by mean %.4f m, max %.3f m; %d stalls; drawing clock ran %.3f to %.3f ticks a frame; %d frames extrapolated, %d held" % [
index, stats[2], stats[0] / frames, stats[1], stats[3] / frames, stats[4], stats[5] / frames, stats[6], stats[7], stats[8], stats[9],
client.remote.extrapolated, client.remote.held,
])
results.append({
"travelled": travelled[index], "airborne": airborne[index], "crouched": crouched[index],
"reconciles": prediction.reconciles, "corrections": (corrections[index] as Array).size(),
"corrections_ground": count_ground, "worst": worst, "worst_ground": worst_ground,
"hidden": own_hidden_max[index], "snaps": prediction.snaps, "own_step": own_step_max[index],
"jumps": client.clock.jumps, "frames": stats[2], "error_mean": stats[0] / frames, "error_max": stats[1],
"off_mean": stats[3] / frames, "off_max": stats[4], "step_off_mean": stats[5] / frames,
"step_off_max": stats[6], "stalls": stats[7], "clock_slowest": stats[8], "clock_fastest": stats[9],
"held": client.remote.held,
})
return results
func test_100_ms_20_ms_jitter_and_2_percent_loss() -> void:
var results: Array[Dictionary] = _play(100.0, 20.0, 0.02)
assert_eq(results.size(), 2)
for index: int in results.size():
var result: Dictionary = results[index]
var who: String = "client %d" % index
# The play measured was real: the server moved each player about, by their commands.
assert_true(result["travelled"] > 150.0, "%s moved %.0f m" % [who, result["travelled"]])
assert_true(result["airborne"] > 30, "%s jumped" % who)
assert_true(result["crouched"] > 30, "%s crouched" % who)
assert_true(result["reconciles"] > 1000, "%s compared %d snapshots" % [who, result["reconciles"]])
# Own movement: nothing the player could see was ever corrected on the ground,
# and nothing at all had to be shown at once.
assert_true(result["worst_ground"] <= 0.02, "%s's largest correction on the ground was %.3f m" % [who, result["worst_ground"]])
assert_true(result["hidden"] <= 0.02, "%s's drawn position was off by up to %.3f m" % [who, result["hidden"]])
assert_true(result["worst"] <= 0.5, "%s's largest correction in the drop was %.3f m" % [who, result["worst"]])
assert_eq(result["snaps"], 0, "%s: corrections shown at once" % who)
# Sprinting covers 0.11 m a frame, and a jump or a step up adds height.
assert_true(result["own_step"] <= 0.3, "%s's own player moved %.3f m in one frame" % [who, result["own_step"]])
assert_true(result["jumps"] <= 2, "%s's clock jumped %d times" % [who, result["jumps"]])
# The other player: drawn where a perfect link would draw them, evenly.
assert_true(result["frames"] > 4000)
assert_true(result["error_mean"] <= 0.03, "%s drew the other %.3f m off the server on average" % [who, result["error_mean"]])
assert_true(result["off_mean"] <= 0.003, "%s drew the other %.4f m off a perfect link on average" % [who, result["off_mean"]])
assert_true(result["off_max"] <= 0.3, "%s drew the other up to %.3f m off a perfect link" % [who, result["off_max"]])
assert_true(result["step_off_max"] <= 0.15, "%s: a frame's step was %.3f m off" % [who, result["step_off_max"]])
assert_true(result["stalls"] <= 3, "%s: %d stalls" % [who, result["stalls"]])
assert_true(result["clock_slowest"] >= 0.45 and result["clock_fastest"] <= 0.55, "%s's drawing clock ran %.3f to %.3f ticks a frame" % [who, result["clock_slowest"], result["clock_fastest"]])
assert_eq(result["held"], 0, "%s: frames with the other player held still" % who)
## Three times the latency, twice the jitter and five times the loss. Corrections
## happen here, and must stay small enough to blend away.
func test_a_much_worse_link_still_plays() -> void:
var results: Array[Dictionary] = _play(150.0, 40.0, 0.10)
assert_eq(results.size(), 2)
for index: int in results.size():
var result: Dictionary = results[index]
var who: String = "client %d" % index
assert_true(result["travelled"] > 150.0, "%s moved %.0f m" % [who, result["travelled"]])
assert_true(result["worst_ground"] <= 1.0, "%s's largest correction on the ground was %.3f m" % [who, result["worst_ground"]])
assert_eq(result["snaps"], 0, "%s: corrections shown at once" % who)
assert_true(result["own_step"] <= 0.4, "%s's own player moved %.3f m in one frame" % [who, result["own_step"]])
assert_true(result["jumps"] <= 3, "%s's clock jumped %d times" % [who, result["jumps"]])
assert_true(result["error_mean"] <= 0.1, "%s drew the other %.3f m off the server on average" % [who, result["error_mean"]])