gale.net.prediction module

This file contains the implementation of the class PredictionBuffer, a small recipe for client-side prediction and server reconciliation: a client applies its own inputs immediately (instead of waiting for a round trip to the server) so movement feels instant, keeps a record of each predicted input/state pair, and later replays whatever inputs the server has not yet acknowledged on top of the authoritative state it sends back, so the client ends up in the same place the server would have put it while still feeling responsive.

Like gale.net’s other recipes (see gale.net.interpolation), this is kept generic over plain, JSON-serializable state and input payloads: gale.net has no notion of “physics” or “entities”, it only moves bytes and tracks time, so this module only ever deals in plain dicts and a game-supplied apply_input function.

Author: Alejandro Mujica (aledrums@gmail.com)

class gale.net.prediction.PredictionBuffer[source]

Bases: object

Buffers a client’s own predicted inputs/states so they can be replayed on top of an authoritative state sent back by the server (client-side prediction + server reconciliation).

Usage example:

buffer = PredictionBuffer()

# Every local frame, after applying input payload for dt # seconds and predicting the resulting state: sequence += 1 predicted_state = apply_input(current_state, payload, dt) buffer.record(sequence, payload, dt, predicted_state) client.send(“input”, {“sequence”: sequence, **payload})

# When the server reports how far it got: def on_snapshot(payload):

state = buffer.reconcile(

payload[“last_processed_sequence”], payload[“state”], apply_input,

) # state is where the client should render from now; # smoothly correcting towards it (rather than snapping) # to hide any discrepancy with what was predicted before # is left to the game, the same way gale.net leaves the # amount of snapshot-interpolation delay to the game (see # gale.net.interpolation).

apply_input has the signature (state, input_payload, dt) -> new_state, and must be a pure function of its arguments (no reliance on wall-clock time, randomness, or outside state) since it is replayed after the fact, possibly several times per reconcile() call.

property pending_count: int

The number of recorded inputs not yet discarded by reconcile(), i.e. still awaiting server acknowledgement.

Type:

returns

record(sequence, input_payload, predicted_state, dt=0.0)[source]

Store an input and the state predicted from applying it, keyed by sequence number, to be replayed later if the server’s authoritative state does not already account for it.

Parameters:

  • sequence (int) – This input’s sequence number. Must increase from one call to the next (matching the sequence the game sends to the server alongside the input).

  • input_payload (Dict[str, Any]) – The input applied this frame.

  • predicted_state (Dict[str, Any]) – The state that resulted from applying input_payload locally. Not used by reconcile() itself (it always replays from the authoritative state), but useful for the game to inspect/compare.

  • dt (float) – Time elapsed, in seconds, over which input_payload was applied. Replayed unchanged by reconcile(). The default value is 0.0.

Return type:

None

reconcile(last_processed_sequence, authoritative_state, apply_input)[source]

Discard every recorded input the server has already accounted for (sequence <= last_processed_sequence), then replay every remaining, unacknowledged input on top of authoritative_state, in the order it was recorded.

Parameters:

  • last_processed_sequence (int) – The highest input sequence number the server had already processed when it produced authoritative_state.

  • authoritative_state (Dict[str, Any]) – The state the server computed after processing inputs up through last_processed_sequence.

  • apply_input (Callable[[Dict[str, Any], Dict[str, Any], float], Dict[str, Any]]) – Function (state, input_payload, dt) -> new_state, applied once per remaining buffered input, in order.

Returns:

The reconciled state: authoritative_state with every unacknowledged input replayed on top of it.

Return type:

Dict[str, Any]