Multiplayer overview

Learn about tldraw’s real-time multiplayer synchronization system

Multiplayer overview

The tldraw multiplayer system enables real-time collaboration through WebSocket-based synchronization. Multiple users can work on the same canvas simultaneously with automatic conflict resolution, live cursors, and presence awareness.

Architecture

The sync system uses a client-server architecture with three main components:

• Client: TLSyncClient manages local state and bidirectional sync with the server
• Server: TLSyncRoom acts as the authoritative source and broadcasts changes
• Storage: Pluggable storage layer for persistence (in-memory, SQLite, or custom)

How it works

The synchronization follows a git-like push/pull/rebase model:

1. Local changes

   When you make changes locally, they’re immediately applied to your store for responsive UI

2. Push to server

   Local changes are sent to the server as diff operations

3. Server validation

   The server validates changes and resolves any conflicts

4. Broadcast

   Validated changes are broadcast to all other connected clients

5. Rebase on conflict

   If conflicts occur, the client undoes local changes, applies server changes, then re-applies local changes on top

Key features

Real-time synchronization

Changes are synchronized at 30 FPS when collaborating, dropping to 1 FPS when working solo to conserve bandwidth.

Presence awareness

See live cursors, selections, and viewport positions of other users. The presence system operates independently from document synchronization.

Conflict resolution

Automatic conflict resolution ensures consistency across all clients. The server acts as the source of truth.

Optimistic updates

Local changes are applied immediately for responsiveness, then reconciled with the server asynchronously.

Schema migrations

Built-in support for schema versioning allows clients on different versions to collaborate safely with automatic down-migrations.

Packages

The multiplayer system is split across two npm packages:

@tldraw/sync

React hooks and utilities for client-side multiplayer:

import { useSync } from '@tldraw/sync'

const store = useSync({
  uri: 'wss://myserver.com/sync/room-123',
  assets: myAssetStore
})

@tldraw/sync-core

Core synchronization primitives for both client and server:

import { TLSyncClient, TLSyncRoom } from '@tldraw/sync-core'

The sync-core package is lower-level. Most applications should use the useSync hook from @tldraw/sync instead.

Connection states

The sync client progresses through several states:

State	Description
loading	Establishing connection and loading initial state
synced-remote	Connected and actively synchronizing
error	Connection failed or sync error occurred

Protocol

The sync protocol uses WebSocket messages with the following event types:

Client → Server:

• connect - Initial handshake with schema and protocol version
• push - Send local changes to server
• ping - Keep-alive message

Server → Client:

• connect - Connection acknowledgment with initial state
• patch - Document changes to apply
• push_result - Acknowledgment of client push (commit, discard, or rebase)
• pong - Keep-alive response
• data - Batched data messages for efficiency

Next steps

Quick start

Get multiplayer running in 5 minutes

Setup guide

Detailed setup instructions

Client API

Client-side API reference

Server API

Server-side API reference