Real-Time Collaboration: Building Multiplayer Experiences

Real-time collaboration enables multiple users to work together simultaneously. This guide covers the patterns and technologies for building collaborative features.

WebSocket Fundamentals#

Server Setup#

import { WebSocketServer, WebSocket } from 'ws';

interface Client {
  id: string;
  ws: WebSocket;
  room: string;
}

class CollaborationServer {
  private wss: WebSocketServer;
  private clients: Map<string, Client> = new Map();
  private rooms: Map<string, Set<string>> = new Map();

  constructor(port: number) {
    this.wss = new WebSocketServer({ port });

    this.wss.on('connection', (ws) => {
      const clientId = crypto.randomUUID();

      ws.on('message', (data) => {
        const message = JSON.parse(data.toString());
        this.handleMessage(clientId, message);
      });

      ws.on('close', () => {
        this.removeClient(clientId);
      });

      this.clients.set(clientId, { id: clientId, ws, room: '' });
      ws.send(JSON.stringify({ type: 'connected', clientId }));
    });
  }

  private handleMessage(clientId: string, message: any) {
    switch (message.type) {
      case 'join':
        this.joinRoom(clientId, message.room);
        break;
      case 'broadcast':
        this.broadcast(clientId, message.data);
        break;
      case 'cursor':
        this.broadcastCursor(clientId, message.position);
        break;
    }
  }

  private joinRoom(clientId: string, room: string) {
    const client = this.clients.get(clientId);
    if (!client) return;

    // Leave previous room
    if (client.room) {
      this.rooms.get(client.room)?.delete(clientId);
    }

    // Join new room
    client.room = room;
    if (!this.rooms.has(room)) {
      this.rooms.set(room, new Set());
    }
    this.rooms.get(room)!.add(clientId);

    // Notify room members
    this.broadcastToRoom(room, {
      type: 'user-joined',
      clientId,
    }, clientId);
  }

  private broadcast(clientId: string, data: any) {
    const client = this.clients.get(clientId);
    if (!client?.room) return;

    this.broadcastToRoom(client.room, {
      type: 'update',
      from: clientId,
      data,
    }, clientId);
  }

  private broadcastToRoom(room: string, message: any, excludeClient?: string) {
    const roomClients = this.rooms.get(room);
    if (!roomClients) return;

    const payload = JSON.stringify(message);
    for (const clientId of roomClients) {
      if (clientId === excludeClient) continue;
      this.clients.get(clientId)?.ws.send(payload);
    }
  }
}

Client Connection#

class CollaborationClient {
  private ws: WebSocket;
  private listeners: Map<string, Set<(data: any) => void>> = new Map();

  constructor(url: string) {
    this.ws = new WebSocket(url);

    this.ws.onmessage = (event) => {
      const message = JSON.parse(event.data);
      this.emit(message.type, message);
    };
  }

  join(room: string) {
    this.send({ type: 'join', room });
  }

  broadcast(data: any) {
    this.send({ type: 'broadcast', data });
  }

  on(event: string, callback: (data: any) => void) {
    if (!this.listeners.has(event)) {
      this.listeners.set(event, new Set());
    }
    this.listeners.get(event)!.add(callback);
  }

  private send(message: any) {
    this.ws.send(JSON.stringify(message));
  }

  private emit(event: string, data: any) {
    this.listeners.get(event)?.forEach(cb => cb(data));
  }
}

Presence and Cursors#

Tracking User Presence#

interface UserPresence {
  id: string;
  name: string;
  color: string;
  cursor: { x: number; y: number } | null;
  selection: { start: number; end: number } | null;
  lastSeen: number;
}

class PresenceManager {
  private presence: Map<string, UserPresence> = new Map();
  private client: CollaborationClient;

  constructor(client: CollaborationClient) {
    this.client = client;

    client.on('presence', (data) => {
      this.presence.set(data.userId, data.presence);
      this.onPresenceChange();
    });

    client.on('user-left', (data) => {
      this.presence.delete(data.userId);
      this.onPresenceChange();
    });

    // Heartbeat
    setInterval(() => {
      this.sendPresence();
    }, 1000);
  }

  updateCursor(position: { x: number; y: number }) {
    this.sendPresence({ cursor: position });
  }

  updateSelection(selection: { start: number; end: number }) {
    this.sendPresence({ selection });
  }

  private sendPresence(update?: Partial<UserPresence>) {
    this.client.broadcast({
      type: 'presence',
      ...update,
    });
  }

  getOtherUsers(): UserPresence[] {
    return Array.from(this.presence.values());
  }

  private onPresenceChange() {
    // Trigger React re-render or update UI
  }
}

React Cursor Component#

function CollaborativeCursors({ users }: { users: UserPresence[] }) {
  return (
    <>
      {users.map(user => (
        user.cursor && (
          <div
            key={user.id}
            className="absolute pointer-events-none transition-all duration-75"
            style={{
              left: user.cursor.x,
              top: user.cursor.y,
            }}
          >
            <svg
              width="24"
              height="24"
              viewBox="0 0 24 24"
              fill={user.color}
            >
              <path d="M5.5 3.21V20.8l4.86-4.86h9.36L5.5 3.21z" />
            </svg>
            <span
              className="ml-2 px-2 py-1 rounded text-white text-xs"
              style={{ backgroundColor: user.color }}
            >
              {user.name}
            </span>
          </div>
        )
      ))}
    </>
  );
}

Conflict Resolution#

Operational Transform (OT)#

interface Operation {
  type: 'insert' | 'delete';
  position: number;
  content?: string;
  length?: number;
}

function transformOperation(op1: Operation, op2: Operation): Operation {
  const transformed = { ...op1 };

  if (op1.position <= op2.position) {
    // op1 comes before op2, no change needed
    return transformed;
  }

  if (op2.type === 'insert') {
    // Shift op1 position by inserted length
    transformed.position += op2.content!.length;
  } else if (op2.type === 'delete') {
    // Shift op1 position by deleted length
    transformed.position -= Math.min(op2.length!, op1.position - op2.position);
  }

  return transformed;
}

class OTDocument {
  private content: string = '';
  private revision: number = 0;
  private pendingOps: Operation[] = [];

  applyLocal(op: Operation) {
    this.content = this.apply(this.content, op);
    this.pendingOps.push(op);
    // Send to server
  }

  applyRemote(op: Operation, serverRevision: number) {
    // Transform against pending ops
    let transformed = op;
    for (const pending of this.pendingOps) {
      transformed = transformOperation(transformed, pending);
    }

    this.content = this.apply(this.content, transformed);
    this.revision = serverRevision;
  }

  private apply(content: string, op: Operation): string {
    if (op.type === 'insert') {
      return content.slice(0, op.position) +
             op.content +
             content.slice(op.position);
    } else {
      return content.slice(0, op.position) +
             content.slice(op.position + op.length!);
    }
  }
}

CRDT (Conflict-free Replicated Data Types)#

// Simple LWW (Last-Writer-Wins) Map CRDT
interface LWWEntry<T> {
  value: T;
  timestamp: number;
  clientId: string;
}

class LWWMap<T> {
  private entries: Map<string, LWWEntry<T>> = new Map();

  set(key: string, value: T, clientId: string) {
    const existing = this.entries.get(key);
    const timestamp = Date.now();

    if (!existing || timestamp > existing.timestamp ||
        (timestamp === existing.timestamp && clientId > existing.clientId)) {
      this.entries.set(key, { value, timestamp, clientId });
    }
  }

  get(key: string): T | undefined {
    return this.entries.get(key)?.value;
  }

  merge(other: LWWMap<T>) {
    for (const [key, entry] of other.entries) {
      const existing = this.entries.get(key);

      if (!existing || entry.timestamp > existing.timestamp ||
          (entry.timestamp === existing.timestamp && entry.clientId > existing.clientId)) {
        this.entries.set(key, entry);
      }
    }
  }

  toJSON() {
    return Object.fromEntries(this.entries);
  }
}

Using Yjs for Complex Documents#

import * as Y from 'yjs';
import { WebsocketProvider } from 'y-websocket';

// Initialize shared document
const ydoc = new Y.Doc();
const ytext = ydoc.getText('content');
const provider = new WebsocketProvider('wss://server.com', 'room-id', ydoc);

// Local edits
ytext.insert(0, 'Hello ');
ytext.insert(6, 'World');

// Listen for changes
ytext.observe((event) => {
  console.log('Document changed:', ytext.toString());
});

// Awareness (presence)
const awareness = provider.awareness;

awareness.setLocalState({
  user: {
    name: 'Alice',
    color: '#ff0000',
  },
  cursor: { x: 100, y: 200 },
});

awareness.on('change', () => {
  const states = awareness.getStates();
  // Update cursor UI
});

Optimistic Updates#

class OptimisticStore<T> {
  private confirmedState: T;
  private pendingChanges: Array<{
    id: string;
    apply: (state: T) => T;
    revert: (state: T) => T;
  }> = [];

  constructor(initialState: T) {
    this.confirmedState = initialState;
  }

  getState(): T {
    return this.pendingChanges.reduce(
      (state, change) => change.apply(state),
      this.confirmedState
    );
  }

  applyOptimistic(
    id: string,
    apply: (state: T) => T,
    revert: (state: T) => T
  ) {
    this.pendingChanges.push({ id, apply, revert });
    return this.getState();
  }

  confirm(id: string, newConfirmedState: T) {
    this.confirmedState = newConfirmedState;
    this.pendingChanges = this.pendingChanges.filter(c => c.id !== id);
  }

  reject(id: string) {
    this.pendingChanges = this.pendingChanges.filter(c => c.id !== id);
  }
}

Best Practices#

Handle reconnection: Sync state after connection drops
Implement throttling: Don't send every keystroke
Show connection status: Users should know when they're offline
Graceful degradation: App should work without collaboration
Conflict visualization: Show when conflicts occur

Conclusion#

Real-time collaboration requires careful handling of concurrent edits. Start with simple presence features and WebSockets, then add conflict resolution with CRDTs or OT as needed.

Share this article