@watchtower-sdk/core 0.2.1 → 0.3.0

package/dist/index.d.mts

@@ -211,6 +211,14 @@ interface SyncOptions {
     tickRate?: number;
     /** Enable interpolation for remote entities (default: true) */
     interpolate?: boolean;
+    /** Interpolation delay in ms - how far "in the past" to render others (default: 100) */
+    interpolationDelay?: number;
+    /** Jitter buffer size in ms - smooths network variance (default: 50) */
+    jitterBuffer?: number;
+    /** Enable auto-reconnection on disconnect (default: true) */
+    autoReconnect?: boolean;
+    /** Max reconnection attempts (default: 10) */
+    maxReconnectAttempts?: number;
 }
 interface JoinOptions {
     /** Create room if it doesn't exist */
@@ -268,9 +276,15 @@ declare class Sync<T extends Record<string, unknown>> {
     private _roomId;
     private ws;
     private syncInterval;
+    private interpolationInterval;
     private lastSentState;
-    private interpolationTargets;
     private listeners;
+    private snapshots;
+    private jitterQueue;
+    private reconnectAttempts;
+    private reconnectTimeout;
+    private lastJoinOptions;
+    private isReconnecting;
     constructor(state: T, config: Required<WatchtowerConfig>, options?: SyncOptions);
     /**
      * Join a room - your state will sync with everyone in this room
@@ -283,6 +297,12 @@ declare class Sync<T extends Record<string, unknown>> {
      * Leave the current room
      */
     leave(): Promise<void>;
+    /**
+     * Send a one-off message to all players in the room
+     *
+     * @param data - Any JSON-serializable data
+     */
+    broadcast(data: unknown): void;
     /**
      * Create a new room and join it
      *
@@ -297,7 +317,7 @@ declare class Sync<T extends Record<string, unknown>> {
     /**
      * Subscribe to sync events
      */
-    on(event: 'join' | 'leave' | 'error' | 'connected' | 'disconnected', callback: Function): void;
+    on(event: 'join' | 'leave' | 'error' | 'connected' | 'disconnected' | 'reconnecting' | 'reconnected' | 'message', callback: Function): void;
     /**
      * Unsubscribe from sync events
      */
@@ -307,13 +327,20 @@ declare class Sync<T extends Record<string, unknown>> {
     private handleMessage;
     private applyFullState;
     private applyPlayerState;
+    private addSnapshot;
+    private applyStateDirect;
     private removePlayer;
+    private attemptReconnect;
     private clearRemotePlayers;
     private findPlayersKey;
     private startSyncLoop;
+    private startInterpolationLoop;
+    private stopInterpolationLoop;
+    private processJitterQueue;
     private stopSyncLoop;
     private syncMyState;
     private updateInterpolation;
+    private lerpState;
     private generateRoomCode;
     private getHeaders;
 }

package/dist/index.d.ts

@@ -211,6 +211,14 @@ interface SyncOptions {
     tickRate?: number;
     /** Enable interpolation for remote entities (default: true) */
     interpolate?: boolean;
+    /** Interpolation delay in ms - how far "in the past" to render others (default: 100) */
+    interpolationDelay?: number;
+    /** Jitter buffer size in ms - smooths network variance (default: 50) */
+    jitterBuffer?: number;
+    /** Enable auto-reconnection on disconnect (default: true) */
+    autoReconnect?: boolean;
+    /** Max reconnection attempts (default: 10) */
+    maxReconnectAttempts?: number;
 }
 interface JoinOptions {
     /** Create room if it doesn't exist */
@@ -268,9 +276,15 @@ declare class Sync<T extends Record<string, unknown>> {
     private _roomId;
     private ws;
     private syncInterval;
+    private interpolationInterval;
     private lastSentState;
-    private interpolationTargets;
     private listeners;
+    private snapshots;
+    private jitterQueue;
+    private reconnectAttempts;
+    private reconnectTimeout;
+    private lastJoinOptions;
+    private isReconnecting;
     constructor(state: T, config: Required<WatchtowerConfig>, options?: SyncOptions);
     /**
      * Join a room - your state will sync with everyone in this room
@@ -283,6 +297,12 @@ declare class Sync<T extends Record<string, unknown>> {
      * Leave the current room
      */
     leave(): Promise<void>;
+    /**
+     * Send a one-off message to all players in the room
+     *
+     * @param data - Any JSON-serializable data
+     */
+    broadcast(data: unknown): void;
     /**
      * Create a new room and join it
      *
@@ -297,7 +317,7 @@ declare class Sync<T extends Record<string, unknown>> {
     /**
      * Subscribe to sync events
      */
-    on(event: 'join' | 'leave' | 'error' | 'connected' | 'disconnected', callback: Function): void;
+    on(event: 'join' | 'leave' | 'error' | 'connected' | 'disconnected' | 'reconnecting' | 'reconnected' | 'message', callback: Function): void;
     /**
      * Unsubscribe from sync events
      */
@@ -307,13 +327,20 @@ declare class Sync<T extends Record<string, unknown>> {
     private handleMessage;
     private applyFullState;
     private applyPlayerState;
+    private addSnapshot;
+    private applyStateDirect;
     private removePlayer;
+    private attemptReconnect;
     private clearRemotePlayers;
     private findPlayersKey;
     private startSyncLoop;
+    private startInterpolationLoop;
+    private stopInterpolationLoop;
+    private processJitterQueue;
     private stopSyncLoop;
     private syncMyState;
     private updateInterpolation;
+    private lerpState;
     private generateRoomCode;
     private getHeaders;
 }

package/dist/index.js

@@ -288,15 +288,29 @@ var Sync = class {
     this._roomId = null;
     this.ws = null;
     this.syncInterval = null;
+    this.interpolationInterval = null;
     this.lastSentState = "";
-    this.interpolationTargets = /* @__PURE__ */ new Map();
     this.listeners = /* @__PURE__ */ new Map();
+    // Snapshot-based interpolation: store timestamped snapshots per player
+    this.snapshots = /* @__PURE__ */ new Map();
+    // Jitter buffer: queue incoming updates before applying
+    this.jitterQueue = [];
+    // Auto-reconnect state
+    this.reconnectAttempts = 0;
+    this.reconnectTimeout = null;
+    this.lastJoinOptions = void 0;
+    this.isReconnecting = false;
     this.state = state;
     this.myId = config.playerId;
     this.config = config;
     this.options = {
       tickRate: options?.tickRate ?? 20,
-      interpolate: options?.interpolate ?? true
+      interpolate: options?.interpolate ?? true,
+      interpolationDelay: options?.interpolationDelay ?? 100,
+      jitterBuffer: options?.jitterBuffer ?? 0,
+      // 0 = immediate, set to 50+ for smoothing
+      autoReconnect: options?.autoReconnect ?? true,
+      maxReconnectAttempts: options?.maxReconnectAttempts ?? 10
     };
   }
   /** Current room ID (null if not in a room) */
@@ -314,25 +328,46 @@ var Sync = class {
    * @param options - Join options
    */
   async join(roomId, options) {
-    if (this._roomId) {
+    if (this._roomId && !this.isReconnecting) {
       await this.leave();
     }
     this._roomId = roomId;
+    this.lastJoinOptions = options;
+    this.reconnectAttempts = 0;
     await this.connectWebSocket(roomId, options);
     this.startSyncLoop();
+    this.startInterpolationLoop();
   }
   /**
    * Leave the current room
    */
   async leave() {
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+    this.isReconnecting = false;
     this.stopSyncLoop();
+    this.stopInterpolationLoop();
     if (this.ws) {
       this.ws.close();
       this.ws = null;
     }
     this.clearRemotePlayers();
+    this.snapshots.clear();
+    this.jitterQueue = [];
     this._roomId = null;
   }
+  /**
+   * Send a one-off message to all players in the room
+   * 
+   * @param data - Any JSON-serializable data
+   */
+  broadcast(data) {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify({ type: "broadcast", data }));
+    }
+  }
   /**
    * Create a new room and join it
    * 
@@ -414,6 +449,9 @@ var Sync = class {
       this.ws.onclose = () => {
         this.stopSyncLoop();
         this.emit("disconnected");
+        if (this.options.autoReconnect && this._roomId && !this.isReconnecting) {
+          this.attemptReconnect();
+        }
       };
       this.ws.onmessage = (event) => {
         try {
@@ -440,6 +478,9 @@ var Sync = class {
         this.removePlayer(data.playerId);
         this.emit("leave", data.playerId);
         break;
+      case "message":
+        this.emit("message", data.from, data.data);
+        break;
     }
   }
   applyFullState(fullState) {
@@ -450,15 +491,43 @@ var Sync = class {
     }
   }
   applyPlayerState(playerId, playerState) {
+    if (this.options.interpolate && this.options.jitterBuffer > 0) {
+      this.jitterQueue.push({
+        deliverAt: Date.now() + this.options.jitterBuffer,
+        playerId,
+        state: { ...playerState }
+      });
+    } else if (this.options.interpolate) {
+      this.addSnapshot(playerId, playerState);
+    } else {
+      this.applyStateDirect(playerId, playerState);
+    }
+  }
+  addSnapshot(playerId, playerState) {
+    const isNewPlayer = !this.snapshots.has(playerId);
+    if (isNewPlayer) {
+      this.snapshots.set(playerId, []);
+    }
+    const playerSnapshots = this.snapshots.get(playerId);
+    playerSnapshots.push({
+      time: Date.now(),
+      state: { ...playerState }
+    });
+    while (playerSnapshots.length > 10) {
+      playerSnapshots.shift();
+    }
+    const playersKey = this.findPlayersKey();
+    if (playersKey) {
+      const players = this.state[playersKey];
+      if (isNewPlayer || !players[playerId]) {
+        players[playerId] = { ...playerState };
+      }
+    }
+  }
+  applyStateDirect(playerId, playerState) {
     const playersKey = this.findPlayersKey();
     if (!playersKey) return;
     const players = this.state[playersKey];
-    if (this.options.interpolate && players[playerId]) {
-      this.interpolationTargets.set(playerId, {
-        target: { ...playerState },
-        current: { ...players[playerId] }
-      });
-    }
     players[playerId] = playerState;
   }
   removePlayer(playerId) {
@@ -466,7 +535,28 @@ var Sync = class {
     if (!playersKey) return;
     const players = this.state[playersKey];
     delete players[playerId];
-    this.interpolationTargets.delete(playerId);
+    this.snapshots.delete(playerId);
+  }
+  attemptReconnect() {
+    if (this.reconnectAttempts >= this.options.maxReconnectAttempts) {
+      this.emit("error", new Error("Max reconnection attempts reached"));
+      return;
+    }
+    this.isReconnecting = true;
+    this.reconnectAttempts++;
+    const delay = Math.min(1e3 * Math.pow(2, this.reconnectAttempts - 1), 3e4);
+    this.emit("reconnecting", { attempt: this.reconnectAttempts, delay });
+    this.reconnectTimeout = setTimeout(async () => {
+      try {
+        await this.connectWebSocket(this._roomId, this.lastJoinOptions);
+        this.startSyncLoop();
+        this.isReconnecting = false;
+        this.reconnectAttempts = 0;
+        this.emit("reconnected");
+      } catch (e) {
+        this.isReconnecting = false;
+      }
+    }, delay);
   }
   clearRemotePlayers() {
     const playersKey = this.findPlayersKey();
@@ -477,7 +567,8 @@ var Sync = class {
         delete players[playerId];
       }
     }
-    this.interpolationTargets.clear();
+    this.snapshots.clear();
+    this.jitterQueue = [];
   }
   findPlayersKey() {
     const candidates = ["players", "entities", "gnomes", "users", "clients"];
@@ -498,11 +589,30 @@ var Sync = class {
     const intervalMs = 1e3 / this.options.tickRate;
     this.syncInterval = setInterval(() => {
       this.syncMyState();
-      if (this.options.interpolate) {
-        this.updateInterpolation();
-      }
     }, intervalMs);
   }
+  startInterpolationLoop() {
+    if (this.interpolationInterval) return;
+    if (!this.options.interpolate) return;
+    this.interpolationInterval = setInterval(() => {
+      this.processJitterQueue();
+      this.updateInterpolation();
+    }, 16);
+  }
+  stopInterpolationLoop() {
+    if (this.interpolationInterval) {
+      clearInterval(this.interpolationInterval);
+      this.interpolationInterval = null;
+    }
+  }
+  processJitterQueue() {
+    const now = Date.now();
+    const ready = this.jitterQueue.filter((item) => item.deliverAt <= now);
+    this.jitterQueue = this.jitterQueue.filter((item) => item.deliverAt > now);
+    for (const item of ready) {
+      this.addSnapshot(item.playerId, item.state);
+    }
+  }
   stopSyncLoop() {
     if (this.syncInterval) {
       clearInterval(this.syncInterval);
@@ -528,16 +638,41 @@ var Sync = class {
     const playersKey = this.findPlayersKey();
     if (!playersKey) return;
     const players = this.state[playersKey];
-    const lerpFactor = 0.2;
-    for (const [playerId, interp] of this.interpolationTargets) {
+    const renderTime = Date.now() - this.options.interpolationDelay;
+    for (const [playerId, playerSnapshots] of this.snapshots) {
+      if (playerId === this.myId) continue;
       const player = players[playerId];
       if (!player) continue;
-      for (const [key, targetValue] of Object.entries(interp.target)) {
-        if (typeof targetValue === "number" && typeof interp.current[key] === "number") {
-          const current = interp.current[key];
-          const newValue = current + (targetValue - current) * lerpFactor;
-          interp.current[key] = newValue;
-          player[key] = newValue;
+      let before = null;
+      let after = null;
+      for (const snapshot of playerSnapshots) {
+        if (snapshot.time <= renderTime) {
+          before = snapshot;
+        } else if (!after) {
+          after = snapshot;
+        }
+      }
+      if (before && after) {
+        const total = after.time - before.time;
+        const elapsed = renderTime - before.time;
+        const alpha = total > 0 ? Math.min(1, elapsed / total) : 1;
+        this.lerpState(player, before.state, after.state, alpha);
+      } else if (before) {
+        this.lerpState(player, player, before.state, 0.3);
+      } else if (after) {
+        this.lerpState(player, player, after.state, 0.3);
+      }
+    }
+  }
+  lerpState(target, from, to, alpha) {
+    for (const key of Object.keys(to)) {
+      const fromVal = from[key];
+      const toVal = to[key];
+      if (typeof fromVal === "number" && typeof toVal === "number") {
+        target[key] = fromVal + (toVal - fromVal) * alpha;
+      } else {
+        if (alpha > 0.5) {
+          target[key] = toVal;
         }
       }
     }

package/dist/index.mjs

@@ -261,15 +261,29 @@ var Sync = class {
     this._roomId = null;
     this.ws = null;
     this.syncInterval = null;
+    this.interpolationInterval = null;
     this.lastSentState = "";
-    this.interpolationTargets = /* @__PURE__ */ new Map();
     this.listeners = /* @__PURE__ */ new Map();
+    // Snapshot-based interpolation: store timestamped snapshots per player
+    this.snapshots = /* @__PURE__ */ new Map();
+    // Jitter buffer: queue incoming updates before applying
+    this.jitterQueue = [];
+    // Auto-reconnect state
+    this.reconnectAttempts = 0;
+    this.reconnectTimeout = null;
+    this.lastJoinOptions = void 0;
+    this.isReconnecting = false;
     this.state = state;
     this.myId = config.playerId;
     this.config = config;
     this.options = {
       tickRate: options?.tickRate ?? 20,
-      interpolate: options?.interpolate ?? true
+      interpolate: options?.interpolate ?? true,
+      interpolationDelay: options?.interpolationDelay ?? 100,
+      jitterBuffer: options?.jitterBuffer ?? 0,
+      // 0 = immediate, set to 50+ for smoothing
+      autoReconnect: options?.autoReconnect ?? true,
+      maxReconnectAttempts: options?.maxReconnectAttempts ?? 10
     };
   }
   /** Current room ID (null if not in a room) */
@@ -287,25 +301,46 @@ var Sync = class {
    * @param options - Join options
    */
   async join(roomId, options) {
-    if (this._roomId) {
+    if (this._roomId && !this.isReconnecting) {
       await this.leave();
     }
     this._roomId = roomId;
+    this.lastJoinOptions = options;
+    this.reconnectAttempts = 0;
     await this.connectWebSocket(roomId, options);
     this.startSyncLoop();
+    this.startInterpolationLoop();
   }
   /**
    * Leave the current room
    */
   async leave() {
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+    this.isReconnecting = false;
     this.stopSyncLoop();
+    this.stopInterpolationLoop();
     if (this.ws) {
       this.ws.close();
       this.ws = null;
     }
     this.clearRemotePlayers();
+    this.snapshots.clear();
+    this.jitterQueue = [];
     this._roomId = null;
   }
+  /**
+   * Send a one-off message to all players in the room
+   * 
+   * @param data - Any JSON-serializable data
+   */
+  broadcast(data) {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify({ type: "broadcast", data }));
+    }
+  }
   /**
    * Create a new room and join it
    * 
@@ -387,6 +422,9 @@ var Sync = class {
       this.ws.onclose = () => {
         this.stopSyncLoop();
         this.emit("disconnected");
+        if (this.options.autoReconnect && this._roomId && !this.isReconnecting) {
+          this.attemptReconnect();
+        }
       };
       this.ws.onmessage = (event) => {
         try {
@@ -413,6 +451,9 @@ var Sync = class {
         this.removePlayer(data.playerId);
         this.emit("leave", data.playerId);
         break;
+      case "message":
+        this.emit("message", data.from, data.data);
+        break;
     }
   }
   applyFullState(fullState) {
@@ -423,15 +464,43 @@ var Sync = class {
     }
   }
   applyPlayerState(playerId, playerState) {
+    if (this.options.interpolate && this.options.jitterBuffer > 0) {
+      this.jitterQueue.push({
+        deliverAt: Date.now() + this.options.jitterBuffer,
+        playerId,
+        state: { ...playerState }
+      });
+    } else if (this.options.interpolate) {
+      this.addSnapshot(playerId, playerState);
+    } else {
+      this.applyStateDirect(playerId, playerState);
+    }
+  }
+  addSnapshot(playerId, playerState) {
+    const isNewPlayer = !this.snapshots.has(playerId);
+    if (isNewPlayer) {
+      this.snapshots.set(playerId, []);
+    }
+    const playerSnapshots = this.snapshots.get(playerId);
+    playerSnapshots.push({
+      time: Date.now(),
+      state: { ...playerState }
+    });
+    while (playerSnapshots.length > 10) {
+      playerSnapshots.shift();
+    }
+    const playersKey = this.findPlayersKey();
+    if (playersKey) {
+      const players = this.state[playersKey];
+      if (isNewPlayer || !players[playerId]) {
+        players[playerId] = { ...playerState };
+      }
+    }
+  }
+  applyStateDirect(playerId, playerState) {
     const playersKey = this.findPlayersKey();
     if (!playersKey) return;
     const players = this.state[playersKey];
-    if (this.options.interpolate && players[playerId]) {
-      this.interpolationTargets.set(playerId, {
-        target: { ...playerState },
-        current: { ...players[playerId] }
-      });
-    }
     players[playerId] = playerState;
   }
   removePlayer(playerId) {
@@ -439,7 +508,28 @@ var Sync = class {
     if (!playersKey) return;
     const players = this.state[playersKey];
     delete players[playerId];
-    this.interpolationTargets.delete(playerId);
+    this.snapshots.delete(playerId);
+  }
+  attemptReconnect() {
+    if (this.reconnectAttempts >= this.options.maxReconnectAttempts) {
+      this.emit("error", new Error("Max reconnection attempts reached"));
+      return;
+    }
+    this.isReconnecting = true;
+    this.reconnectAttempts++;
+    const delay = Math.min(1e3 * Math.pow(2, this.reconnectAttempts - 1), 3e4);
+    this.emit("reconnecting", { attempt: this.reconnectAttempts, delay });
+    this.reconnectTimeout = setTimeout(async () => {
+      try {
+        await this.connectWebSocket(this._roomId, this.lastJoinOptions);
+        this.startSyncLoop();
+        this.isReconnecting = false;
+        this.reconnectAttempts = 0;
+        this.emit("reconnected");
+      } catch (e) {
+        this.isReconnecting = false;
+      }
+    }, delay);
   }
   clearRemotePlayers() {
     const playersKey = this.findPlayersKey();
@@ -450,7 +540,8 @@ var Sync = class {
         delete players[playerId];
       }
     }
-    this.interpolationTargets.clear();
+    this.snapshots.clear();
+    this.jitterQueue = [];
   }
   findPlayersKey() {
     const candidates = ["players", "entities", "gnomes", "users", "clients"];
@@ -471,11 +562,30 @@ var Sync = class {
     const intervalMs = 1e3 / this.options.tickRate;
     this.syncInterval = setInterval(() => {
       this.syncMyState();
-      if (this.options.interpolate) {
-        this.updateInterpolation();
-      }
     }, intervalMs);
   }
+  startInterpolationLoop() {
+    if (this.interpolationInterval) return;
+    if (!this.options.interpolate) return;
+    this.interpolationInterval = setInterval(() => {
+      this.processJitterQueue();
+      this.updateInterpolation();
+    }, 16);
+  }
+  stopInterpolationLoop() {
+    if (this.interpolationInterval) {
+      clearInterval(this.interpolationInterval);
+      this.interpolationInterval = null;
+    }
+  }
+  processJitterQueue() {
+    const now = Date.now();
+    const ready = this.jitterQueue.filter((item) => item.deliverAt <= now);
+    this.jitterQueue = this.jitterQueue.filter((item) => item.deliverAt > now);
+    for (const item of ready) {
+      this.addSnapshot(item.playerId, item.state);
+    }
+  }
   stopSyncLoop() {
     if (this.syncInterval) {
       clearInterval(this.syncInterval);
@@ -501,16 +611,41 @@ var Sync = class {
     const playersKey = this.findPlayersKey();
     if (!playersKey) return;
     const players = this.state[playersKey];
-    const lerpFactor = 0.2;
-    for (const [playerId, interp] of this.interpolationTargets) {
+    const renderTime = Date.now() - this.options.interpolationDelay;
+    for (const [playerId, playerSnapshots] of this.snapshots) {
+      if (playerId === this.myId) continue;
       const player = players[playerId];
       if (!player) continue;
-      for (const [key, targetValue] of Object.entries(interp.target)) {
-        if (typeof targetValue === "number" && typeof interp.current[key] === "number") {
-          const current = interp.current[key];
-          const newValue = current + (targetValue - current) * lerpFactor;
-          interp.current[key] = newValue;
-          player[key] = newValue;
+      let before = null;
+      let after = null;
+      for (const snapshot of playerSnapshots) {
+        if (snapshot.time <= renderTime) {
+          before = snapshot;
+        } else if (!after) {
+          after = snapshot;
+        }
+      }
+      if (before && after) {
+        const total = after.time - before.time;
+        const elapsed = renderTime - before.time;
+        const alpha = total > 0 ? Math.min(1, elapsed / total) : 1;
+        this.lerpState(player, before.state, after.state, alpha);
+      } else if (before) {
+        this.lerpState(player, player, before.state, 0.3);
+      } else if (after) {
+        this.lerpState(player, player, after.state, 0.3);
+      }
+    }
+  }
+  lerpState(target, from, to, alpha) {
+    for (const key of Object.keys(to)) {
+      const fromVal = from[key];
+      const toVal = to[key];
+      if (typeof fromVal === "number" && typeof toVal === "number") {
+        target[key] = fromVal + (toVal - fromVal) * alpha;
+      } else {
+        if (alpha > 0.5) {
+          target[key] = toVal;
         }
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@watchtower-sdk/core",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Simple game backend SDK - saves, multiplayer rooms, and more",
   "main": "dist/index.js",
   "module": "dist/index.mjs",