Files
tidewall/test/net/test_client_prediction.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

188 lines
7.0 KiB
GDScript

extends TestCase
## Issue N3: predicting the client's own player and reconciling with the server, on a
## flat test ground with the server's simulation stepped by hand. Snapshots here
## arrive `DELAY` ticks after the state they describe.
const DELAY: int = 6
const DT: float = 1.0 / Tuning.TICK_RATE_HZ
var sim: Simulation
var server: SimEntity
var prediction: ClientPrediction
## What the client is sent, oldest first: [simulation tick, own block, record].
var snapshots: Array = []
func before_each() -> void:
sim = Simulation.new(9, SimGround.flat())
server = sim.entities.find(sim.add_player())
server.position = Vector3(500.0, 0.0, 500.0)
prediction = ClientPrediction.new()
prediction.begin(sim.ground, null)
snapshots.clear()
_snapshot()
_deliver()
func _snapshot() -> void:
snapshots.append([sim.tick, SnapshotSender.own_block(sim, server), NetSnapshot.record_of(server)])
func _deliver() -> float:
var snapshot: Array = snapshots.pop_front()
return prediction.reconcile(server.id, snapshot[1], snapshot[2], snapshot[0])
func _command(tick: int) -> PlayerCommand:
var buttons: int = PlayerCommand.BUTTON_SPRINT if tick % 90 < 45 else 0
if tick % 40 == 7:
buttons |= PlayerCommand.BUTTON_JUMP
return PlayerCommand.from_input(tick, Vector2(sin(tick * 0.03), 1.0), 0.5 + sin(tick * 0.01) * 0.5, 0.0, buttons)
## One tick of both ends: the client predicts `tick`, the server runs it with the
## command unless it is `lost`, and the snapshot from DELAY ticks ago arrives.
func _tick(lost: bool = false) -> float:
var command: PlayerCommand = _command(prediction.next_tick)
prediction.predict(command)
if not lost:
assert_true(sim.submit_command(server.id, command))
sim.step()
_snapshot()
return _deliver() if snapshots.size() > DELAY else 0.0
func test_the_first_snapshot_starts_prediction_where_the_server_is() -> void:
assert_true(prediction.active)
assert_eq(prediction.next_tick, 0)
assert_eq(prediction.player.position, server.position)
assert_eq(prediction.player.id, server.id)
func test_prediction_runs_ahead_and_matches_the_server_exactly() -> void:
for _round: int in 600:
assert_eq(_tick(), 0.0)
assert_eq(prediction.player.position, server.position, "the client is where the server is, without waiting to be told")
assert_eq(prediction.player.velocity, server.velocity)
assert_eq(prediction.mispredictions, 0)
assert_true(prediction.reconciles > 500)
assert_true(server.position.distance_to(Vector3(500.0, 0.0, 500.0)) > 20.0, "and they went somewhere")
assert_eq(prediction.hidden_correction(), 0.0)
func test_swimming_and_the_water_around_the_player_are_predicted() -> void:
sim.set_sea_level(3.0)
_snapshot()
_deliver()
var swum: int = 0
for _round: int in 300:
_tick()
swum += 1 if server.swimming else 0
assert_true(swum > 150, "deep water over a flat floor: swam for %d ticks" % swum)
assert_eq(prediction.player.position, server.position)
assert_eq(prediction.player.stamina_ticks, server.stamina_ticks)
assert_true(prediction.mispredictions <= 1, "only the sea arriving unannounced: %d" % prediction.mispredictions)
func test_a_command_the_server_never_got_is_corrected_and_the_fix_is_eased_in() -> void:
for _round: int in 75:
_tick()
assert_true(server.on_ground)
var lost_at: int = prediction.next_tick
_tick(true)
# The server stood still that tick; the client walked. Nobody knows yet.
var apart: float = prediction.player.position.distance_to(server.position)
assert_true(apart > 0.1 and apart < 0.3, "one tick of running: %.3f m" % apart)
var corrected: float = 0.0
var drawn_before: Vector3 = prediction.view_position()
for _round: int in DELAY + 1:
var drawn: Vector3 = prediction.view_position()
var moved: float = _tick()
if moved > 0.0:
corrected = moved
# The frame the news arrives, the drawn position doesn't jump: it moves by
# the tick just predicted and no more.
assert_true(prediction.view_position().distance_to(drawn) < 0.3, "drawn position moved %.3f m" % prediction.view_position().distance_to(drawn))
assert_near(prediction.hidden_correction(), moved, 0.001)
assert_near(corrected, apart, 0.05, "corrected by about what the lost tick was worth")
assert_eq(prediction.mispredictions, 1)
assert_eq(prediction.player.position, server.position, "back in step, tick %d on" % lost_at)
assert_true(drawn_before != prediction.view_position())
for _frame: int in 60:
prediction.smooth(1.0 / 60.0)
assert_eq(prediction.hidden_correction(), 0.0, "the offset fades out within a second")
for _round: int in 60:
assert_eq(_tick(), 0.0)
assert_eq(prediction.mispredictions, 1)
func test_being_moved_by_the_server_far_away_is_shown_at_once() -> void:
for _round: int in 30:
_tick()
server.position += Vector3(40.0, 0.0, 0.0)
for _round: int in DELAY + 2:
_tick()
assert_eq(prediction.snaps, 1)
assert_eq(prediction.hidden_correction(), 0.0)
assert_eq(prediction.player.position, server.position)
func test_drawing_between_ticks_goes_from_the_last_tick_to_this_one() -> void:
for _round: int in 20:
_tick()
var before: Vector3 = prediction.player.position
_tick()
var after: Vector3 = prediction.player.position
assert_eq(prediction.view_position(0.0), before)
assert_eq(prediction.view_position(1.0), after)
assert_eq(prediction.view_position(0.5), before.lerp(after, 0.5))
func test_the_barge_ride_and_the_leap_are_predicted_from_the_same_route() -> void:
sim = Simulation.new(21)
sim.start_drop()
server = sim.entities.find(sim.add_player())
prediction = ClientPrediction.new()
prediction.begin(sim.ground, Drop.plan(sim.ground, SimRng.new(21), 0))
snapshots.clear()
_snapshot()
_deliver()
assert_eq(prediction.player.drop_state, Drop.ABOARD)
var leap_at: int = sim.drop.duration_ticks / 2
for round: int in leap_at + 200:
var command: PlayerCommand = PlayerCommand.from_input(prediction.next_tick, Vector2(0.3, 1.0), 1.0, 0.0, PlayerCommand.BUTTON_JUMP if round == leap_at else 0)
prediction.predict(command)
sim.submit_command(server.id, command)
sim.step()
_snapshot()
if snapshots.size() > DELAY:
_deliver()
if prediction.player.position != server.position:
fail("apart at tick %d: %s and %s" % [sim.tick, prediction.player.position, server.position])
break
assert_true(server.drop_state == Drop.FREEFALL or server.drop_state == Drop.GLIDING, "leapt and falling")
assert_eq(prediction.mispredictions, 0)
func test_being_thrown_off_at_the_end_of_the_route_is_predicted_too() -> void:
sim = Simulation.new(21)
sim.start_drop()
server = sim.entities.find(sim.add_player())
prediction = ClientPrediction.new()
prediction.begin(sim.ground, Drop.plan(sim.ground, SimRng.new(21), 0))
snapshots.clear()
_snapshot()
_deliver()
for _round: int in sim.drop.duration_ticks + 30:
var command: PlayerCommand = PlayerCommand.from_input(prediction.next_tick, Vector2.ZERO, 0.0, 0.0)
prediction.predict(command)
sim.submit_command(server.id, command)
sim.step()
_snapshot()
if snapshots.size() > DELAY:
_deliver()
assert_ne(server.drop_state, Drop.ABOARD)
assert_eq(prediction.player.position, server.position)
assert_eq(prediction.mispredictions, 0)