@watchtower-sdk/core 0.2.2 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # @watchtower-sdk/core
 
-Simple game backend SDK - cloud saves and multiplayer.
+The simplest way to add multiplayer to your game. Point at your state, join a room, done.
 
 ## Installation
 
@@ -15,74 +15,169 @@ import { Watchtower } from '@watchtower-sdk/core'
 
 const wt = new Watchtower({
   gameId: 'my-game',
-  apiKey: 'wt_live_...' // Get from dashboard
+  apiKey: 'wt_live_...'  // Get from watchtower.host
 })
 
-// Cloud saves
-await wt.save('progress', { level: 5 })
-const data = await wt.load('progress')
-
-// Multiplayer
+// Your game state
 const state = { players: {} }
+
+// Make it multiplayer
 const sync = wt.sync(state)
-await sync.join('room-code')
-state.players[sync.myId] = { x: 0, y: 0 }
-// Others appear in state.players automatically!
+await sync.join('my-room')
+
+// Add yourself
+state.players[sync.myId] = { x: 0, y: 0, name: 'Player1' }
+
+// Move (automatically syncs!)
+state.players[sync.myId].x += 10
+
+// Others appear automatically in state.players
+for (const [id, player] of Object.entries(state.players)) {
+  drawPlayer(player.x, player.y)
+}
 ```
 
-## Cloud Saves
+No events. No message handlers. Just read and write your state.
 
-Key-value storage per player. JSON in, JSON out.
+---
 
-```typescript
-// Save
-await wt.save('progress', { level: 5, coins: 100 })
-await wt.save('settings', { music: true, sfx: true })
+## State Templates
 
-// Load
-const progress = await wt.load('progress')
-const settings = await wt.load('settings')
+Pick the pattern that matches your game:
 
-// List all saves
-const keys = await wt.listSaves() // ['progress', 'settings']
+### Movement Game (Cursor Party, Agar.io)
 
-// Delete
-await wt.deleteSave('progress')
-```
+```typescript
+interface GameState {
+  players: Record<string, {
+    x: number
+    y: number
+    name: string
+    color: string
+  }>
+}
 
-## Multiplayer
+const state: GameState = { players: {} }
+const sync = wt.sync(state, { 
+  interpolate: true,
+  interpolationDelay: 100,
+  jitterBuffer: 50
+})
+```
 
-Point at your game state. Join a room. State syncs automatically.
+### Chat / Lobby
 
 ```typescript
-// Your game state
-const state = { players: {} }
+interface GameState {
+  players: Record<string, {
+    name: string
+    avatar: string
+    ready: boolean
+  }>
+  messages: Array<{
+    from: string
+    text: string
+    ts: number
+  }>
+}
 
-// Connect to Watchtower
-const sync = wt.sync(state)
+const state: GameState = { players: {}, messages: [] }
+const sync = wt.sync(state, { interpolate: false })  // No movement = no interpolation needed
+```
 
-// Join a room
-await sync.join('my-room')
+### Turn-Based (Chess, Cards)
 
-// Add yourself
-state.players[sync.myId] = {
-  x: 0,
-  y: 0,
-  name: 'Player1'
+```typescript
+interface GameState {
+  players: Record<string, {
+    name: string
+    hand?: Card[]  // Hidden from others in real implementation
+  }>
+  currentTurn: string
+  board: BoardState
+  phase: 'waiting' | 'playing' | 'finished'
 }
 
-// Move (automatically syncs to others!)
-state.players[sync.myId].x += 5
+const state: GameState = { 
+  players: {}, 
+  currentTurn: '', 
+  board: initialBoard,
+  phase: 'waiting'
+}
+const sync = wt.sync(state, { interpolate: false })
+```
 
-// Draw everyone (others appear automatically!)
-for (const [id, player] of Object.entries(state.players)) {
-  drawPlayer(player.x, player.y)
+### Action Game (Shooter, Brawler)
+
+```typescript
+interface GameState {
+  players: Record<string, {
+    x: number
+    y: number
+    vx: number  // Velocity helps with prediction
+    vy: number
+    health: number
+    facing: 'left' | 'right'
+    animation: string
+  }>
 }
+
+const state: GameState = { players: {} }
+const sync = wt.sync(state, {
+  interpolate: true,
+  interpolationDelay: 50,  // Lower for faster games
+  jitterBuffer: 25
+})
 ```
 
-No events. No message handlers. Just read and write your state.
+---
+
+## Smoothing Options
+
+The SDK automatically smooths remote player movement. Configure based on your game type:
+
+```typescript
+const sync = wt.sync(state, {
+  // Core settings
+  tickRate: 20,              // Updates per second (default: 20)
+  interpolate: true,         // Smooth remote movement (default: true)
+  
+  // Smoothing tuning
+  interpolationDelay: 100,   // Render others Xms in the past (default: 100)
+  jitterBuffer: 50,          // Buffer packets Xms to smooth delivery (default: 0)
+  
+  // Connection handling
+  autoReconnect: true,       // Auto-reconnect on disconnect (default: true)
+  maxReconnectAttempts: 10   // Give up after X attempts (default: 10)
+})
+```
+
+### Recommended Presets
+
+| Game Type | interpolationDelay | jitterBuffer | Notes |
+|-----------|-------------------|--------------|-------|
+| Casual (cursor party) | 100ms | 50ms | Buttery smooth, slight delay |
+| Action (platformer) | 50ms | 25ms | Responsive, still smooth |
+| Fast (shooter) | 40ms | 20ms | Very responsive |
+| Turn-based | 0ms | 0ms | Instant, no movement to smooth |
 
-### Creating & Joining Rooms
+**Why the delay?** The SDK renders other players slightly "in the past" using server timestamps. This allows it to interpolate between known positions instead of guessing. 100ms is imperceptible for casual games but makes movement silky smooth.
+
+---
+
+## Properties
+
+```typescript
+sync.myId        // Your player ID
+sync.roomId      // Current room ID, or null
+sync.connected   // WebSocket connected?
+sync.playerCount // Players in room
+sync.latency     // RTT to server in ms
+```
+
+---
+
+## Rooms
 
 ```typescript
 // Create a new room
@@ -99,53 +194,84 @@ await sync.leave()
 const rooms = await sync.listRooms()
 ```
 
-### Options
+---
 
-```typescript
-const sync = wt.sync(state, {
-  tickRate: 20,       // Updates per second (default: 20)
-  interpolate: true   // Smooth remote movement (default: true)
-})
-```
+## Events
 
-### Properties
+You don't *need* events — just read your state. But if you want notifications:
 
 ```typescript
-sync.myId      // Your player ID
-sync.roomId    // Current room, or null
-sync.connected // WebSocket connected?
+// Player events
+sync.on('join', (playerId) => console.log(`${playerId} joined`))
+sync.on('leave', (playerId) => console.log(`${playerId} left`))
+
+// Connection events
+sync.on('connected', () => console.log('Connected!'))
+sync.on('disconnected', () => console.log('Disconnected'))
+sync.on('reconnecting', ({ attempt, delay }) => console.log(`Reconnecting in ${delay}ms...`))
+sync.on('reconnected', () => console.log('Reconnected!'))
+
+// Error handling
+sync.on('error', (err) => console.error(err))
 ```
 
-### Events (Optional)
+---
+
+## Broadcast Messages
 
-You don't need events—just read your state. But if you want notifications:
+For one-off events that don't belong in state (explosions, sound effects):
 
 ```typescript
-sync.on('join', (playerId) => console.log(playerId, 'joined'))
-sync.on('leave', (playerId) => console.log(playerId, 'left'))
-sync.on('connected', () => console.log('Connected'))
-sync.on('disconnected', () => console.log('Disconnected'))
+// Send
+sync.broadcast({ type: 'explosion', x: 100, y: 200 })
+
+// Receive
+sync.on('message', (from, data) => {
+  if (data.type === 'explosion') {
+    playExplosion(data.x, data.y)
+  }
+})
 ```
 
-### Chat & Messages
+---
 
-Messages are just state:
+## Cloud Saves
+
+Simple key-value storage per player:
 
 ```typescript
-state.chat = [
-  ...state.chat.slice(-50),  // Keep last 50
-  { from: sync.myId, text: 'Hello!', ts: Date.now() }
-]
+// Save
+await wt.save('progress', { level: 5, coins: 100 })
+
+// Load
+const progress = await wt.load('progress')
+
+// List all saves
+const keys = await wt.listSaves()  // ['progress']
+
+// Delete
+await wt.deleteSave('progress')
 ```
 
+---
+
 ## Full Example
 
 ```typescript
 import { Watchtower } from '@watchtower-sdk/core'
 
 const wt = new Watchtower({ gameId: 'my-game', apiKey: 'wt_...' })
-const state = { players: {} }
-const sync = wt.sync(state)
+
+// State template: movement game
+const state = { 
+  players: {} as Record<string, { x: number; y: number; color: string }>
+}
+
+const sync = wt.sync(state, {
+  interpolate: true,
+  interpolationDelay: 100,
+  jitterBuffer: 50
+})
 
 // Join or create room
 const code = prompt('Room code? (blank to create)')
@@ -171,57 +297,42 @@ function loop() {
   if (keys.up)    state.players[sync.myId].y -= 5
   if (keys.down)  state.players[sync.myId].y += 5
   
-  // Draw everyone
+  // Draw everyone (others are auto-interpolated!)
   ctx.clearRect(0, 0, 800, 600)
   for (const [id, p] of Object.entries(state.players)) {
     ctx.fillStyle = p.color
     ctx.fillRect(p.x - 10, p.y - 10, 20, 20)
+    
+    // Show latency for your player
+    if (id === sync.myId) {
+      ctx.fillText(`${sync.latency}ms`, p.x, p.y - 15)
+    }
   }
   
+  // Debug info
+  ctx.fillStyle = '#fff'
+  ctx.fillText(`Players: ${sync.playerCount}`, 10, 20)
+  
   requestAnimationFrame(loop)
 }
 loop()
 ```
 
-## API Reference
+---
 
-### Watchtower
+## Best Practices
 
-```typescript
-const wt = new Watchtower({
-  gameId: string,    // From dashboard
-  apiKey?: string,   // From dashboard
-  playerId?: string  // Auto-generated if not provided
-})
-
-wt.playerId  // Current player ID
-wt.gameId    // Game ID
-
-// Saves
-await wt.save(key: string, data: any): Promise<void>
-await wt.load<T>(key: string): Promise<T | null>
-await wt.listSaves(): Promise<string[]>
-await wt.deleteSave(key: string): Promise<void>
+1. **Keep state flat.** Nested objects sync fine, but flat is faster to diff.
 
-// Multiplayer
-wt.sync(state: object, options?: SyncOptions): Sync
-```
+2. **Use the `players` key.** The SDK auto-detects `players`, `entities`, `users`, or `clients`.
 
-### Sync
+3. **Don't store secrets in state.** Everyone sees everything. Use server-side validation for game logic.
 
-```typescript
-sync.myId: string
-sync.roomId: string | null
-sync.connected: boolean
+4. **Let the SDK interpolate.** Don't add your own smoothing on top — it'll fight the SDK.
 
-await sync.join(roomId: string, options?: JoinOptions): Promise<void>
-await sync.leave(): Promise<void>
-await sync.create(options?: CreateOptions): Promise<string>
-await sync.listRooms(): Promise<RoomListing[]>
+5. **Test with "Open another tab".** Easiest way to see multiplayer working.
 
-sync.on(event: string, callback: Function): void
-sync.off(event: string, callback: Function): void
-```
+---
 
 ## License
 

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 */
@@ -263,14 +271,29 @@ declare class Sync<T extends Record<string, unknown>> {
     get roomId(): string | null;
     /** Whether currently connected to a room */
     get connected(): boolean;
+    /** Number of players in the current room */
+    get playerCount(): number;
+    /** Current latency to server in milliseconds */
+    get latency(): number;
     private config;
     private options;
     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;
+    private serverTimeOffset;
+    private _playerCount;
+    private _latency;
+    private pingStartTime;
+    private pingInterval;
     constructor(state: T, config: Required<WatchtowerConfig>, options?: SyncOptions);
     /**
      * Join a room - your state will sync with everyone in this room
@@ -303,7 +326,7 @@ declare class Sync<T extends Record<string, unknown>> {
     /**
      * Subscribe to sync events
      */
-    on(event: 'join' | 'leave' | 'error' | 'connected' | 'disconnected' | 'message', callback: Function): void;
+    on(event: 'join' | 'leave' | 'error' | 'connected' | 'disconnected' | 'reconnecting' | 'reconnected' | 'message', callback: Function): void;
     /**
      * Unsubscribe from sync events
      */
@@ -313,13 +336,21 @@ 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 measureLatency;
+    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 */
@@ -263,14 +271,29 @@ declare class Sync<T extends Record<string, unknown>> {
     get roomId(): string | null;
     /** Whether currently connected to a room */
     get connected(): boolean;
+    /** Number of players in the current room */
+    get playerCount(): number;
+    /** Current latency to server in milliseconds */
+    get latency(): number;
     private config;
     private options;
     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;
+    private serverTimeOffset;
+    private _playerCount;
+    private _latency;
+    private pingStartTime;
+    private pingInterval;
     constructor(state: T, config: Required<WatchtowerConfig>, options?: SyncOptions);
     /**
      * Join a room - your state will sync with everyone in this room
@@ -303,7 +326,7 @@ declare class Sync<T extends Record<string, unknown>> {
     /**
      * Subscribe to sync events
      */
-    on(event: 'join' | 'leave' | 'error' | 'connected' | 'disconnected' | 'message', callback: Function): void;
+    on(event: 'join' | 'leave' | 'error' | 'connected' | 'disconnected' | 'reconnecting' | 'reconnected' | 'message', callback: Function): void;
     /**
      * Unsubscribe from sync events
      */
@@ -313,13 +336,21 @@ 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 measureLatency;
+    private stopInterpolationLoop;
+    private processJitterQueue;
     private stopSyncLoop;
     private syncMyState;
     private updateInterpolation;
+    private lerpState;
     private generateRoomCode;
     private getHeaders;
 }

package/dist/index.js

@@ -288,15 +288,36 @@ 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;
+    // Server time sync and metrics
+    this.serverTimeOffset = 0;
+    // Local time - server time
+    this._playerCount = 1;
+    this._latency = 0;
+    this.pingStartTime = 0;
+    this.pingInterval = null;
     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) */
@@ -307,6 +328,14 @@ var Sync = class {
   get connected() {
     return this.ws?.readyState === WebSocket.OPEN;
   }
+  /** Number of players in the current room */
+  get playerCount() {
+    return this._playerCount;
+  }
+  /** Current latency to server in milliseconds */
+  get latency() {
+    return this._latency;
+  }
   /**
    * Join a room - your state will sync with everyone in this room
    * 
@@ -314,23 +343,34 @@ 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;
   }
   /**
@@ -424,6 +464,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 {
@@ -436,23 +479,41 @@ var Sync = class {
     });
   }
   handleMessage(data) {
+    if (data.serverTime) {
+      this.serverTimeOffset = Date.now() - data.serverTime;
+    }
     switch (data.type) {
+      case "welcome":
+        if (data.state) {
+          this.applyFullState(data.state);
+        }
+        this._playerCount = data.playerCount || 1;
+        this.emit("welcome", { playerCount: data.playerCount, tick: data.tick });
+        break;
       case "full_state":
         this.applyFullState(data.state);
         break;
       case "state":
-        this.applyPlayerState(data.playerId, data.data);
+        this.applyPlayerState(data.playerId, data.data, data.serverTime);
         break;
       case "join":
+        this._playerCount = data.playerCount || this._playerCount + 1;
         this.emit("join", data.playerId);
         break;
       case "leave":
+        this._playerCount = data.playerCount || Math.max(1, this._playerCount - 1);
         this.removePlayer(data.playerId);
         this.emit("leave", data.playerId);
         break;
       case "message":
         this.emit("message", data.from, data.data);
         break;
+      case "pong":
+        if (this.pingStartTime) {
+          this._latency = Date.now() - this.pingStartTime;
+          this._playerCount = data.playerCount || this._playerCount;
+        }
+        break;
     }
   }
   applyFullState(fullState) {
@@ -462,16 +523,46 @@ var Sync = class {
       }
     }
   }
-  applyPlayerState(playerId, playerState) {
+  applyPlayerState(playerId, playerState, serverTime) {
+    const timestamp = serverTime ? serverTime + this.serverTimeOffset : Date.now();
+    if (this.options.interpolate && this.options.jitterBuffer > 0) {
+      this.jitterQueue.push({
+        deliverAt: timestamp + this.options.jitterBuffer,
+        playerId,
+        state: { ...playerState },
+        timestamp
+      });
+    } else if (this.options.interpolate) {
+      this.addSnapshot(playerId, playerState, timestamp);
+    } else {
+      this.applyStateDirect(playerId, playerState);
+    }
+  }
+  addSnapshot(playerId, playerState, timestamp) {
+    const isNewPlayer = !this.snapshots.has(playerId);
+    if (isNewPlayer) {
+      this.snapshots.set(playerId, []);
+    }
+    const playerSnapshots = this.snapshots.get(playerId);
+    playerSnapshots.push({
+      time: timestamp || 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) {
@@ -479,7 +570,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();
@@ -490,7 +602,8 @@ var Sync = class {
         delete players[playerId];
       }
     }
-    this.interpolationTargets.clear();
+    this.snapshots.clear();
+    this.jitterQueue = [];
   }
   findPlayersKey() {
     const candidates = ["players", "entities", "gnomes", "users", "clients"];
@@ -511,11 +624,43 @@ 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);
+    this.pingInterval = setInterval(() => {
+      this.measureLatency();
+    }, 2e3);
+  }
+  measureLatency() {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.pingStartTime = Date.now();
+      this.ws.send(JSON.stringify({ type: "ping" }));
+    }
+  }
+  stopInterpolationLoop() {
+    if (this.interpolationInterval) {
+      clearInterval(this.interpolationInterval);
+      this.interpolationInterval = null;
+    }
+    if (this.pingInterval) {
+      clearInterval(this.pingInterval);
+      this.pingInterval = 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, item.timestamp);
+    }
+  }
   stopSyncLoop() {
     if (this.syncInterval) {
       clearInterval(this.syncInterval);
@@ -541,16 +686,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,36 @@ 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;
+    // Server time sync and metrics
+    this.serverTimeOffset = 0;
+    // Local time - server time
+    this._playerCount = 1;
+    this._latency = 0;
+    this.pingStartTime = 0;
+    this.pingInterval = null;
     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) */
@@ -280,6 +301,14 @@ var Sync = class {
   get connected() {
     return this.ws?.readyState === WebSocket.OPEN;
   }
+  /** Number of players in the current room */
+  get playerCount() {
+    return this._playerCount;
+  }
+  /** Current latency to server in milliseconds */
+  get latency() {
+    return this._latency;
+  }
   /**
    * Join a room - your state will sync with everyone in this room
    * 
@@ -287,23 +316,34 @@ 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;
   }
   /**
@@ -397,6 +437,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 {
@@ -409,23 +452,41 @@ var Sync = class {
     });
   }
   handleMessage(data) {
+    if (data.serverTime) {
+      this.serverTimeOffset = Date.now() - data.serverTime;
+    }
     switch (data.type) {
+      case "welcome":
+        if (data.state) {
+          this.applyFullState(data.state);
+        }
+        this._playerCount = data.playerCount || 1;
+        this.emit("welcome", { playerCount: data.playerCount, tick: data.tick });
+        break;
       case "full_state":
         this.applyFullState(data.state);
         break;
       case "state":
-        this.applyPlayerState(data.playerId, data.data);
+        this.applyPlayerState(data.playerId, data.data, data.serverTime);
         break;
       case "join":
+        this._playerCount = data.playerCount || this._playerCount + 1;
         this.emit("join", data.playerId);
         break;
       case "leave":
+        this._playerCount = data.playerCount || Math.max(1, this._playerCount - 1);
         this.removePlayer(data.playerId);
         this.emit("leave", data.playerId);
         break;
       case "message":
         this.emit("message", data.from, data.data);
         break;
+      case "pong":
+        if (this.pingStartTime) {
+          this._latency = Date.now() - this.pingStartTime;
+          this._playerCount = data.playerCount || this._playerCount;
+        }
+        break;
     }
   }
   applyFullState(fullState) {
@@ -435,16 +496,46 @@ var Sync = class {
       }
     }
   }
-  applyPlayerState(playerId, playerState) {
+  applyPlayerState(playerId, playerState, serverTime) {
+    const timestamp = serverTime ? serverTime + this.serverTimeOffset : Date.now();
+    if (this.options.interpolate && this.options.jitterBuffer > 0) {
+      this.jitterQueue.push({
+        deliverAt: timestamp + this.options.jitterBuffer,
+        playerId,
+        state: { ...playerState },
+        timestamp
+      });
+    } else if (this.options.interpolate) {
+      this.addSnapshot(playerId, playerState, timestamp);
+    } else {
+      this.applyStateDirect(playerId, playerState);
+    }
+  }
+  addSnapshot(playerId, playerState, timestamp) {
+    const isNewPlayer = !this.snapshots.has(playerId);
+    if (isNewPlayer) {
+      this.snapshots.set(playerId, []);
+    }
+    const playerSnapshots = this.snapshots.get(playerId);
+    playerSnapshots.push({
+      time: timestamp || 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) {
@@ -452,7 +543,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();
@@ -463,7 +575,8 @@ var Sync = class {
         delete players[playerId];
       }
     }
-    this.interpolationTargets.clear();
+    this.snapshots.clear();
+    this.jitterQueue = [];
   }
   findPlayersKey() {
     const candidates = ["players", "entities", "gnomes", "users", "clients"];
@@ -484,11 +597,43 @@ 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);
+    this.pingInterval = setInterval(() => {
+      this.measureLatency();
+    }, 2e3);
+  }
+  measureLatency() {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.pingStartTime = Date.now();
+      this.ws.send(JSON.stringify({ type: "ping" }));
+    }
+  }
+  stopInterpolationLoop() {
+    if (this.interpolationInterval) {
+      clearInterval(this.interpolationInterval);
+      this.interpolationInterval = null;
+    }
+    if (this.pingInterval) {
+      clearInterval(this.pingInterval);
+      this.pingInterval = 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, item.timestamp);
+    }
+  }
   stopSyncLoop() {
     if (this.syncInterval) {
       clearInterval(this.syncInterval);
@@ -514,16 +659,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.2",
+  "version": "0.3.1",
   "description": "Simple game backend SDK - saves, multiplayer rooms, and more",
   "main": "dist/index.js",
   "module": "dist/index.mjs",