@carverjs/multiplayer 0.0.1 → 0.0.2

package/dist/sync.d.ts

@@ -1,6 +1,7 @@
-import { C as CarverTransport, d as Codec, S as SnapshotBuffer, E as EntityState, N as NetworkQuality, e as TickKeeper } from './NetworkManager-nvVAOr1O.js';
-export { f as EntityState2D, g as EntityState3D, h as EventPacket, I as InputPacket, i as SnapshotPacket, j as SyncMode } from './NetworkManager-nvVAOr1O.js';
-import './types-5LHBOW08.js';
+import { C as CarverTransport, e as Codec, S as SnapshotBuffer, E as EntityState, P as PlayerInput, N as NetworkQuality, f as SnapshotListener, g as SnapshotSource, h as TickKeeper, i as PredictionSyncOptions, j as PhysicsStepCallback, k as PredictionWorldDriver, l as ErrorOffset } from './NetworkManager-DH9uGVMg.js';
+export { m as EntityState2D, n as EntityState3D, o as EventPacket, I as InputPacket, p as SnapshotPacket, q as SyncMode } from './NetworkManager-DH9uGVMg.js';
+import { I as InputBuffer } from './InputBuffer-V7XfHbc6.js';
+import './types-hNfCIBzj.js';
 
 /**
  * Layer 1: Event-based messaging over a reliable+ordered channel.
@@ -59,10 +60,11 @@ declare class HostAuthority {
     /**
      * Called every fixed tick by the sync engine.
      * Collects entity states and decides whether to broadcast.
+     * `hostInput` (prediction mode) is embedded in the snapshot packet as `hi`.
      */
-    tick(currentTick: number, entities: Map<string, EntityState>, delta: number): void;
+    tick(currentTick: number, entities: Map<string, EntityState>, delta: number, hostInput?: PlayerInput): void;
     /** Force a keyframe broadcast to all clients (e.g., after host migration) */
-    forceKeyframe(currentTick: number, entities: Map<string, EntityState>): void;
+    forceKeyframe(currentTick: number, entities: Map<string, EntityState>, hostInput?: PlayerInput): void;
     destroy(): void;
     private _broadcastToClient;
 }
@@ -87,6 +89,7 @@ declare class ClientReceiver {
     private _packetCount;
     private _is2D;
     private _fullState;
+    private _snapshotListeners;
     constructor(transport: CarverTransport, codec: Codec, options?: {
         bufferSize?: number;
         method?: "hermite" | "linear";
@@ -103,6 +106,8 @@ declare class ClientReceiver {
     interpolate(renderTime: number): Map<string, EntityState>;
     /** Request a keyframe from the host */
     requestKeyframe(): void;
+    /** Register a listener fired after each snapshot is merged into the full world state */
+    onSnapshot(cb: SnapshotListener): void;
     destroy(): void;
     private _handleSnapshot;
     private _interpolateEntity;
@@ -123,18 +128,21 @@ interface SnapshotSyncOptions {
  * Layer 2: Snapshot interpolation sync engine.
  * Host broadcasts state at fixed intervals, clients interpolate.
  */
-declare class SnapshotSync {
+declare class SnapshotSync implements SnapshotSource {
     private _transport;
     private _hostAuthority;
     private _clientReceiver;
     private _codec;
     private _snapshotBuffer;
+    private _snapshotListeners;
     constructor(transport: CarverTransport, codec: Codec, snapshotBuffer: SnapshotBuffer, options?: SnapshotSyncOptions);
     get isHost(): boolean;
     get hostAuthority(): HostAuthority | null;
     get clientReceiver(): ClientReceiver | null;
     /** Host: called every fixed tick to potentially broadcast state */
-    hostTick(tick: number, entities: Map<string, EntityState>, delta: number): void;
+    hostTick(tick: number, entities: Map<string, EntityState>, delta: number, hostInput?: PlayerInput): void;
+    /** Register a listener fired after each merged snapshot (client side). */
+    onSnapshot(cb: SnapshotListener): void;
     /** Client: called every render frame to interpolate */
     clientInterpolate(renderTime: number): Map<string, EntityState>;
     /** Set interest filter on host authority */
@@ -144,69 +152,145 @@ declare class SnapshotSync {
     /** Handle host migration: switch from host to client mode */
     demoteToClient(options?: SnapshotSyncOptions): void;
     destroy(): void;
+    /** Forward receiver snapshots to registered listeners (survives host migration). */
+    private _attachSnapshotForwarder;
 }
 
-interface PredictionOptions {
-    maxRewindTicks: number;
-    errorSmoothingDecay: number;
-    maxErrorPerFrame: number;
-    snapThreshold: number;
-    lagCompensation: boolean;
-}
 /**
- * Layer 3: Client-side prediction with server reconciliation.
- * Builds on top of Layer 2 (SnapshotSync).
+ * Layer 3: Full-world prediction with full-world rollback.
+ * Ported from LumberNet, built on top of Layer 2 (SnapshotSync) as the
+ * authoritative state channel.
  *
  * Flow:
- *   Client: input -> apply locally (predict) -> store in buffer -> send to host
- *   Host: receive input -> apply to simulation -> broadcast state + lastProcessedInputTick
- *   Client: receive state -> compare with prediction ->
- *           if mismatch: reset to server state + replay unacked inputs -> visual smoothing
+ *   Every peer (host included): broadcast tick-stamped input to ALL peers each
+ *   fixed tick on carver:inputs, simulate EVERY networked entity forward with
+ *   last-known remote inputs (hold-last-input extrapolation).
+ *
+ *   Host: stays authoritative; SnapshotSync broadcasts delta-compressed,
+ *   ACK-driven snapshots with the host's own input embedded (`hi`).
+ *
+ *   Client: on each accepted snapshot, reset ALL networked entities to server
+ *   state, resimulate from serverTick + 1 to localTick replaying per-tick
+ *   inputs for every peer, and convert the visual discontinuity into
+ *   per-entity error offsets decayed per render frame.
+ *
+ * Role is checked dynamically via transport.isHost at every use site (host
+ * migration is best-effort).
  */
+
 declare class PredictionSync {
     private _transport;
-    private _codec;
     private _tickKeeper;
     private _options;
     private _inputChannel;
-    private _stateChannel;
-    private _ackChannel;
-    private _inputBuffer;
-    private _clientLastProcessedTick;
-    private _predictedState;
-    private _errorCorrections;
-    private _serverState;
+    private _inputs;
+    private _currentInput;
+    private _pending;
+    private _errors;
     private _serverTick;
+    private _lastAppliedServerTick;
+    private _worldDriver;
     private _onPhysicsStep;
-    private _currentInput;
-    private _isHost;
-    constructor(transport: CarverTransport, codec: Codec, tickKeeper: TickKeeper, options?: Partial<PredictionOptions>);
-    /** Set the physics step callback (required for rollback re-simulation) */
-    setPhysicsStep(cb: (inputs: Map<string, unknown>, tick: number, isRollback: boolean) => void): void;
-    /** Set the current input for this tick (client-side) */
-    setInput(input: unknown): void;
+    constructor(transport: CarverTransport, tickKeeper: TickKeeper, snapshots: SnapshotSource, options?: PredictionSyncOptions);
+    /** Set the game simulation callback (forward sim + rollback resim). */
+    setPhysicsStep(cb: PhysicsStepCallback): void;
+    /** Set the world driver used for forward stepping and rollback. */
+    setWorldDriver(driver: PredictionWorldDriver): void;
+    /** Set the local player's input. PERSISTS across ticks until replaced. */
+    setInput(input: PlayerInput): void;
+    /** Local input stored at the given tick (neutral fallback). Used by the host to embed `hi`. */
+    getLocalInput(tick: number): PlayerInput;
     /**
-     * Called every fixed tick on the client.
-     * Applies input locally (prediction), buffers it, and sends to host.
+     * Apply the newest pending server snapshot (full-world rollback).
+     * Call once per render frame BEFORE tickKeeper.update().
+     * No-op on host or when nothing is pending.
      */
-    clientTick(tick: number): void;
+    beginFrame(): void;
     /**
-     * Called every fixed tick on the host.
-     * Processes received inputs and broadcasts authoritative state.
+     * Run one forward fixed tick (host AND client): store + broadcast input,
+     * build per-tick input maps, invoke the callback, then step the world.
      */
-    hostTick(tick: number, entities: Map<string, EntityState>, _delta: number): void;
+    tick(tick: number): void;
     /**
-     * Called every render frame on the client to apply visual error smoothing.
-     * Returns the corrected entity states.
+     * Decay stored error offsets and return the portion to ADD to rendered
+     * transforms this frame. Call exactly once per render frame.
      */
-    applyErrorSmoothing(entities: Map<string, EntityState>): Map<string, EntityState>;
-    get predictedState(): Map<string, EntityState>;
+    getRenderErrorOffsets(): Map<string, ErrorOffset>;
+    /** Tick of the newest RECEIVED snapshot. */
     get serverTick(): number;
+    /** Tick of the newest APPLIED (rolled-back) snapshot, 0 initially. */
+    get lastAppliedServerTick(): number;
     destroy(): void;
-    private _setupHostListeners;
-    private _setupClientListeners;
-    private _reconcile;
-    private _computeError;
 }
 
-export { EntityState, EventSync, PredictionSync, SnapshotSync, type SnapshotSyncOptions };
+/**
+ * Rollback — full-world rollback for prediction mode.
+ *
+ * Ported from LumberNet's LumberRollback, adapted to CarverJS entity state
+ * (2D and 3D). On each accepted server snapshot the client:
+ *   1. captures the pre-rollback visual pose (raw physics + accumulated error),
+ *   2. hard-applies server state to EVERY networked entity,
+ *   3. resimulates from serverTick + 1 to localTick replaying per-tick inputs
+ *      (or hard-snaps the tick when drift exceeds maxRewindTicks),
+ *   4. converts the visual discontinuity into per-entity error offsets.
+ *
+ * Pure module: no transport, no React, no three.js. Quaternion math is
+ * hand-rolled below.
+ */
+
+interface Quat {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+/** Hamilton product (a ⊗ b). */
+declare function quatMultiply(a: Quat, b: Quat): Quat;
+/** Conjugate (inputs assumed normalized). */
+declare function quatInvert(q: Quat): Quat;
+/** Normalize; degenerate (near-zero) quaternions return identity. */
+declare function quatNormalize(q: Quat): Quat;
+/** Rotation angle in radians: 2*acos(clamp(|w|, 0, 1)). */
+declare function quatAngle(q: Quat): number;
+/** Scale the rotation angle toward identity by `factor`, preserving the axis. */
+declare function quatScaleAngle(q: Quat, factor: number): Quat;
+interface RollbackParams {
+    /** Tick embedded in the accepted server snapshot. */
+    serverTick: number;
+    /** Authoritative full-world state from the snapshot. */
+    serverState: ReadonlyMap<string, EntityState>;
+    /** Client's current simulation tick. */
+    localTick: number;
+    /** This peer's id (local inputs are replayed from the local ring buffer). */
+    localPeerId: string;
+    /** Input buffer holding local and per-peer tick history. */
+    inputs: InputBuffer;
+    /** Currently accumulated visual error offsets (kept continuous across rollbacks). */
+    currentErrors: ReadonlyMap<string, ErrorOffset>;
+    /** World access for capture/apply/step. */
+    driver: PredictionWorldDriver;
+    /** Game physics-step callback, re-invoked during resimulation. */
+    callback: PhysicsStepCallback | null;
+    /** Fixed timestep in seconds. */
+    dt: number;
+    /** Snap target offset: snap target = serverTick + driftTargetTicks. */
+    driftTargetTicks: number;
+    /** Max |localTick - (serverTick + driftTargetTicks)| before hard tick snap. */
+    maxRewindTicks: number;
+    /** Per-axis positional jump above which correction is suppressed (teleport). */
+    snapThreshold: number;
+}
+interface RollbackResult {
+    /** New local tick (differs from localTick only when a hard snap occurred). */
+    newLocalTick: number;
+    snapped: boolean;
+    /** Per-entity visual error offsets (pre-visual minus post-resim). */
+    errors: Map<string, ErrorOffset>;
+}
+/**
+ * Apply a server snapshot to the whole world and resimulate forward.
+ * Returns the new local tick and per-entity visual error offsets.
+ */
+declare function applyRollback(params: RollbackParams): RollbackResult;
+
+export { EntityState, ErrorOffset, EventSync, PhysicsStepCallback, PlayerInput, PredictionSync, PredictionSyncOptions, PredictionWorldDriver, type Quat, type RollbackParams, type RollbackResult, SnapshotListener, SnapshotSource, SnapshotSync, type SnapshotSyncOptions, applyRollback, quatAngle, quatInvert, quatMultiply, quatNormalize, quatScaleAngle };