@carverjs/multiplayer 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,154 @@
+# @carverjs/multiplayer
+
+[![npm](https://img.shields.io/npm/v/@carverjs/multiplayer)](https://www.npmjs.com/package/@carverjs/multiplayer)
+[![license](https://img.shields.io/npm/l/@carverjs/multiplayer)](https://github.com/MoneyTales/carverjs/blob/main/LICENSE)
+[![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/5ymwfD4hYE)
+
+Serverless peer-to-peer multiplayer for [CarverJS](https://www.npmjs.com/package/@carverjs/core) games. A WebRTC data-channel mesh with pluggable signaling (MQTT or Firebase), lobbies, host authority, and three sync engines — **no game server required**.
+
+> **Beta:** CarverJS is under active development. APIs may change between minor versions until 1.0.
+
+## Install
+
+```bash
+npm install @carverjs/multiplayer
+# optional — Firebase RTDB signaling (MQTT is the zero-config default)
+npm install firebase
+```
+
+Peer dependencies: `@carverjs/core`, `@react-three/fiber`, `react`, `react-dom`. `firebase` is an optional peer, needed only when you choose the Firebase strategy.
+
+## How it works
+
+Signaling (MQTT or Firebase) is used only to introduce peers and relay SDP/ICE. Once the WebRTC connection is established, **all game data flows directly peer-to-peer** over data channels — the signaling backend never sees gameplay traffic. One peer acts as the authoritative host; host migrates automatically if it leaves.
+
+## Quick start
+
+Wrap your game in a provider, join a room, and exchange typed events:
+
+```tsx
+import {
+  MultiplayerProvider, MultiplayerBridge,
+  useRoom, usePlayers, useNetworkEvents,
+} from "@carverjs/multiplayer";
+import { Game, World } from "@carverjs/core/components";
+
+function App() {
+  return (
+    // Zero-config: free public MQTT brokers handle signaling
+    <MultiplayerProvider appId="my-game">
+      <Game mode="2d">
+        <MultiplayerBridge>
+          <World>
+            <Lobby />
+          </World>
+        </MultiplayerBridge>
+      </Game>
+    </MultiplayerProvider>
+  );
+}
+
+function Lobby() {
+  const room = useRoom("room-code-1234", { displayName: "Ada" });
+  const { players, self } = usePlayers();
+  const { broadcast, onEvent } = useNetworkEvents();
+
+  // room.connectionState, room.isHost, room.selfId, room.leave(), ...
+  return <span>{players.length} players · {room.isHost ? "host" : "client"}</span>;
+}
+```
+
+`MultiplayerBridge` connects the engine's render loop to the network layer; place it inside `<Game>` and around the scene that uses sync hooks.
+
+## Signaling strategies
+
+```tsx
+// Free, zero-config (default): public MQTT brokers
+<MultiplayerProvider appId="my-game">
+
+// Firebase Realtime Database (bring your own project)
+<MultiplayerProvider
+  appId="my-game"
+  strategy={{ type: "firebase", databaseURL: "https://your-project.firebaseio.com" }}
+>
+```
+
+## STUN / TURN
+
+Defaults to public STUN. Add a TURN relay so peers behind restrictive NATs or firewalls can still connect:
+
+```tsx
+<MultiplayerProvider
+  appId="my-game"
+  iceServers={[
+    { urls: "stun:stun.cloudflare.com:3478" },
+    { urls: "turn:turn.cloudflare.com:3478", username: "...", credential: "..." },
+  ]}
+>
+```
+
+TURN is only used when a direct connection fails. For same-network testing, STUN alone is enough.
+
+## Sync modes
+
+`useMultiplayer({ mode })` selects how world state is replicated:
+
+| Mode | Use it for | How |
+| --- | --- | --- |
+| `events` | turn-based, sandbox, chat, infrequent state changes | typed messages over a reliable, ordered channel |
+| `snapshot` | real-time movement | host broadcasts delta-compressed snapshots; clients interpolate |
+| `prediction` | fast-paced action | client-side prediction with server reconciliation and rollback |
+
+```tsx
+import { useMultiplayer } from "@carverjs/multiplayer";
+
+function Scene() {
+  useMultiplayer({ mode: "snapshot", tickRate: 60 });
+  // ... actors marked networked are replicated automatically
+}
+```
+
+## Hooks
+
+| Hook | Purpose |
+| --- | --- |
+| `useRoom(roomId, opts)` | Join / leave a room; exposes connection state, host, and self id. |
+| `useLobby()` | Browse advertised rooms. |
+| `usePlayers()` | Live player list plus `self`. |
+| `useHost()` | Host-only room controls — room state, lock, kick, host transfer. |
+| `useMultiplayer({ mode })` | Drive the sync engine for a scene. |
+| `useNetworkEvents()` | Typed `broadcast` / `sendEvent` / `onEvent` messaging. |
+| `useNetworkState()` | Networked spawn / despawn helpers. |
+
+## Host authority & migration
+
+Exactly one peer is the authoritative host. If it disconnects, the engine migrates host to another peer automatically, and host election is deterministic and consistent across all peers.
+
+To pin a specific peer as host — for example the room creator that owns the world — advertise a host priority in player metadata. The lowest priority wins; peers that advertise none rank last (preserving the default lowest-peer-id election among them):
+
+```tsx
+useRoom(roomId, {
+  displayName: name,
+  playerMetadata: { hostPriority: isCreator ? 0 : 1 },
+});
+```
+
+## Advanced exports
+
+For lower-level control, the package also exports:
+
+- `MqttStrategy`, `FirebaseStrategy` — construct or inject a signaling strategy directly.
+- `NetworkSimulator` — inject artificial latency and packet loss during development.
+- `InterestManager` — area-of-interest filtering for large worlds.
+- `InputBuffer`, `computeJustPressed` — input history and edge detection for prediction.
+- `DebugOverlay` — on-screen network stats.
+
+## Links
+
+- Documentation: [docs.carverjs.dev](https://docs.carverjs.dev)
+- Community: [Discord](https://discord.gg/5ymwfD4hYE)
+- Issues: [github.com/MoneyTales/carverjs/issues](https://github.com/MoneyTales/carverjs/issues)
+
+## License
+
+[MIT](https://github.com/MoneyTales/carverjs/blob/main/LICENSE) — MoneyTales EduTech Private Limited

package/dist/InputBuffer-J6XT_Tt0.d.mts

@@ -0,0 +1,61 @@
+import { P as PlayerInput } from './NetworkManager-D-DxFgdM.mjs';
+
+/**
+ * InputBuffer — unified ring-buffer for local and peer inputs.
+ *
+ * Ported from LumberNet's LumberInputBuffer. Stores:
+ *   - local player tick-keyed inputs (storeTick / getTick / hasTick)
+ *   - last-received input per remote peer (setRemote / getRemote / allRemotes)
+ *   - per-peer tick-keyed inputs for accurate rollback resimulation (getRemoteAtTick)
+ *
+ * Generic over per-tick payload I. Caller supplies the neutral payload.
+ */
+
+declare class InputBuffer<I extends PlayerInput = PlayerInput> {
+    private readonly _historySize;
+    private readonly _neutral;
+    /** Local player tick-keyed inputs (ring buffer). */
+    private readonly _local;
+    /** Last-received input per remote peer. */
+    private readonly _remotes;
+    /** Per-peer tick-keyed inputs for accurate rollback re-simulation. */
+    private readonly _peerTicks;
+    constructor(neutralInput: I, historySize?: number);
+    /** Record a snapshot of the local input at the given tick. Evicts the entry exactly historySize back. */
+    storeTick(tick: number, input: I): void;
+    /** Return the local input at `tick`, or a neutral copy if out of range. */
+    getTick(tick: number): I;
+    /** True if we have a stored local input for this tick (used to avoid spurious justPressed after snap/rejoin). */
+    hasTick(tick: number): boolean;
+    /** Neutral payload with every boolean field forced false (use for justPressed when prev tick is unknown). */
+    getJustPressedZero(): I;
+    /**
+     * Record a remote peer's input. If `tick` is given (the sender's local tick),
+     * also store it in the per-peer ring buffer for rollback.
+     */
+    setRemote(peerId: string, input: I, tick?: number): void;
+    /** Last-known input for a peer, or a neutral copy if never received. */
+    getRemote(peerId: string): I;
+    /** Snapshot of all remote peers' last-known inputs (shallow copy of the map). */
+    allRemotes(): Map<string, I>;
+    /**
+     * Return a peer's exact input at the given tick (for rollback accuracy),
+     * falling back to their last-known input when history does not reach that far.
+     */
+    getRemoteAtTick(peerId: string, tick: number): I;
+    /** Override the last-known input for a peer (does NOT touch tick history). */
+    overrideRemote(peerId: string, input: I): void;
+    /** Number of currently tracked remote peers. */
+    get peerCount(): number;
+    /** Iterate tracked peer IDs. */
+    peerIds(): IterableIterator<string>;
+    /**
+     * Keep only these peer IDs; remove any other remotes (e.g. after leave/rejoin).
+     * Call when the room's peer list changes so stale peers stop receiving input.
+     */
+    setPeerIds(peerIds: ReadonlySet<string> | string[]): void;
+    /** Clear local history, remote last-known inputs, and per-peer tick history. */
+    clear(): void;
+}
+
+export { InputBuffer as I };

package/dist/InputBuffer-V7XfHbc6.d.ts

@@ -0,0 +1,61 @@
+import { P as PlayerInput } from './NetworkManager-DH9uGVMg.js';
+
+/**
+ * InputBuffer — unified ring-buffer for local and peer inputs.
+ *
+ * Ported from LumberNet's LumberInputBuffer. Stores:
+ *   - local player tick-keyed inputs (storeTick / getTick / hasTick)
+ *   - last-received input per remote peer (setRemote / getRemote / allRemotes)
+ *   - per-peer tick-keyed inputs for accurate rollback resimulation (getRemoteAtTick)
+ *
+ * Generic over per-tick payload I. Caller supplies the neutral payload.
+ */
+
+declare class InputBuffer<I extends PlayerInput = PlayerInput> {
+    private readonly _historySize;
+    private readonly _neutral;
+    /** Local player tick-keyed inputs (ring buffer). */
+    private readonly _local;
+    /** Last-received input per remote peer. */
+    private readonly _remotes;
+    /** Per-peer tick-keyed inputs for accurate rollback re-simulation. */
+    private readonly _peerTicks;
+    constructor(neutralInput: I, historySize?: number);
+    /** Record a snapshot of the local input at the given tick. Evicts the entry exactly historySize back. */
+    storeTick(tick: number, input: I): void;
+    /** Return the local input at `tick`, or a neutral copy if out of range. */
+    getTick(tick: number): I;
+    /** True if we have a stored local input for this tick (used to avoid spurious justPressed after snap/rejoin). */
+    hasTick(tick: number): boolean;
+    /** Neutral payload with every boolean field forced false (use for justPressed when prev tick is unknown). */
+    getJustPressedZero(): I;
+    /**
+     * Record a remote peer's input. If `tick` is given (the sender's local tick),
+     * also store it in the per-peer ring buffer for rollback.
+     */
+    setRemote(peerId: string, input: I, tick?: number): void;
+    /** Last-known input for a peer, or a neutral copy if never received. */
+    getRemote(peerId: string): I;
+    /** Snapshot of all remote peers' last-known inputs (shallow copy of the map). */
+    allRemotes(): Map<string, I>;
+    /**
+     * Return a peer's exact input at the given tick (for rollback accuracy),
+     * falling back to their last-known input when history does not reach that far.
+     */
+    getRemoteAtTick(peerId: string, tick: number): I;
+    /** Override the last-known input for a peer (does NOT touch tick history). */
+    overrideRemote(peerId: string, input: I): void;
+    /** Number of currently tracked remote peers. */
+    get peerCount(): number;
+    /** Iterate tracked peer IDs. */
+    peerIds(): IterableIterator<string>;
+    /**
+     * Keep only these peer IDs; remove any other remotes (e.g. after leave/rejoin).
+     * Call when the room's peer list changes so stale peers stop receiving input.
+     */
+    setPeerIds(peerIds: ReadonlySet<string> | string[]): void;
+    /** Clear local history, remote last-known inputs, and per-peer tick history. */
+    clear(): void;
+}
+
+export { InputBuffer as I };

package/dist/{NetworkManager-nvVAOr1O.d.ts → NetworkManager-D-DxFgdM.d.mts}

@@ -1,4 +1,4 @@
-import { S as SignalingStrategy } from './types-5LHBOW08.js';
+import { S as SignalingStrategy } from './types-hNfCIBzj.mjs';
 
 type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'migrating' | 'reconnecting';
 type RoomState = 'lobby' | 'playing' | 'ended';
@@ -108,15 +108,68 @@ interface EntityState3D {
     c?: Record<string, unknown>;
 }
 type EntityState = EntityState2D | EntityState3D;
+/** Flat per-tick input payload. Booleans get edge detection; numbers pass through. */
+type PlayerInput = Record<string, boolean | number | undefined>;
+/**
+ * Game simulation callback for prediction mode.
+ * Keys of both maps are peer ids (the local player appears under transport.peerId).
+ * Invoked once per fixed tick (isRollback=false) and once per resimulated tick (isRollback=true).
+ */
+type PhysicsStepCallback = (inputs: Map<string, PlayerInput>, justPressed: Map<string, PlayerInput>, tick: number, isRollback: boolean, dt: number) => void;
+/** Per-entity visual error offset produced by rollback. 2D uses x/y/a (z=0, q=identity); 3D uses x/y/z + quaternion (a=0). */
+interface ErrorOffset {
+    x: number;
+    y: number;
+    z: number;
+    a: number;
+    qx: number;
+    qy: number;
+    qz: number;
+    qw: number;
+}
+/** World access used by PredictionSync for forward stepping and rollback. */
+interface PredictionWorldDriver {
+    /** Read current state of every networked entity (raw physics, no error offsets). */
+    captureState(): Map<string, EntityState>;
+    /** Hard-apply states (position, rotation, velocities) to actors and rigid bodies, waking them. Skips tombstones. */
+    applyState(entities: Iterable<EntityState>): void;
+    /** Optional: step the physics world one fixed tick. If omitted, the game steps inside onPhysicsStep. */
+    stepWorld?(): void;
+}
+interface PredictionSyncOptions {
+    /** Max |localTick - (serverTick + driftTargetTicks)| before hard tick snap (no resim). Default 15. */
+    maxRewindTicks?: number;
+    /** Per-axis positional jump (units) above which a rollback error vector is suppressed (intentional teleport). Default 150. */
+    snapThreshold?: number;
+    /** Multiplicative error decay per render frame. Default 0.85. */
+    errorDecay?: number;
+    /** Max positional correction magnitude applied per render frame. 0 = disabled (full decaying error applied). Default 0. */
+    maxErrorPerFrame?: number;
+    /** Neutral input payload used as fallback for unknown ticks/peers. Default {}. */
+    neutralInput?: PlayerInput;
+    /** Tick-history ring size for local and per-peer inputs. Default 120. */
+    inputHistorySize?: number;
+    /** Rollback snap target offset: snap target = serverTick + driftTargetTicks. Default 4. */
+    driftTargetTicks?: number;
+}
+/** Fired by ClientReceiver after each snapshot is merged into the full world state. */
+type SnapshotListener = (tick: number, entities: Map<string, EntityState>, hostInput: PlayerInput | undefined) => void;
+/** Minimal structural source of merged snapshots (implemented by SnapshotSync). */
+interface SnapshotSource {
+    onSnapshot(cb: SnapshotListener): void;
+}
 interface SnapshotPacket {
     t: number;
     b: number;
     s: Uint8Array;
-    hi?: unknown;
+    hi?: PlayerInput;
 }
 interface InputPacket {
+    /** Sender's local tick. */
     t: number;
-    i: unknown;
+    /** Per-tick input payload. */
+    i: PlayerInput;
+    /** Sender peerId (informational; receivers MUST key by transport-provided peerId). */
     p: string;
 }
 interface EventPacket {
@@ -173,13 +226,7 @@ interface UseMultiplayerOptions {
         velocity?: number;
         custom?: 'strict' | number;
     };
-    prediction?: {
-        maxRewindTicks?: number;
-        errorSmoothingDecay?: number;
-        maxErrorPerFrame?: number;
-        snapThreshold?: number;
-        lagCompensation?: boolean;
-    };
+    prediction?: PredictionSyncOptions;
     interpolation?: {
         bufferSize?: number;
         method?: 'hermite' | 'linear';
@@ -197,7 +244,9 @@ interface UseMultiplayerOptions {
         simulatedPacketLoss?: number;
         logLevel?: 'none' | 'error' | 'warn' | 'verbose';
     };
-    onPhysicsStep?: (inputs: Map<string, unknown>, tick: number, isRollback: boolean) => void;
+    /** Optional: step the physics world one fixed tick. Used for both forward sim and rollback resim. */
+    stepWorld?: () => void;
+    onPhysicsStep?: PhysicsStepCallback;
 }
 interface MultiplayerContextValue {
     appId: string;
@@ -241,6 +290,8 @@ declare class TickKeeper {
     get drift(): number;
     /** Update server tick from received snapshot */
     setServerTick(serverTick: number): void;
+    /** Hard-set the local tick (prediction rollback snap). Does not touch the accumulator. */
+    snapTick(tick: number): void;
     /**
      * Accumulate time and return the number of fixed ticks to process.
      * Call this once per render frame with the raw frame delta.
@@ -302,13 +353,14 @@ declare class Codec {
      * Returns null if nothing changed.
      */
     computeDelta(current: Map<string, EntityState>, baseline: Map<string, EntityState> | undefined): EntityState[] | null;
-    /** Serialize a delta snapshot packet */
-    serializeDelta(tick: number, baseTick: number, current: Map<string, EntityState>, baseline: Map<string, EntityState> | undefined): Uint8Array | null;
+    /** Serialize a delta snapshot packet (optionally embedding the host's own input as `hi`) */
+    serializeDelta(tick: number, baseTick: number, current: Map<string, EntityState>, baseline: Map<string, EntityState> | undefined, hostInput?: PlayerInput): Uint8Array | null;
     /** Deserialize a snapshot packet */
     deserializePacket(data: Uint8Array): {
         tick: number;
         baseTick: number;
         entities: EntityState[];
+        hostInput: PlayerInput | undefined;
     };
     private _hasChanged;
     private _quantizeEntity;
@@ -366,4 +418,4 @@ declare class NetworkManager {
     private _notifyRoomListeners;
 }
 
-export { type CarverTransport as C, type EntityState as E, type InputPacket as I, type JoinOptions as J, type MultiplayerContextValue as M, type NetworkQuality as N, type Player as P, type Room as R, SnapshotBuffer as S, type TransportConfig as T, type UseRoomOptions as U, type ChannelOptions as a, type CarverChannel as b, type RoomState as c, Codec as d, TickKeeper as e, type EntityState2D as f, type EntityState3D as g, type EventPacket as h, type SnapshotPacket as i, type SyncMode as j, NetworkManager as k, type ConnectionState as l, type CarverMultiplayerError as m, type UseLobbyOptions as n, type RoomConfig as o, type UseMultiplayerOptions as p, type CarverErrorCode as q };
+export { type CarverTransport as C, type EntityState as E, type InputPacket as I, type JoinOptions as J, type MultiplayerContextValue as M, type NetworkQuality as N, type PlayerInput as P, type Room as R, SnapshotBuffer as S, type TransportConfig as T, type UseRoomOptions as U, type Player as a, type ChannelOptions as b, type CarverChannel as c, type RoomState as d, Codec as e, type SnapshotListener as f, type SnapshotSource as g, TickKeeper as h, type PredictionSyncOptions as i, type PhysicsStepCallback as j, type PredictionWorldDriver as k, type ErrorOffset as l, type EntityState2D as m, type EntityState3D as n, type EventPacket as o, type SnapshotPacket as p, type SyncMode as q, NetworkManager as r, type ConnectionState as s, type CarverMultiplayerError as t, type UseLobbyOptions as u, type RoomConfig as v, type UseMultiplayerOptions as w, type CarverErrorCode as x };

package/dist/{NetworkManager-DrKM2tEx.d.mts → NetworkManager-DH9uGVMg.d.ts}

@@ -1,4 +1,4 @@
-import { S as SignalingStrategy } from './types-5LHBOW08.mjs';
+import { S as SignalingStrategy } from './types-hNfCIBzj.js';
 
 type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'migrating' | 'reconnecting';
 type RoomState = 'lobby' | 'playing' | 'ended';
@@ -108,15 +108,68 @@ interface EntityState3D {
     c?: Record<string, unknown>;
 }
 type EntityState = EntityState2D | EntityState3D;
+/** Flat per-tick input payload. Booleans get edge detection; numbers pass through. */
+type PlayerInput = Record<string, boolean | number | undefined>;
+/**
+ * Game simulation callback for prediction mode.
+ * Keys of both maps are peer ids (the local player appears under transport.peerId).
+ * Invoked once per fixed tick (isRollback=false) and once per resimulated tick (isRollback=true).
+ */
+type PhysicsStepCallback = (inputs: Map<string, PlayerInput>, justPressed: Map<string, PlayerInput>, tick: number, isRollback: boolean, dt: number) => void;
+/** Per-entity visual error offset produced by rollback. 2D uses x/y/a (z=0, q=identity); 3D uses x/y/z + quaternion (a=0). */
+interface ErrorOffset {
+    x: number;
+    y: number;
+    z: number;
+    a: number;
+    qx: number;
+    qy: number;
+    qz: number;
+    qw: number;
+}
+/** World access used by PredictionSync for forward stepping and rollback. */
+interface PredictionWorldDriver {
+    /** Read current state of every networked entity (raw physics, no error offsets). */
+    captureState(): Map<string, EntityState>;
+    /** Hard-apply states (position, rotation, velocities) to actors and rigid bodies, waking them. Skips tombstones. */
+    applyState(entities: Iterable<EntityState>): void;
+    /** Optional: step the physics world one fixed tick. If omitted, the game steps inside onPhysicsStep. */
+    stepWorld?(): void;
+}
+interface PredictionSyncOptions {
+    /** Max |localTick - (serverTick + driftTargetTicks)| before hard tick snap (no resim). Default 15. */
+    maxRewindTicks?: number;
+    /** Per-axis positional jump (units) above which a rollback error vector is suppressed (intentional teleport). Default 150. */
+    snapThreshold?: number;
+    /** Multiplicative error decay per render frame. Default 0.85. */
+    errorDecay?: number;
+    /** Max positional correction magnitude applied per render frame. 0 = disabled (full decaying error applied). Default 0. */
+    maxErrorPerFrame?: number;
+    /** Neutral input payload used as fallback for unknown ticks/peers. Default {}. */
+    neutralInput?: PlayerInput;
+    /** Tick-history ring size for local and per-peer inputs. Default 120. */
+    inputHistorySize?: number;
+    /** Rollback snap target offset: snap target = serverTick + driftTargetTicks. Default 4. */
+    driftTargetTicks?: number;
+}
+/** Fired by ClientReceiver after each snapshot is merged into the full world state. */
+type SnapshotListener = (tick: number, entities: Map<string, EntityState>, hostInput: PlayerInput | undefined) => void;
+/** Minimal structural source of merged snapshots (implemented by SnapshotSync). */
+interface SnapshotSource {
+    onSnapshot(cb: SnapshotListener): void;
+}
 interface SnapshotPacket {
     t: number;
     b: number;
     s: Uint8Array;
-    hi?: unknown;
+    hi?: PlayerInput;
 }
 interface InputPacket {
+    /** Sender's local tick. */
     t: number;
-    i: unknown;
+    /** Per-tick input payload. */
+    i: PlayerInput;
+    /** Sender peerId (informational; receivers MUST key by transport-provided peerId). */
     p: string;
 }
 interface EventPacket {
@@ -173,13 +226,7 @@ interface UseMultiplayerOptions {
         velocity?: number;
         custom?: 'strict' | number;
     };
-    prediction?: {
-        maxRewindTicks?: number;
-        errorSmoothingDecay?: number;
-        maxErrorPerFrame?: number;
-        snapThreshold?: number;
-        lagCompensation?: boolean;
-    };
+    prediction?: PredictionSyncOptions;
     interpolation?: {
         bufferSize?: number;
         method?: 'hermite' | 'linear';
@@ -197,7 +244,9 @@ interface UseMultiplayerOptions {
         simulatedPacketLoss?: number;
         logLevel?: 'none' | 'error' | 'warn' | 'verbose';
     };
-    onPhysicsStep?: (inputs: Map<string, unknown>, tick: number, isRollback: boolean) => void;
+    /** Optional: step the physics world one fixed tick. Used for both forward sim and rollback resim. */
+    stepWorld?: () => void;
+    onPhysicsStep?: PhysicsStepCallback;
 }
 interface MultiplayerContextValue {
     appId: string;
@@ -241,6 +290,8 @@ declare class TickKeeper {
     get drift(): number;
     /** Update server tick from received snapshot */
     setServerTick(serverTick: number): void;
+    /** Hard-set the local tick (prediction rollback snap). Does not touch the accumulator. */
+    snapTick(tick: number): void;
     /**
      * Accumulate time and return the number of fixed ticks to process.
      * Call this once per render frame with the raw frame delta.
@@ -302,13 +353,14 @@ declare class Codec {
      * Returns null if nothing changed.
      */
     computeDelta(current: Map<string, EntityState>, baseline: Map<string, EntityState> | undefined): EntityState[] | null;
-    /** Serialize a delta snapshot packet */
-    serializeDelta(tick: number, baseTick: number, current: Map<string, EntityState>, baseline: Map<string, EntityState> | undefined): Uint8Array | null;
+    /** Serialize a delta snapshot packet (optionally embedding the host's own input as `hi`) */
+    serializeDelta(tick: number, baseTick: number, current: Map<string, EntityState>, baseline: Map<string, EntityState> | undefined, hostInput?: PlayerInput): Uint8Array | null;
     /** Deserialize a snapshot packet */
     deserializePacket(data: Uint8Array): {
         tick: number;
         baseTick: number;
         entities: EntityState[];
+        hostInput: PlayerInput | undefined;
     };
     private _hasChanged;
     private _quantizeEntity;
@@ -366,4 +418,4 @@ declare class NetworkManager {
     private _notifyRoomListeners;
 }
 
-export { type CarverTransport as C, type EntityState as E, type InputPacket as I, type JoinOptions as J, type MultiplayerContextValue as M, type NetworkQuality as N, type Player as P, type Room as R, SnapshotBuffer as S, type TransportConfig as T, type UseRoomOptions as U, type ChannelOptions as a, type CarverChannel as b, type RoomState as c, Codec as d, TickKeeper as e, type EntityState2D as f, type EntityState3D as g, type EventPacket as h, type SnapshotPacket as i, type SyncMode as j, NetworkManager as k, type ConnectionState as l, type CarverMultiplayerError as m, type UseLobbyOptions as n, type RoomConfig as o, type UseMultiplayerOptions as p, type CarverErrorCode as q };
+export { type CarverTransport as C, type EntityState as E, type InputPacket as I, type JoinOptions as J, type MultiplayerContextValue as M, type NetworkQuality as N, type PlayerInput as P, type Room as R, SnapshotBuffer as S, type TransportConfig as T, type UseRoomOptions as U, type Player as a, type ChannelOptions as b, type CarverChannel as c, type RoomState as d, Codec as e, type SnapshotListener as f, type SnapshotSource as g, TickKeeper as h, type PredictionSyncOptions as i, type PhysicsStepCallback as j, type PredictionWorldDriver as k, type ErrorOffset as l, type EntityState2D as m, type EntityState3D as n, type EventPacket as o, type SnapshotPacket as p, type SyncMode as q, NetworkManager as r, type ConnectionState as s, type CarverMultiplayerError as t, type UseLobbyOptions as u, type RoomConfig as v, type UseMultiplayerOptions as w, type CarverErrorCode as x };

package/dist/{chunk-UD6FDZMX.mjs → chunk-GOTAQDBJ.mjs}

@@ -76,6 +76,7 @@ var MqttStrategy = class {
     this._peerExpiryTimer = null;
     this._lobbySubscribed = false;
     this._destroyed = false;
+    this._lastAnnouncement = null;
     this.selfId = generatePeerId();
     this._appId = appId;
     this._config = config;
@@ -141,9 +142,19 @@ var MqttStrategy = class {
       removeFromArray(this._onLobby, cb);
     };
   }
+  updateRoomOccupancy(roomId, playerCount, state) {
+    const ann = this._lastAnnouncement;
+    if (!ann || ann.roomId !== roomId || !this._client) return;
+    ann.playerCount = playerCount;
+    if (state) ann.state = state;
+    ann.lastSeen = Date.now();
+    const topic = mqttTopics(this._appId, roomId, "").roomLobbyEntry;
+    this._client.publish(topic, JSON.stringify(ann), { retain: true, qos: 1 });
+  }
   announceRoom(announcement) {
     if (!this._client) return;
     const topic = mqttTopics(this._appId, announcement.roomId, "").roomLobbyEntry;
+    this._lastAnnouncement = announcement;
     announcement.lastSeen = Date.now();
     this._client.publish(topic, JSON.stringify(announcement), { retain: true, qos: 1 });
     if (this._lobbyAnnounceTimer) clearInterval(this._lobbyAnnounceTimer);
@@ -341,6 +352,8 @@ var FirebaseStrategy = class {
     // State
     this._knownPeers = /* @__PURE__ */ new Set();
     this._lobbyAnnounceTimer = null;
+    this._lastAnnouncement = null;
+    this._lobbyWired = false;
     this._destroyed = false;
     this.selfId = generatePeerId();
     this._appId = appId;
@@ -356,7 +369,7 @@ var FirebaseStrategy = class {
     this._joinGeneration++;
     this._roomId = roomId;
     this._peerMeta = peerMeta;
-    const { ref, set, onChildAdded, onChildRemoved, onDisconnect, remove } = this._fb;
+    const { ref, set, onChildAdded, onChildRemoved, onDisconnect, onValue, remove } = this._fb;
     const paths = firebasePaths(this._appId, roomId, this.selfId);
     await remove(ref(this._db, paths.peerSignalInbox)).catch(() => {
     });
@@ -367,6 +380,18 @@ var FirebaseStrategy = class {
       ts: Date.now()
     });
     onDisconnect(presenceRef).remove();
+    const generation = this._joinGeneration;
+    const connectedRef = ref(this._db, ".info/connected");
+    const connectedUnsub = onValue(connectedRef, (snap) => {
+      if (snap.val() !== true) return;
+      if (this._destroyed || this._joinGeneration !== generation || this._roomId !== roomId) return;
+      onDisconnect(presenceRef).remove().then(() => {
+        if (this._destroyed || this._joinGeneration !== generation || this._roomId !== roomId) return;
+        return set(presenceRef, { peerId: this.selfId, meta: peerMeta, ts: Date.now() });
+      }).catch(() => {
+      });
+    });
+    this._listeners.push(() => connectedUnsub());
     const peersRef = ref(this._db, paths.peers);
     const addedUnsub = onChildAdded(peersRef, (snapshot) => {
       const data = snapshot.val();
@@ -429,6 +454,12 @@ var FirebaseStrategy = class {
   }
   subscribeToLobby(cb) {
     this._onLobby.push(cb);
+    if (this._lobbyWired) {
+      return () => {
+        removeFromArray(this._onLobby, cb);
+      };
+    }
+    this._lobbyWired = true;
     this._ensureInit().then(() => {
       if (!this._db || !this._fb || this._destroyed) return;
       const { ref, onValue } = this._fb;
@@ -456,14 +487,25 @@ var FirebaseStrategy = class {
     if (!this._db || !this._fb) return;
     const { ref, set } = this._fb;
     const paths = firebasePaths(this._appId, announcement.roomId, "");
+    this._lastAnnouncement = announcement;
     announcement.lastSeen = Date.now();
-    set(ref(this._db, paths.roomLobbyEntry), announcement);
+    set(ref(this._db, paths.roomLobbyEntry), sanitizeForFirebase(announcement));
     if (this._lobbyAnnounceTimer) clearInterval(this._lobbyAnnounceTimer);
     this._lobbyAnnounceTimer = setInterval(() => {
       announcement.lastSeen = Date.now();
-      set(ref(this._db, paths.roomLobbyEntry), announcement);
+      set(ref(this._db, paths.roomLobbyEntry), sanitizeForFirebase(announcement));
     }, ROOM_ANNOUNCE_INTERVAL_MS);
   }
+  updateRoomOccupancy(roomId, playerCount, state) {
+    const ann = this._lastAnnouncement;
+    if (!ann || ann.roomId !== roomId || !this._db || !this._fb) return;
+    ann.playerCount = playerCount;
+    if (state) ann.state = state;
+    ann.lastSeen = Date.now();
+    const { ref, set } = this._fb;
+    const paths = firebasePaths(this._appId, roomId, "");
+    set(ref(this._db, paths.roomLobbyEntry), sanitizeForFirebase(ann));
+  }
   removeRoomAnnouncement(roomId) {
     if (!this._db || !this._fb) return;
     const { ref, remove } = this._fb;
@@ -566,6 +608,7 @@ function sanitizeForFirebase(obj) {
   if (typeof obj === "object" && obj !== null) {
     const result = {};
     for (const [key, value] of Object.entries(obj)) {
+      if (value === void 0) continue;
       result[key] = value === null ? "__null__" : sanitizeForFirebase(value);
     }
     return result;
@@ -578,4 +621,4 @@ export {
   MqttStrategy,
   FirebaseStrategy
 };
-//# sourceMappingURL=chunk-UD6FDZMX.mjs.map
+//# sourceMappingURL=chunk-GOTAQDBJ.mjs.map