@watchtower-sdk/core 0.2.0 → 0.2.2

package/README.md

@@ -1,17 +1,17 @@
-# @watchtower/sdk
+# @watchtower-sdk/core
 
-Simple game backend SDK - cloud saves, multiplayer rooms, automatic state sync.
+Simple game backend SDK - cloud saves and multiplayer.
 
 ## Installation
 
 ```bash
-npm install @watchtower/sdk
+npm install @watchtower-sdk/core
 ```
 
 ## Quick Start
 
 ```typescript
-import { Watchtower } from '@watchtower/sdk'
+import { Watchtower } from '@watchtower-sdk/core'
 
 const wt = new Watchtower({
   gameId: 'my-game',
@@ -19,265 +19,168 @@ const wt = new Watchtower({
 })
 
 // Cloud saves
-await wt.save('progress', { level: 5, coins: 100 })
+await wt.save('progress', { level: 5 })
 const data = await wt.load('progress')
 
 // Multiplayer
-const room = await wt.createRoom()
-console.log('Share this code:', room.code) // e.g., "ABCD"
+const state = { players: {} }
+const sync = wt.sync(state)
+await sync.join('room-code')
+state.players[sync.myId] = { x: 0, y: 0 }
+// Others appear in state.players automatically!
 ```
 
 ## Cloud Saves
 
-Simple key-value storage per player. Works across devices.
+Key-value storage per player. JSON in, JSON out.
 
 ```typescript
-// Save anything JSON-serializable
+// Save
 await wt.save('progress', { level: 5, coins: 100 })
 await wt.save('settings', { music: true, sfx: true })
-await wt.save('inventory', ['sword', 'shield', 'potion'])
 
-// Load it back
+// Load
 const progress = await wt.load('progress')
 const settings = await wt.load('settings')
 
-// List all save keys
-const keys = await wt.listSaves() // ['progress', 'settings', 'inventory']
+// List all saves
+const keys = await wt.listSaves() // ['progress', 'settings']
 
-// Delete a save
-await wt.deleteSave('inventory')
+// Delete
+await wt.deleteSave('progress')
 ```
 
-## Multiplayer Rooms
+## Multiplayer
 
-Create rooms with 4-letter codes. Share with friends to play together.
+Point at your game state. Join a room. State syncs automatically.
 
 ```typescript
-// Create a room (you become the host)
-const room = await wt.createRoom()
-console.log('Room code:', room.code)
-
-// Join an existing room
-const room = await wt.joinRoom('ABCD')
-
-// Check room properties
-room.isHost      // true if you're the host
-room.hostId      // current host's player ID
-room.playerId    // your player ID
-room.playerCount // number of players
-room.players     // all players' states
-```
+// Your game state
+const state = { players: {} }
 
-## Player State Sync
+// Connect to Watchtower
+const sync = wt.sync(state)
 
-Automatically sync your player's position/state to all other players.
+// Join a room
+await sync.join('my-room')
 
-```typescript
-// Set your player state (automatically synced at 20Hz)
-room.player.set({
-  x: 100,
-  y: 200,
-  sprite: 'running',
-  health: 100
-})
-
-// State is merged, so you can update individual fields
-room.player.set({ x: 150 }) // keeps y, sprite, health
+// Add yourself
+state.players[sync.myId] = {
+  x: 0,
+  y: 0,
+  name: 'Player1'
+}
 
-// Force immediate sync
-room.player.sync()
+// Move (automatically syncs to others!)
+state.players[sync.myId].x += 5
 
-// See all players' states
-room.on('players', (players) => {
-  for (const [playerId, state] of Object.entries(players)) {
-    if (playerId !== room.playerId) {
-      // Update other player's sprite
-      updateOtherPlayer(playerId, state.x, state.y, state.sprite)
-    }
-  }
-})
+// Draw everyone (others appear automatically!)
+for (const [id, player] of Object.entries(state.players)) {
+  drawPlayer(player.x, player.y)
+}
 ```
 
-## Game State (Host-Controlled)
+No events. No message handlers. Just read and write your state.
 
-Shared state for things like game phase, scores, round number. Only the host can modify it.
+### Creating & Joining Rooms
 
 ```typescript
-// Host sets game state
-if (room.isHost) {
-  room.state.set({
-    phase: 'lobby',
-    round: 0,
-    scores: {}
-  })
-  
-  // Start the game
-  room.state.set({ phase: 'playing', round: 1 })
-}
+// Create a new room
+const code = await sync.create({ maxPlayers: 4 })
+console.log('Share this code:', code)  // e.g., "A3B7X2"
 
-// Everyone receives state updates
-room.on('state', (state) => {
-  if (state.phase === 'playing') {
-    startGame()
-  }
-  if (state.phase === 'gameover') {
-    showWinner(state.winner)
-  }
-})
+// Join existing room
+await sync.join('A3B7X2')
 
-// Read current state anytime
-const currentState = room.state.get()
-```
+// Leave room
+await sync.leave()
 
-## Broadcast Messages
+// List public rooms
+const rooms = await sync.listRooms()
+```
 
-For one-off events that don't need persistent state.
+### Options
 
 ```typescript
-// Broadcast to all players
-room.broadcast({ type: 'explosion', x: 50, y: 50 })
-room.broadcast({ type: 'chat', message: 'gg!' })
-
-// Send to specific player
-room.sendTo(playerId, { type: 'private_message', text: 'hey' })
-
-// Receive messages
-room.on('message', (from, data) => {
-  if (data.type === 'explosion') {
-    createExplosion(data.x, data.y)
-  }
-  if (data.type === 'chat') {
-    showChat(from, data.message)
-  }
+const sync = wt.sync(state, {
+  tickRate: 20,       // Updates per second (default: 20)
+  interpolate: true   // Smooth remote movement (default: true)
 })
 ```
 
-## Room Events
+### Properties
 
 ```typescript
-// Connection established
-room.on('connected', ({ playerId, room }) => {
-  console.log('Connected as', playerId)
-  console.log('Host is', room.hostId)
-})
+sync.myId      // Your player ID
+sync.roomId    // Current room, or null
+sync.connected // WebSocket connected?
+```
 
-// Player joined
-room.on('playerJoined', (playerId, playerCount) => {
-  console.log(`${playerId} joined (${playerCount} players)`)
-  spawnPlayer(playerId)
-})
+### Events (Optional)
 
-// Player left
-room.on('playerLeft', (playerId, playerCount) => {
-  console.log(`${playerId} left (${playerCount} players)`)
-  removePlayer(playerId)
-})
+You don't need events—just read your state. But if you want notifications:
 
-// Host changed (automatic migration when host leaves)
-room.on('hostChanged', (newHostId) => {
-  console.log('New host:', newHostId)
-  if (newHostId === room.playerId) {
-    console.log("I'm the host now!")
-  }
-})
-
-// Disconnected
-room.on('disconnected', () => {
-  console.log('Lost connection')
-})
-
-// Error
-room.on('error', (error) => {
-  console.error('Room error:', error)
-})
+```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'))
 ```
 
-## Host Transfer
+### Chat & Messages
+
+Messages are just state:
 
 ```typescript
-// Host can transfer to another player
-if (room.isHost) {
-  room.transferHost(otherPlayerId)
-}
+state.chat = [
+  ...state.chat.slice(-50),  // Keep last 50
+  { from: sync.myId, text: 'Hello!', ts: Date.now() }
+]
 ```
 
-## Full Example: Simple Multiplayer Game
+## Full Example
 
 ```typescript
-import { Watchtower } from '@watchtower/sdk'
+import { Watchtower } from '@watchtower-sdk/core'
 
 const wt = new Watchtower({ gameId: 'my-game', apiKey: 'wt_...' })
+const state = { players: {} }
+const sync = wt.sync(state)
 
 // Join or create room
-async function joinGame(code?: string) {
-  const room = code 
-    ? await wt.joinRoom(code)
-    : await wt.createRoom()
-  
-  console.log('Room:', room.code)
+const code = prompt('Room code? (blank to create)')
+if (code) {
+  await sync.join(code)
+} else {
+  const newCode = await sync.create()
+  alert('Share: ' + newCode)
+}
+
+// Add yourself
+state.players[sync.myId] = {
+  x: Math.random() * 800,
+  y: Math.random() * 600,
+  color: '#' + Math.floor(Math.random()*16777215).toString(16)
+}
+
+// Game loop
+function loop() {
+  // Move
+  if (keys.left)  state.players[sync.myId].x -= 5
+  if (keys.right) state.players[sync.myId].x += 5
+  if (keys.up)    state.players[sync.myId].y -= 5
+  if (keys.down)  state.players[sync.myId].y += 5
   
-  // Game loop - update player position
-  function gameLoop() {
-    room.player.set({
-      x: myPlayer.x,
-      y: myPlayer.y,
-      animation: myPlayer.currentAnim
-    })
-    requestAnimationFrame(gameLoop)
+  // Draw everyone
+  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)
   }
-  gameLoop()
-  
-  // Render other players
-  const otherPlayers: Record<string, Sprite> = {}
-  
-  room.on('players', (players) => {
-    for (const [id, state] of Object.entries(players)) {
-      if (id === room.playerId) continue
-      
-      // Create sprite if new player
-      if (!otherPlayers[id]) {
-        otherPlayers[id] = createSprite()
-      }
-      
-      // Update position
-      otherPlayers[id].x = state.x as number
-      otherPlayers[id].y = state.y as number
-      otherPlayers[id].play(state.animation as string)
-    }
-  })
-  
-  // Clean up when players leave
-  room.on('playerLeft', (id) => {
-    otherPlayers[id]?.destroy()
-    delete otherPlayers[id]
-  })
-  
-  // Handle game events
-  room.on('message', (from, data: any) => {
-    if (data.type === 'shoot') {
-      createBullet(data.x, data.y, data.dir)
-    }
-  })
   
-  // Game state (host manages rounds, scores)
-  room.on('state', (state: any) => {
-    if (state.phase === 'playing') {
-      showRound(state.round)
-    }
-    if (state.phase === 'gameover') {
-      showWinner(state.winner)
-    }
-  })
-  
-  // If we're host, start game when 2 players join
-  room.on('playerJoined', (_, count) => {
-    if (room.isHost && count >= 2) {
-      room.state.set({ phase: 'playing', round: 1 })
-    }
-  })
-  
-  return room
+  requestAnimationFrame(loop)
 }
+loop()
 ```
 
 ## API Reference
@@ -285,51 +188,40 @@ async function joinGame(code?: string) {
 ### Watchtower
 
 ```typescript
-const wt = new Watchtower(config)
+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>
+
+// Multiplayer
+wt.sync(state: object, options?: SyncOptions): Sync
 ```
 
-| Config | Type | Description |
-|--------|------|-------------|
-| `gameId` | `string` | Your game's unique identifier |
-| `apiKey` | `string` | API key from dashboard |
-| `playerId` | `string?` | Custom player ID (auto-generated if not provided) |
-| `apiUrl` | `string?` | Custom API URL (default: Watchtower API) |
-
-### Room
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `code` | `string` | 4-letter room code |
-| `isHost` | `boolean` | True if you're the host |
-| `hostId` | `string` | Current host's player ID |
-| `playerId` | `string` | Your player ID |
-| `playerCount` | `number` | Number of players |
-| `players` | `PlayersState` | All players' states |
-| `connected` | `boolean` | Connection status |
-
-| Method | Description |
-|--------|-------------|
-| `player.set(state)` | Set your player state (auto-synced) |
-| `player.get()` | Get your current player state |
-| `player.sync()` | Force immediate sync |
-| `state.set(state)` | Set game state (host only) |
-| `state.get()` | Get current game state |
-| `broadcast(data)` | Send to all players |
-| `sendTo(id, data)` | Send to specific player |
-| `transferHost(id)` | Transfer host (host only) |
-| `disconnect()` | Leave the room |
-
-| Event | Callback | Description |
-|-------|----------|-------------|
-| `connected` | `({playerId, room}) => void` | Connected to room |
-| `players` | `(players) => void` | Player states updated |
-| `state` | `(state) => void` | Game state updated |
-| `playerJoined` | `(id, count) => void` | Player joined |
-| `playerLeft` | `(id, count) => void` | Player left |
-| `hostChanged` | `(newHostId) => void` | Host changed |
-| `message` | `(from, data) => void` | Received broadcast |
-| `disconnected` | `() => void` | Lost connection |
-| `error` | `(error) => void` | Error occurred |
+### Sync
+
+```typescript
+sync.myId: string
+sync.roomId: string | null
+sync.connected: boolean
+
+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[]>
+
+sync.on(event: string, callback: Function): void
+sync.off(event: string, callback: Function): void
+```
 
 ## License
 

package/dist/index.d.mts

@@ -206,6 +206,123 @@ declare class Room {
     /** Check if connected */
     get connected(): boolean;
 }
+interface SyncOptions {
+    /** Updates per second (default: 20) */
+    tickRate?: number;
+    /** Enable interpolation for remote entities (default: true) */
+    interpolate?: boolean;
+}
+interface JoinOptions {
+    /** Create room if it doesn't exist */
+    create?: boolean;
+    /** Max players (only on create) */
+    maxPlayers?: number;
+    /** Make room public/discoverable (only on create) */
+    public?: boolean;
+    /** Room metadata (only on create) */
+    metadata?: Record<string, unknown>;
+}
+interface RoomListing {
+    id: string;
+    players: number;
+    maxPlayers?: number;
+    metadata?: Record<string, unknown>;
+    createdAt: number;
+}
+/**
+ * Sync - Automatic state synchronization
+ *
+ * Point this at your game state object and it becomes multiplayer.
+ * No events, no callbacks - just read and write your state.
+ *
+ * @example
+ * ```ts
+ * const state = { players: {} }
+ * const sync = wt.sync(state)
+ *
+ * await sync.join('my-room')
+ *
+ * // Add yourself
+ * state.players[sync.myId] = { x: 0, y: 0, name: 'Player1' }
+ *
+ * // Move (automatically syncs to others)
+ * state.players[sync.myId].x = 100
+ *
+ * // Others appear automatically in state.players!
+ * for (const [id, player] of Object.entries(state.players)) {
+ *   draw(player.x, player.y)
+ * }
+ * ```
+ */
+declare class Sync<T extends Record<string, unknown>> {
+    /** The synchronized state object */
+    readonly state: T;
+    /** Your player ID */
+    readonly myId: string;
+    /** Current room ID (null if not in a room) */
+    get roomId(): string | null;
+    /** Whether currently connected to a room */
+    get connected(): boolean;
+    private config;
+    private options;
+    private _roomId;
+    private ws;
+    private syncInterval;
+    private lastSentState;
+    private interpolationTargets;
+    private listeners;
+    constructor(state: T, config: Required<WatchtowerConfig>, options?: SyncOptions);
+    /**
+     * Join a room - your state will sync with everyone in this room
+     *
+     * @param roomId - Room identifier (any string)
+     * @param options - Join options
+     */
+    join(roomId: string, options?: JoinOptions): Promise<void>;
+    /**
+     * Leave the current room
+     */
+    leave(): Promise<void>;
+    /**
+     * Send a one-off message to all players in the room
+     *
+     * @param data - Any JSON-serializable data
+     */
+    broadcast(data: unknown): void;
+    /**
+     * Create a new room and join it
+     *
+     * @param options - Room creation options
+     * @returns The room code/ID
+     */
+    create(options?: Omit<JoinOptions, 'create'>): Promise<string>;
+    /**
+     * List public rooms
+     */
+    listRooms(): Promise<RoomListing[]>;
+    /**
+     * Subscribe to sync events
+     */
+    on(event: 'join' | 'leave' | 'error' | 'connected' | 'disconnected' | 'message', callback: Function): void;
+    /**
+     * Unsubscribe from sync events
+     */
+    off(event: string, callback: Function): void;
+    private emit;
+    private connectWebSocket;
+    private handleMessage;
+    private applyFullState;
+    private applyPlayerState;
+    private removePlayer;
+    private clearRemotePlayers;
+    private findPlayersKey;
+    private startSyncLoop;
+    private stopSyncLoop;
+    private syncMyState;
+    private updateInterpolation;
+    private generateRoomCode;
+    private getHeaders;
+}
 declare class Watchtower {
     /** @internal - Config is non-enumerable to prevent accidental API key exposure */
     private readonly config;
@@ -291,6 +408,36 @@ declare class Watchtower {
      * Note: This returns a promise, use `await wt.stats` or `wt.getStats()`
      */
     get stats(): Promise<GameStats>;
+    /**
+     * Create a synchronized state object
+     *
+     * Point this at your game state and it becomes multiplayer.
+     * No events, no callbacks - just read and write your state.
+     *
+     * @param state - Your game state object (e.g., { players: {} })
+     * @param options - Sync options (tickRate, interpolation)
+     * @returns A Sync instance
+     *
+     * @example
+     * ```ts
+     * const state = { players: {} }
+     * const sync = wt.sync(state)
+     *
+     * await sync.join('my-room')
+     *
+     * // Add yourself
+     * state.players[sync.myId] = { x: 0, y: 0 }
+     *
+     * // Move (automatically syncs to others)
+     * state.players[sync.myId].x = 100
+     *
+     * // Others appear automatically in state.players!
+     * for (const [id, player] of Object.entries(state.players)) {
+     *   draw(player.x, player.y)
+     * }
+     * ```
+     */
+    sync<T extends Record<string, unknown>>(state: T, options?: SyncOptions): Sync<T>;
 }
 
-export { type GameState, type GameStats, type PlayerInfo, type PlayerState, type PlayerStats, type PlayersState, Room, type RoomEventMap, type RoomInfo, type SaveData, Watchtower, type WatchtowerConfig, Watchtower as default };
+export { type GameState, type GameStats, type JoinOptions, type PlayerInfo, type PlayerState, type PlayerStats, type PlayersState, Room, type RoomEventMap, type RoomInfo, type RoomListing, type SaveData, Sync, type SyncOptions, Watchtower, type WatchtowerConfig, Watchtower as default };