Client.hpp

Go to the documentation of this file.

 
#pragma once
 
#include "ecs/components/AnimSnapshot.hpp"
#include "ecs/components/InputSnapshot.hpp"
#include "ecs/registry/Registry.hpp"
#include "network/ChatProtocol.hpp"
#include "network/DiscoverySettings.hpp"
#include "network/MatchConfig.hpp"
#include "network/MatchStatus.hpp"
#include "network/MessageStream.hpp"
#include "network/NetKillEvent.hpp"
#include "network/NetworkConfig.hpp"
#include "network/OutboundQueue.hpp"
#include "network/RegistrySerialization.hpp"
#include "network/RosterEvent.hpp"
#include "network/ShotDebugReport.hpp" // PR-20: shared wire-format + runtime capture struct.
#include "network/ShotEvent.hpp"
#include "network/VoiceProtocol.hpp"
#include "network/lobby/LobbyStatus.hpp"
#include "network/transport/FragmentReassembler.hpp"
#include "network/transport/UdpEndpoint.hpp"
#include "network/transport/UdpSessionTransport.hpp"
 
#include <SDL3/SDL_stdinc.h>
 
#include <SDL3_net/SDL_net.h>
#include <array>
#include <atomic>
#include <cstdint>
#include <deque>
#include <entt/entt.hpp>
#include <mutex>
#include <optional>
#include <random>
#include <span>
#include <string_view>
#include <thread>
#include <utility>

struct NetworkStats
{
    float rttMs = 0.0f;                 
    float avgRttMs = 0.0f;              
    uint64_t bytesRecvTotal = 0;        
    uint64_t bytesSentTotal = 0;        
    float recvBytesPerSec = 0.0f;       
    float sendBytesPerSec = 0.0f;       
    uint32_t registryUpdateSize = 0;    
    float registryUpdatesPerSec = 0.0f; 
};
 
enum class ConnectError
{
    None,
    ResolveFailed,
    ResolveTimedOut,
    CreateClientFailed,
    ConnectTimedOut,
    ConnectFailed,
    LobbyFull,
};

class Client
{
public:
    using SnapshotApplyCallback = std::function<bool(std::uint32_t snapshotTick,
                                                     const std::uint8_t* bytes,
                                                     Uint32 size,
                                                     Uint64 captureNs,
                                                     std::uint32_t& ackedTick)>;
    using RawParticleEventCallback = std::function<void(const NetParticleEvent& evt)>;
    using MatchStateUpdateFn = std::function<void(const MatchStatePacket&)>;
    using KillEventCallback = std::function<void(const NetKillEvent&)>;
    using TextChatCallback = std::function<void(const net::chat::ServerTextChat&)>;
    using RosterEventCallback = std::function<void(const PlayerRosterEvent&)>;
    using VoiceFrameCallback = std::function<void(const net::voice::ServerVoiceFrame&)>;
    using ShotDebugCallback = std::function<void(const net::shotdebug::ShotDebugCapture&)>;

    using LobbyUpdateCallback = std::function<void(const LobbyUpdateEvent& update)>;
    using LobbyStateCallback = std::function<void(const std::vector<LobbyPlayer>& players, ClientId localId)>;
    using MatchConfigCallback = std::function<void(const MatchConfig& config)>;

    ConnectError init(const char* addr,
                      Uint16 port,
                      const TransportConfig& transport = {},
                      int timeoutMs = -1,
                      const std::optional<net::UdpSessionTransport::RelayConfig>& relay = std::nullopt,
                      const std::optional<net::UdpSessionTransport::PunchAssist>& punch = std::nullopt);

    void shutdown();

    bool isConnected();

    bool send(const void* data, uint32_t size);

    bool sendInputSnapshot(const InputSnapshot& snap);

    void resetInputHistory();

    bool sendShotIntent(std::uint32_t shotInputTick, std::uint16_t targetClientId, const AnimSnapshot& targetAnim);

    bool sendChatMessage(std::string_view message);

    bool sendPhysicsDiagRecording(bool enabled);

    bool sendVoiceFrame(std::uint16_t sequence, std::uint8_t frameMs, std::span<const std::uint8_t> opus);

    bool sendPlayerReady(bool ready);

    bool sendStartMatch();

    bool sendCancelStartMatch();

    bool sendMatchConfig(const MatchConfig& config);

    bool sendDiscoverySettings(const DiscoverySettings& settings);

    bool sendServerShutdown();

    void sendPing();

    void updateStats(float dt);
 
    void onSnapshotApply(SnapshotApplyCallback fn)
    {
        snapshotApplyFn_ = std::move(fn);
    } 
    void onRawParticleEvent(RawParticleEventCallback fn)
    {
        rawParticleEventFn_ = std::move(fn);
    } 
    void onMatchStateUpdate(MatchStateUpdateFn fn) { matchStateUpdateFn_ = std::move(fn); }
    void onKillEvent(KillEventCallback fn) { killEventFn_ = std::move(fn); }
    void onTextChat(TextChatCallback fn) { textChatFn_ = std::move(fn); }
    void onRosterEvent(RosterEventCallback fn) { rosterEventFn_ = std::move(fn); }
    void onVoiceFrame(VoiceFrameCallback fn) { voiceFrameFn_ = std::move(fn); }
    void onShotDebugReport(ShotDebugCallback fn) { shotDebugFn_ = std::move(fn); }
    void onLobbyUpdate(LobbyUpdateCallback fn)
    {
        lobbyUpdateFn_ = std::move(fn);
    } 
    void onLobbyState(LobbyStateCallback fn)
    {
        lobbyStateFn_ = std::move(fn);
    } 
    void onMatchConfig(MatchConfigCallback fn)
    {
        matchConfigFn_ = std::move(fn);
    } 

    bool poll();

    const NetworkStats& getNetStats() const { return stats; }

    std::optional<MatchStatePacket> getLatestMatchState() const { return latestMatchState_; }

    std::optional<MatchConfig> getLatestMatchConfig() const { return latestMatchConfig_; }

    std::optional<std::pair<std::vector<LobbyPlayer>, ClientId>> getLatestLobbyState() const;

    std::optional<std::string> getLatestServerName() const { return latestServerName_; }

    [[nodiscard]] uint32_t getServerAckedClientTick() const noexcept { return serverAckedClientTick_; }

    [[nodiscard]] bool consumeSnapshotApplied() noexcept
    {
        const bool was = snapshotAppliedFlag_;
        snapshotAppliedFlag_ = false;
        return was;
    }

    [[nodiscard]] float getSnapshotAlpha() const;

    [[nodiscard]] std::optional<entt::entity> getServerLocalPlayerEntity() const { return localPlayerEntity; }

    [[nodiscard]] Uint64 getInterpolationRenderTimeNs() const;

    [[nodiscard]] Uint64 getSnapshotIntervalNs() const;

    void applyInterpolatedTransforms(Registry& registry);

    void recordInterpolationSamples(Registry& registry, Uint64 captureNs);

    static constexpr size_t k_inputRedundancy = 5;

    void setSimulatedLatencyMs(int totalMs) noexcept;

    [[nodiscard]] int getSimulatedLatencyMs() const noexcept
    {
        return simulatedLatencyMs_.load(std::memory_order_relaxed);
    }

    void setSimulatedLossPercent(int percent) noexcept;

    [[nodiscard]] int getSimulatedLossPercent() const noexcept
    {
        return simulatedLossPercent_.load(std::memory_order_relaxed);
    }
 
    bool sendGameplayReady();
 
private:
    MessageStream msgStream{nullptr};              
    NET_Address* serverAddr = nullptr;             
    SnapshotApplyCallback snapshotApplyFn_;        
    RawParticleEventCallback rawParticleEventFn_;  
    MatchStateUpdateFn matchStateUpdateFn_;        
    KillEventCallback killEventFn_;                
    TextChatCallback textChatFn_;                  
    RosterEventCallback rosterEventFn_;            
    VoiceFrameCallback voiceFrameFn_;              
    ShotDebugCallback shotDebugFn_;                
    LobbyUpdateCallback lobbyUpdateFn_;            
    LobbyStateCallback lobbyStateFn_;              
    MatchConfigCallback matchConfigFn_;            
    std::optional<entt::entity> localPlayerEntity; 
    std::optional<MatchStatePacket>
        latestMatchState_;                         
    std::optional<MatchConfig> latestMatchConfig_; 
    std::optional<std::vector<LobbyPlayer>> latestLobbyPlayers_; 
    std::optional<ClientId> latestLobbyLocalId_;  
    std::optional<std::string> latestServerName_; 
 
    // ── PR-10 + PR-14 (server-perf): snapshot delta encoding state ────
    //
    // `keyframePayload_` holds the most-recent FULL snapshot's raw
    // entt-serialized bytes (no PacketType prefix, no tick), and
    // `keyframeTick_` is the tick that snapshot was sent at.
    //
    // PR-14 (loss resilience): both fields update *only* on FULL
    // arrival.  DELTA packets reconstruct the current frame's bytes
    // by applying their patch on top of the keyframe and feed the
    // reconstructed bytes into the Loader, but do NOT replace the
    // saved keyframe.  Pre-PR-14, every DELTA replaced the saved
    // baseline with the just-reconstructed bytes — which meant a
    // single dropped DELTA cascaded into all subsequent DELTAs in the
    // same keyframe window dropping silently (their `fromTick` no
    // longer matched the client's stored `lastSnapshotTick_`).  Now
    // every DELTA in a window is independently decodable against the
    // shared keyframe, so individual packet drops only cost that one
    // frame's state.
    //
    // If `fromTick` on a DELTA doesn't match `keyframeTick_` the
    // packet is dropped — happens when a FULL keyframe was lost or
    // hasn't arrived yet.  The next periodic full keyframe (every 8
    // snapshots ≈ 62 ms at 128 Hz) re-syncs us.
    std::vector<uint8_t> keyframePayload_;
    std::uint32_t keyframeTick_ = 0;
 
    NetworkStats stats; 
 
    // Bandwidth tracking — accumulated between updateStats() calls.
    uint64_t bytesSentWindow = 0;
    uint64_t bytesRecvWindow = 0;
    uint64_t udpSessionLastBytesSent_ = 0;
    uint64_t udpSessionLastBytesRecv_ = 0;
    uint32_t registryUpdatesWindow = 0;
    float statsAccumulator = 0.0f;
 
    // Redundant input ring — see k_inputRedundancy and sendInputSnapshot().
    // Stores the last N stamped InputSnapshots in chronological order so each
    // outbound INPUT packet can include them all (server dedups by tick).
    std::array<InputSnapshot, k_inputRedundancy> inputRing_{};
    size_t inputRingHead_ = 0;  
    size_t inputRingCount_ = 0; 
 
    // ── Stage 3c: dedicated network thread ────────────────────────────────
    //
    // Symmetric to the server's stage 3b. The network thread continuously
    // (a) pumps the kernel receive buffer into msgStream's recvBuf and
    // (b) drains the outbound queue to the socket. The game thread keeps
    // calling sendInputSnapshot / sendPing / poll() — those now
    // touch the queue + recvBuf under stateMutex_ rather than doing
    // syscalls inline. The win is that a render-frame stutter on the game
    // thread no longer causes the kernel buffer to back up.
    OutboundQueue outbound_;
    std::mutex stateMutex_;
    std::thread networkThread_;
    std::atomic<bool> shouldStop_{false};

    std::atomic<bool> socketDead_{false};
 
    // ── Phase 5a: snapshot-interval interpolation timing ──────────────────
    //
    // Updated whenever dispatchMessage applies an UPDATE_REGISTRY. The
    // renderer reads getSnapshotAlpha() instead of the physics-tick alpha
    // so motion stays smooth at the much-coarser snapshot rate. Both fields
    // are 0 before any snapshot has been applied; getSnapshotAlpha returns
    // 1.0 in that case so first frame draws the snapped position.
    Uint64 lastSnapshotApplyNs_ = 0;
    Uint64 prevSnapshotApplyNs_ = 0;
 
    // ── PR-11: render-delay interpolation ────────────────────────────────
    //
    // `interpDelaySnapshots_` is read once at init() from the
    // GROUP2_CLIENT_INTERP_DELAY_SNAPSHOTS env var (default 2).  0 disables
    // the buffered render-delay path entirely; non-local entities
    // fall back to the Phase-5a (prev, cur, alpha) lerp.  Higher values
    // smooth more loss but make remote entities visibly behind server
    // truth.  Source engine ships 2 (62.5 ms at 32 Hz) — that's our
    // default and matches Valorant / Fortnite cadence.
    //
    // EMA of snapshot apply intervals.  `prevSnapshotApplyNs_` and
    // `lastSnapshotApplyNs_` already give a single most-recent interval;
    // the EMA smooths burst arrivals so the render-delay computation
    // doesn't wobble when packets arrive bunched.  Snapshot rate doesn't
    // change during a session, so a single-pole IIR with α=0.25 is
    // ample.  Initial value matches the design's 32 Hz snapshot rate.
    // PR-13: 128 Hz default snapshot rate (AAA-pro cadence).  EMA
    // self-corrects once two snapshots have arrived if the actual
    // rate differs (e.g. legacy server running at 32 Hz from a
    // pre-PR-13 config.toml).  The two-snapshot warmup window is
    // ~16 ms at 128 Hz — fast enough that the initial value barely
    // matters in practice.
    static constexpr Uint64 k_defaultSnapshotIntervalNs = 1'000'000'000ULL / 128ULL;
 
    // PR-19: re-enabled default = 2 snapshots after `Client::
    // applyInterpolatedTransforms` started overwriting Position +
    // InputSnapshot.yaw in place every frame.  Now ALL visual
    // consumers (renderer, tracers, ribbon trails, smoke emitters,
    // beam endpoints, sfx) read from a single source of truth —
    // `pos.value`, freshly written each frame to the interpolated
    // value — so there's no more 6-unit body-vs-tracer separation
    // that PR-16 was the emergency hotfix for.
    //
    // PR-16's history (kept for posterity): pre-PR-19, PR-11 wired
    // `entity_interpolation::sample()` into 3 specific Game.cpp
    // render sites only, missing TracerEffect / RibbonTrail /
    // SmokeEffect / BeamState / sfx.  PR-16 default-flipped this to
    // 0 to disable the misaligned interp until PR-19's unified
    // approach landed.  PR-17 (FragmentReassembler stuck-state)
    // turned out to be the bigger source of "models in wrong
    // locations" — once that was fixed and PR-19 unifies the read
    // path, default-on is safe again.
    //
    // To disable: set `GROUP2_CLIENT_INTERP_DELAY_SNAPSHOTS=0`.
    int interpDelaySnapshots_ = 2;
    Uint64 snapshotIntervalEmaNs_ = k_defaultSnapshotIntervalNs;
 
    // ── Phase 5b: prediction reconciliation hand-off ──────────────────────
    //
    // Updated by dispatchMessage on every UPDATE_REGISTRY apply. The game
    // thread reads getServerAckedClientTick() + consumeSnapshotApplied() to
    // know when and from which tick to replay client-stored inputs.
    uint32_t serverAckedClientTick_ = 0;
    bool snapshotAppliedFlag_ = false;
 
    // ── Phase 3d: UDP sidecar ─────────────────────────────────────────────
    //
    // Bound during init() to any free local port. Server's address is
    // resolved from the same hostname/port we connected over TCP. We
    // stamp every outbound UDP datagram with the connectionId the
    // server gave us in the ASSIGN_CLIENT_ID packet so it can match
    // datagrams to our TCP-established Connection. Until that arrives
    // we fall back to TCP for everything (connectionId == 0).
    TransportConfig transportConfig_;
    bool usingUdpSession_ = false;
    net::UdpSessionTransport session_;
    net::UdpEndpoint udpEndpoint_;
    net::UdpEndpointAddr serverUdpAddr_;
    std::uint64_t connectionId_ = 0;
    uint16_t udpInputSequence_ = 0; 
    std::uint16_t chatClientSeq_ = 0;

    std::vector<std::vector<uint8_t>> udpRecvQueue_;

    net::FragmentReassembler unreliableReassembler_;

    std::uint32_t reliableHighestSeen_ = 0;
    uint64_t reliableSeenBitmask_ = 0;
    bool reliableHasAny_ = false; 

    bool acceptReliableSequence(std::uint32_t seq);
 
    // ── Phase 6 testing: latency simulator ────────────────────────────────
    //
    // Two FIFO queues — outbound packets that haven't reached the kernel
    // socket yet, and inbound payloads that haven't been delivered to the
    // game thread's dispatch queue yet. Both are drained at the top of
    // each `networkLoop` cycle: any entry whose target counter has passed
    // is sent (or enqueued for dispatch). Both share `stateMutex_` because
    // the existing send/receive paths already hold it; piggy-backing
    // avoids a second mutex.
    //
    // Sized to grow with traffic — typical worst case is 200 ms × 128 Hz
    // INPUT × 1 client + ~32 Hz inbound snapshot stream ≈ 30 entries.

    std::atomic<int> simulatedLatencyMs_{0};

    std::atomic<int> simulatedLossPercent_{0};

    std::mt19937 simLossRng_{};

    bool shouldDropPacketLocked();

    struct DelayedOutbound
    {
        Uint64 sendAtCounter;         
        net::PacketHeader header;     
        std::vector<uint8_t> payload; 
        std::size_t totalBytes;       
    };
    std::deque<DelayedOutbound> simLatOutbound_;

    struct DelayedInbound
    {
        Uint64 deliverAtCounter;      
        std::vector<uint8_t> payload; 
    };
    std::deque<DelayedInbound> simLatInbound_;

    bool sendUdpDelayed(net::PacketHeader hdr, const void* data, int len);

    void recvUdpDelayed(std::vector<uint8_t>&& payload);

    void networkLoop();

    void dispatchMessage(const uint8_t* data, Uint32 size);

    bool applySnapshot(std::uint32_t snapshotTick, const std::uint8_t* bytes, Uint32 size, Uint32 wireSize);
};