SDK Reference

Complete API reference for the Watchtower JavaScript/TypeScript SDK.

connect()

import { connect } from '@watchtower-sdk/core'

const room = await connect(roomId?: string, options?: ConnectOptions)

Connect to a room. Creates the room if it doesn't exist.

Parameters

Returns

Promise<Room> — A connected Room instance.

Examples

// Join or create room
const room = await connect('ABCD')

// Auto-generate room code
const room = await connect()
console.log('Share:', room.code)

// With player info
const room = await connect('ABCD', {
  name: 'Player1',
  meta: { avatar: 'knight', color: '#ff0000' }
})

// With debug logging
const room = await connect('ABCD', { debug: true })

Room

Properties

Messaging Methods

broadcast(data)

room.broadcast(data: unknown): void

Send data to all players in the room.

room.broadcast({ type: 'move', x: 100, y: 200 })
room.broadcast({ type: 'chat', text: 'Hello!' })

send(playerId, data)

room.send(playerId: string, data: unknown): void

Send data to a specific player.

room.send('player123', { type: 'private', text: 'Hey!' })

Host Methods

kick(playerId, reason?)

room.kick(playerId: string, reason?: string): void

Kick a player from the room. Only works if you are the host.

if (room.isHost) {
  room.kick('player123', 'Breaking rules')
}

Throws an error if:

• You are not the host
• You try to kick yourself

Lifecycle Methods

leave()

room.leave(): void

Leave the room and disconnect.

Event Methods

on(event, callback)

room.on(event: string, callback: Function): void

Subscribe to events.

off(event, callback)

room.off(event: string, callback: Function): void

Unsubscribe from events.

Events

message

room.on('message', (from: string, data: unknown, meta: MessageMeta) => void)

Fired when a message is received from another player.

join

room.on('join', (player: Player) => void)

Fired when a player joins the room.

leave

room.on('leave', (player: Player) => void)

Fired when a player leaves the room (or is kicked).

kicked

room.on('kicked', (reason?: string) => void)

Fired when you are kicked from the room. Auto-reconnect is disabled after being kicked.

room.on('kicked', (reason) => {
  console.log('You were kicked:', reason)
  // Show UI, redirect, etc.
})

connected

room.on('connected', () => void)

Fired when connected to the room.

disconnected

room.on('disconnected', () => void)

Fired when disconnected. Auto-reconnect will attempt (unless kicked).

error

room.on('error', (error: Error) => void)

Fired on connection errors.

Debug Mode

Enable debug logging to see all WebSocket activity in the console:

const room = await connect('my-room', { debug: true })

// Console output:
// [Watchtower] Connecting to my-room
// [Watchtower] Connected! playerId: p_abc123 isHost: true
// [Watchtower] ← join { playerId: 'p_xyz789', ... }
// [Watchtower] → broadcast { x: 100, y: 200 }
// [Watchtower] Player joined: p_xyz789
// [Watchtower] Reconnecting in 1000 ms (attempt 1)

Event History

The room.history property contains recent events (up to 50) from the room. This is populated on connect with events that occurred before you joined.

// Access recent events
console.log(room.history)

// Each event has at minimum:
interface HistoryEvent {
  type: string      // 'join' | 'leave' | 'message' | 'kicked'
  serverTime: number
  tick: number
  // ... other fields depending on type
}

Useful for:

• Showing recent chat messages to new players
• Replaying recent game moves
• Displaying who joined/left recently

Types

interface ConnectOptions {
  gameId?: string
  playerId?: string
  apiUrl?: string
  name?: string
  meta?: Record<string, unknown>
  debug?: boolean
}

interface Player {
  id: string
  name?: string
  meta?: Record<string, unknown>
  joinedAt: number
}

interface MessageMeta {
  serverTime: number
  tick: number
}

interface HistoryEvent {
  type: string
  serverTime: number
  tick: number
  [key: string]: unknown
}