#pragma once #include "evo/network/probe_motion.hpp" #include #include #include #include #include // M10.6 client prediction and reconciliation of the probe marker (ADR-0094). Headless, // single-owner, presentation only: nothing here is authority. // // The predictor keeps a bounded list of sent, unacknowledged inputs. On each authoritative // marker state (from a snapshot: state after tick T, newest applied intention sequence) it // restores that state, drops inputs that are applied or can no longer apply (tick <= T), // and replays the rest with the shared rule up to the presented tick. The difference that // rebasing makes to the presented position is a correction; the smoother hides it over a // short time (or snaps when it is large). Prediction never outlives its inputs: a refused // intention is removed, and a reset (new session or epoch) forgets everything. namespace evo::client { struct PredictionLimits { std::size_t max_pending{32}; // Sent, unacknowledged inputs (bounded replay). std::uint64_t max_replay_ticks{32}; // Ticks predicted beyond the authoritative state. std::size_t max_history{128}; // Predicted states kept to measure errors. std::size_t max_errors{4096}; // Error samples awaiting take_errors(). }; struct MotionInput { std::uint64_t sequence{}, tick{}; network::motion::Vector vector; }; // The authoritative marker as a snapshot reports it: the state after `tick`. struct AuthoritativeMarker { std::uint64_t tick{}, applied_sequence{}; network::motion::State state; network::motion::Area area; }; struct PredictionStats { std::uint64_t authoritative{}, corrections{}, replayed_ticks{}, dropped_inputs{}, rejected_inputs{}; std::uint64_t max_error_um{}, max_pending{}; }; class MotionPredictor { public: explicit MotionPredictor(PredictionLimits limits = {}) : limits_{limits} {} // A new session or epoch: forget the authoritative state, inputs and history. void reset(); // Records a sent input. False (nothing recorded) when the list is full or the input's // tick is not after the authoritative state; the caller then does not send it. [[nodiscard]] bool input(const MotionInput& in); // The server refused this input: it never takes effect. void rejected(std::uint64_t sequence); // A newer authoritative state (older or equal ticks are ignored). void authoritative(const AuthoritativeMarker& a); // The predicted state after `tick` (the presented tick: server tick plus input lead); // nothing before the first authoritative state. [[nodiscard]] std::optional predict(std::uint64_t tick); // M10.7 (ADR-0095): the position `fraction` (0..1) of the way from tick to tick + 1, for // presentation between ticks. With `record`, the prediction for `tick` is kept to measure // errors like predict(); a caller presenting beyond the tick it schedules inputs for passes // false (inputs for that tick may still come). struct Point { double x{}, y{}; // Micrometres. }; [[nodiscard]] std::optional predict_between(std::uint64_t tick, double fraction, bool record = true); // The jump rebasing made to the newest prediction (old minus new), since the last call. struct Offset { std::int64_t x{}, y{}; }; [[nodiscard]] Offset take_correction() noexcept; // Distance in micrometres between what was predicted for a tick and what the authority // reported for it, one sample per authoritative state that had a prediction. [[nodiscard]] std::vector take_errors(); [[nodiscard]] std::size_t pending() const noexcept { return pending_.size(); } [[nodiscard]] bool full() const noexcept { return pending_.size() >= limits_.max_pending; } [[nodiscard]] const std::optional& authority() const noexcept { return authority_; } [[nodiscard]] const PredictionStats& stats() const noexcept { return stats_; } private: [[nodiscard]] std::optional predict(std::uint64_t tick, bool record); [[nodiscard]] std::optional replay(std::uint64_t tick); // Re-predicts the newest presented tick after a change and accumulates the jump. void rebase(const std::optional& before); PredictionLimits limits_; std::optional authority_; std::vector pending_; // Ascending tick, then sequence. std::map history_; std::optional presented_tick_; Offset correction_; std::vector errors_; PredictionStats stats_; }; // Presentation smoothing, separate from prediction: a visual offset that decays to zero. class CorrectionSmoother { public: explicit CorrectionSmoother(double half_life_ms = 60, std::int64_t snap_um = 2'000'000) : half_life_ms_{half_life_ms}, snap_um_{snap_um} {} // Adds a correction (old minus new predicted position). Larger offsets snap. void add(MotionPredictor::Offset correction); // Advances by `elapsed_ms` and returns the offset to add to the predicted position. [[nodiscard]] MotionPredictor::Offset advance(double elapsed_ms); void reset() noexcept { x_ = y_ = 0; } [[nodiscard]] std::uint64_t snaps() const noexcept { return snaps_; } private: double half_life_ms_; std::int64_t snap_um_; double x_{}, y_{}; std::uint64_t snaps_{}; }; // How many ticks ahead of the client's newest known server tick inputs are scheduled. It // grows when the server refuses an input as too late (outside_window) and shrinks slowly // when receipts show spare ticks, within [min, max] (max below the admission window). class InputLead { public: explicit InputLead(std::uint64_t min = 2, std::uint64_t max = 7) : min_{min}, max_{max}, lead_{min} {} [[nodiscard]] std::uint64_t lead() const noexcept { return lead_; } void too_late() noexcept; // An admitted input for `tick` received at the server's `server_tick`. void admitted(std::uint64_t tick, std::uint64_t server_tick) noexcept; void reset() noexcept { lead_ = min_; spare_ = 0; } private: std::uint64_t min_, max_, lead_; std::uint32_t spare_{}; }; } // namespace evo::client