@watchtower-sdk/core 0.3.0 → 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

@@ -271,6 +271,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;
@@ -285,6 +289,11 @@ declare class Sync<T extends Record<string, unknown>> {
     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
@@ -335,6 +344,7 @@ declare class Sync<T extends Record<string, unknown>> {
     private findPlayersKey;
     private startSyncLoop;
     private startInterpolationLoop;
+    private measureLatency;
     private stopInterpolationLoop;
     private processJitterQueue;
     private stopSyncLoop;

package/dist/index.d.ts

@@ -271,6 +271,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;
@@ -285,6 +289,11 @@ declare class Sync<T extends Record<string, unknown>> {
     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
@@ -335,6 +344,7 @@ declare class Sync<T extends Record<string, unknown>> {
     private findPlayersKey;
     private startSyncLoop;
     private startInterpolationLoop;
+    private measureLatency;
     private stopInterpolationLoop;
     private processJitterQueue;
     private stopSyncLoop;

package/dist/index.js

@@ -300,6 +300,13 @@ 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;
@@ -321,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
    * 
@@ -464,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) {
@@ -490,27 +523,29 @@ 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: Date.now() + this.options.jitterBuffer,
+        deliverAt: timestamp + this.options.jitterBuffer,
         playerId,
-        state: { ...playerState }
+        state: { ...playerState },
+        timestamp
       });
     } else if (this.options.interpolate) {
-      this.addSnapshot(playerId, playerState);
+      this.addSnapshot(playerId, playerState, timestamp);
     } else {
       this.applyStateDirect(playerId, playerState);
     }
   }
-  addSnapshot(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) {
@@ -598,19 +633,32 @@ var Sync = class {
       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);
+      this.addSnapshot(item.playerId, item.state, item.timestamp);
     }
   }
   stopSyncLoop() {

package/dist/index.mjs

@@ -273,6 +273,13 @@ 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;
@@ -294,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
    * 
@@ -437,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) {
@@ -463,27 +496,29 @@ 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: Date.now() + this.options.jitterBuffer,
+        deliverAt: timestamp + this.options.jitterBuffer,
         playerId,
-        state: { ...playerState }
+        state: { ...playerState },
+        timestamp
       });
     } else if (this.options.interpolate) {
-      this.addSnapshot(playerId, playerState);
+      this.addSnapshot(playerId, playerState, timestamp);
     } else {
       this.applyStateDirect(playerId, playerState);
     }
   }
-  addSnapshot(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) {
@@ -571,19 +606,32 @@ var Sync = class {
       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);
+      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.3.1",
   "description": "Simple game backend SDK - saves, multiplayer rooms, and more",
   "main": "dist/index.js",
   "module": "dist/index.mjs",