Foundation / checks (deploy) (push) Successful in 6s
Foundation / checks (ecs) (push) Successful in 1m59s
Foundation / checks (client) (push) Successful in 12m44s
Foundation / checks (network) (push) Successful in 12m45s
Foundation / checks (tsan) (push) Successful in 8m5s
Foundation / checks (checks) (push) Successful in 32m4s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (postgres) (push) Canceled after 21m38s
ADR-0095 (presentation only): a drift-corrected monotonic tick clock that never runs more than one tick past the newest observation; remote probe markers shown 2-6 ticks behind (adaptive to snapshot gaps), interpolated, extrapolated for at most 2 ticks and then marked stale; appearance and removal at their snapshot ticks; organisms never extrapolated; sub-tick own-marker prediction. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
144 lines
6.1 KiB
C++
144 lines
6.1 KiB
C++
#pragma once
|
|
#include "evo/network/probe_motion.hpp"
|
|
#include <cstddef>
|
|
#include <cstdint>
|
|
#include <map>
|
|
#include <optional>
|
|
#include <vector>
|
|
|
|
// 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<network::motion::State> 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; records the prediction for `tick` like predict().
|
|
struct Point {
|
|
double x{}, y{}; // Micrometres.
|
|
};
|
|
[[nodiscard]] std::optional<Point> predict_between(std::uint64_t tick, double fraction);
|
|
// 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<std::uint64_t> 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<AuthoritativeMarker>& authority() const noexcept {
|
|
return authority_;
|
|
}
|
|
[[nodiscard]] const PredictionStats& stats() const noexcept {
|
|
return stats_;
|
|
}
|
|
|
|
private:
|
|
[[nodiscard]] std::optional<network::motion::State> replay(std::uint64_t tick);
|
|
// Re-predicts the newest presented tick after a change and accumulates the jump.
|
|
void rebase(const std::optional<network::motion::State>& before);
|
|
PredictionLimits limits_;
|
|
std::optional<AuthoritativeMarker> authority_;
|
|
std::vector<MotionInput> pending_; // Ascending tick, then sequence.
|
|
std::map<std::uint64_t, network::motion::State> history_;
|
|
std::optional<std::uint64_t> presented_tick_;
|
|
Offset correction_;
|
|
std::vector<std::uint64_t> 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
|