@watchtower-sdk/core 0.3.0 → 0.4.0

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

@@ -209,11 +209,20 @@ declare class Room {
 interface SyncOptions {
     /** Updates per second (default: 20) */
     tickRate?: number;
-    /** Enable interpolation for remote entities (default: true) */
+    /**
+     * Smoothing mode for remote players (default: 'lerp')
+     * - 'lerp': Frame-based lerping toward latest position. Zero latency, simple, great for casual games.
+     * - 'interpolate': Time-based snapshot interpolation. Adds latency but more accurate for competitive games.
+     * - 'none': No smoothing, positions snap immediately.
+     */
+    smoothing?: 'lerp' | 'interpolate' | 'none';
+    /** Lerp factor - how fast to catch up to target (default: 0.15). Only used in 'lerp' mode. */
+    lerpFactor?: number;
+    /** @deprecated Use smoothing: 'interpolate' instead */
     interpolate?: boolean;
-    /** Interpolation delay in ms - how far "in the past" to render others (default: 100) */
+    /** Interpolation delay in ms - how far "in the past" to render others (default: 100). Only used in 'interpolate' mode. */
     interpolationDelay?: number;
-    /** Jitter buffer size in ms - smooths network variance (default: 50) */
+    /** Jitter buffer size in ms - smooths network variance (default: 0). Only used in 'interpolate' mode. */
     jitterBuffer?: number;
     /** Enable auto-reconnection on disconnect (default: true) */
     autoReconnect?: boolean;
@@ -271,6 +280,10 @@ 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;
@@ -280,11 +293,17 @@ declare class Sync<T extends Record<string, unknown>> {
     private lastSentState;
     private listeners;
     private snapshots;
+    private lerpTargets;
     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
@@ -327,6 +346,7 @@ declare class Sync<T extends Record<string, unknown>> {
     private handleMessage;
     private applyFullState;
     private applyPlayerState;
+    private setLerpTarget;
     private addSnapshot;
     private applyStateDirect;
     private removePlayer;
@@ -335,6 +355,13 @@ declare class Sync<T extends Record<string, unknown>> {
     private findPlayersKey;
     private startSyncLoop;
     private startInterpolationLoop;
+    /**
+     * Frame-based lerping (gnome-chat style)
+     * Lerps each remote player's position toward their target by lerpFactor each frame.
+     * Simple, zero latency, great for casual games.
+     */
+    private updateLerp;
+    private measureLatency;
     private stopInterpolationLoop;
     private processJitterQueue;
     private stopSyncLoop;

package/dist/index.d.ts

@@ -209,11 +209,20 @@ declare class Room {
 interface SyncOptions {
     /** Updates per second (default: 20) */
     tickRate?: number;
-    /** Enable interpolation for remote entities (default: true) */
+    /**
+     * Smoothing mode for remote players (default: 'lerp')
+     * - 'lerp': Frame-based lerping toward latest position. Zero latency, simple, great for casual games.
+     * - 'interpolate': Time-based snapshot interpolation. Adds latency but more accurate for competitive games.
+     * - 'none': No smoothing, positions snap immediately.
+     */
+    smoothing?: 'lerp' | 'interpolate' | 'none';
+    /** Lerp factor - how fast to catch up to target (default: 0.15). Only used in 'lerp' mode. */
+    lerpFactor?: number;
+    /** @deprecated Use smoothing: 'interpolate' instead */
     interpolate?: boolean;
-    /** Interpolation delay in ms - how far "in the past" to render others (default: 100) */
+    /** Interpolation delay in ms - how far "in the past" to render others (default: 100). Only used in 'interpolate' mode. */
     interpolationDelay?: number;
-    /** Jitter buffer size in ms - smooths network variance (default: 50) */
+    /** Jitter buffer size in ms - smooths network variance (default: 0). Only used in 'interpolate' mode. */
     jitterBuffer?: number;
     /** Enable auto-reconnection on disconnect (default: true) */
     autoReconnect?: boolean;
@@ -271,6 +280,10 @@ 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;
@@ -280,11 +293,17 @@ declare class Sync<T extends Record<string, unknown>> {
     private lastSentState;
     private listeners;
     private snapshots;
+    private lerpTargets;
     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
@@ -327,6 +346,7 @@ declare class Sync<T extends Record<string, unknown>> {
     private handleMessage;
     private applyFullState;
     private applyPlayerState;
+    private setLerpTarget;
     private addSnapshot;
     private applyStateDirect;
     private removePlayer;
@@ -335,6 +355,13 @@ declare class Sync<T extends Record<string, unknown>> {
     private findPlayersKey;
     private startSyncLoop;
     private startInterpolationLoop;
+    /**
+     * Frame-based lerping (gnome-chat style)
+     * Lerps each remote player's position toward their target by lerpFactor each frame.
+     * Simple, zero latency, great for casual games.
+     */
+    private updateLerp;
+    private measureLatency;
     private stopInterpolationLoop;
     private processJitterQueue;
     private stopSyncLoop;

package/dist/index.js

@@ -293,6 +293,8 @@ var Sync = class {
     this.listeners = /* @__PURE__ */ new Map();
     // Snapshot-based interpolation: store timestamped snapshots per player
     this.snapshots = /* @__PURE__ */ new Map();
+    // Lerp-based smoothing: store target positions per player (for 'lerp' mode)
+    this.lerpTargets = /* @__PURE__ */ new Map();
     // Jitter buffer: queue incoming updates before applying
     this.jitterQueue = [];
     // Auto-reconnect state
@@ -300,15 +302,30 @@ var Sync = class {
     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;
+    let smoothing = options?.smoothing ?? "lerp";
+    if (options?.interpolate === false) {
+      smoothing = "none";
+    } else if (options?.interpolate === true && !options?.smoothing) {
+      smoothing = "lerp";
+    }
     this.options = {
       tickRate: options?.tickRate ?? 20,
-      interpolate: options?.interpolate ?? true,
+      smoothing,
+      lerpFactor: options?.lerpFactor ?? 0.15,
+      interpolate: smoothing !== "none",
+      // Legacy compat
       interpolationDelay: options?.interpolationDelay ?? 100,
       jitterBuffer: options?.jitterBuffer ?? 0,
-      // 0 = immediate, set to 50+ for smoothing
       autoReconnect: options?.autoReconnect ?? true,
       maxReconnectAttempts: options?.maxReconnectAttempts ?? 10
     };
@@ -321,6 +338,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
    * 
@@ -464,23 +489,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) {
@@ -490,27 +533,49 @@ 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);
+  applyPlayerState(playerId, playerState, serverTime) {
+    const timestamp = serverTime ? serverTime + this.serverTimeOffset : Date.now();
+    switch (this.options.smoothing) {
+      case "lerp":
+        this.setLerpTarget(playerId, playerState);
+        break;
+      case "interpolate":
+        if (this.options.jitterBuffer > 0) {
+          this.jitterQueue.push({
+            deliverAt: timestamp + this.options.jitterBuffer,
+            playerId,
+            state: { ...playerState },
+            timestamp
+          });
+        } else {
+          this.addSnapshot(playerId, playerState, timestamp);
+        }
+        break;
+      case "none":
+      default:
+        this.applyStateDirect(playerId, playerState);
+        break;
     }
   }
-  addSnapshot(playerId, playerState) {
+  setLerpTarget(playerId, playerState) {
+    const isNewPlayer = !this.lerpTargets.has(playerId);
+    this.lerpTargets.set(playerId, { ...playerState });
+    const playersKey = this.findPlayersKey();
+    if (playersKey) {
+      const players = this.state[playersKey];
+      if (isNewPlayer || !players[playerId]) {
+        players[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: Date.now(),
+      time: timestamp || Date.now(),
       state: { ...playerState }
     });
     while (playerSnapshots.length > 10) {
@@ -536,6 +601,7 @@ var Sync = class {
     const players = this.state[playersKey];
     delete players[playerId];
     this.snapshots.delete(playerId);
+    this.lerpTargets.delete(playerId);
   }
   attemptReconnect() {
     if (this.reconnectAttempts >= this.options.maxReconnectAttempts) {
@@ -568,6 +634,7 @@ var Sync = class {
       }
     }
     this.snapshots.clear();
+    this.lerpTargets.clear();
     this.jitterQueue = [];
   }
   findPlayersKey() {
@@ -593,24 +660,65 @@ var Sync = class {
   }
   startInterpolationLoop() {
     if (this.interpolationInterval) return;
-    if (!this.options.interpolate) return;
+    if (this.options.smoothing === "none") return;
     this.interpolationInterval = setInterval(() => {
-      this.processJitterQueue();
-      this.updateInterpolation();
+      if (this.options.smoothing === "lerp") {
+        this.updateLerp();
+      } else if (this.options.smoothing === "interpolate") {
+        this.processJitterQueue();
+        this.updateInterpolation();
+      }
     }, 16);
+    this.pingInterval = setInterval(() => {
+      this.measureLatency();
+    }, 2e3);
+  }
+  /**
+   * Frame-based lerping (gnome-chat style)
+   * Lerps each remote player's position toward their target by lerpFactor each frame.
+   * Simple, zero latency, great for casual games.
+   */
+  updateLerp() {
+    const playersKey = this.findPlayersKey();
+    if (!playersKey) return;
+    const players = this.state[playersKey];
+    const lerpFactor = this.options.lerpFactor;
+    for (const [playerId, target] of this.lerpTargets) {
+      if (playerId === this.myId) continue;
+      const player = players[playerId];
+      if (!player) continue;
+      for (const [key, targetValue] of Object.entries(target)) {
+        if (typeof targetValue === "number" && typeof player[key] === "number") {
+          const current = player[key];
+          player[key] = current + (targetValue - current) * lerpFactor;
+        } else if (typeof targetValue !== "number") {
+          player[key] = targetValue;
+        }
+      }
+    }
+  }
+  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);
+      this.addSnapshot(item.playerId, item.state, item.timestamp);
     }
   }
   stopSyncLoop() {

package/dist/index.mjs

@@ -266,6 +266,8 @@ var Sync = class {
     this.listeners = /* @__PURE__ */ new Map();
     // Snapshot-based interpolation: store timestamped snapshots per player
     this.snapshots = /* @__PURE__ */ new Map();
+    // Lerp-based smoothing: store target positions per player (for 'lerp' mode)
+    this.lerpTargets = /* @__PURE__ */ new Map();
     // Jitter buffer: queue incoming updates before applying
     this.jitterQueue = [];
     // Auto-reconnect state
@@ -273,15 +275,30 @@ var Sync = class {
     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;
+    let smoothing = options?.smoothing ?? "lerp";
+    if (options?.interpolate === false) {
+      smoothing = "none";
+    } else if (options?.interpolate === true && !options?.smoothing) {
+      smoothing = "lerp";
+    }
     this.options = {
       tickRate: options?.tickRate ?? 20,
-      interpolate: options?.interpolate ?? true,
+      smoothing,
+      lerpFactor: options?.lerpFactor ?? 0.15,
+      interpolate: smoothing !== "none",
+      // Legacy compat
       interpolationDelay: options?.interpolationDelay ?? 100,
       jitterBuffer: options?.jitterBuffer ?? 0,
-      // 0 = immediate, set to 50+ for smoothing
       autoReconnect: options?.autoReconnect ?? true,
       maxReconnectAttempts: options?.maxReconnectAttempts ?? 10
     };
@@ -294,6 +311,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
    * 
@@ -437,23 +462,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) {
@@ -463,27 +506,49 @@ 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);
+  applyPlayerState(playerId, playerState, serverTime) {
+    const timestamp = serverTime ? serverTime + this.serverTimeOffset : Date.now();
+    switch (this.options.smoothing) {
+      case "lerp":
+        this.setLerpTarget(playerId, playerState);
+        break;
+      case "interpolate":
+        if (this.options.jitterBuffer > 0) {
+          this.jitterQueue.push({
+            deliverAt: timestamp + this.options.jitterBuffer,
+            playerId,
+            state: { ...playerState },
+            timestamp
+          });
+        } else {
+          this.addSnapshot(playerId, playerState, timestamp);
+        }
+        break;
+      case "none":
+      default:
+        this.applyStateDirect(playerId, playerState);
+        break;
     }
   }
-  addSnapshot(playerId, playerState) {
+  setLerpTarget(playerId, playerState) {
+    const isNewPlayer = !this.lerpTargets.has(playerId);
+    this.lerpTargets.set(playerId, { ...playerState });
+    const playersKey = this.findPlayersKey();
+    if (playersKey) {
+      const players = this.state[playersKey];
+      if (isNewPlayer || !players[playerId]) {
+        players[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: Date.now(),
+      time: timestamp || Date.now(),
       state: { ...playerState }
     });
     while (playerSnapshots.length > 10) {
@@ -509,6 +574,7 @@ var Sync = class {
     const players = this.state[playersKey];
     delete players[playerId];
     this.snapshots.delete(playerId);
+    this.lerpTargets.delete(playerId);
   }
   attemptReconnect() {
     if (this.reconnectAttempts >= this.options.maxReconnectAttempts) {
@@ -541,6 +607,7 @@ var Sync = class {
       }
     }
     this.snapshots.clear();
+    this.lerpTargets.clear();
     this.jitterQueue = [];
   }
   findPlayersKey() {
@@ -566,24 +633,65 @@ var Sync = class {
   }
   startInterpolationLoop() {
     if (this.interpolationInterval) return;
-    if (!this.options.interpolate) return;
+    if (this.options.smoothing === "none") return;
     this.interpolationInterval = setInterval(() => {
-      this.processJitterQueue();
-      this.updateInterpolation();
+      if (this.options.smoothing === "lerp") {
+        this.updateLerp();
+      } else if (this.options.smoothing === "interpolate") {
+        this.processJitterQueue();
+        this.updateInterpolation();
+      }
     }, 16);
+    this.pingInterval = setInterval(() => {
+      this.measureLatency();
+    }, 2e3);
+  }
+  /**
+   * Frame-based lerping (gnome-chat style)
+   * Lerps each remote player's position toward their target by lerpFactor each frame.
+   * Simple, zero latency, great for casual games.
+   */
+  updateLerp() {
+    const playersKey = this.findPlayersKey();
+    if (!playersKey) return;
+    const players = this.state[playersKey];
+    const lerpFactor = this.options.lerpFactor;
+    for (const [playerId, target] of this.lerpTargets) {
+      if (playerId === this.myId) continue;
+      const player = players[playerId];
+      if (!player) continue;
+      for (const [key, targetValue] of Object.entries(target)) {
+        if (typeof targetValue === "number" && typeof player[key] === "number") {
+          const current = player[key];
+          player[key] = current + (targetValue - current) * lerpFactor;
+        } else if (typeof targetValue !== "number") {
+          player[key] = targetValue;
+        }
+      }
+    }
+  }
+  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);
+      this.addSnapshot(item.playerId, item.state, item.timestamp);
     }
   }
   stopSyncLoop() {

package/package.json

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