Sockets – Real-time Communication

The Collab Server offers comprehensive real-time features via sockets.

Connection

import { io } from 'socket.io-client';

const socket = io('http://localhost:4000', {
  query: {
    room: 'artwork:item-001',
    artworkId: 'item-001'
  }
});

Room Structure

Joining a Room

socket.emit('join-room', { room: 'artwork:item-001' });

Communication Modes

1. Artwork ↔ Artwork

Direct communication between artworks:

// Send
socket.emit('artwork:message', {
  type: 'custom-event',
  payload: { x: 100, y: 200 },
  targetRoom: 'artwork:item-002'
});

// Receive
socket.on('artwork:message', (data) => {
  console.log(data.payload);
});

2. Studio ↔ Artwork

Debugging and parameter control:

// Studio requests parameters
socket.emit('request-parameter-dump', {
  targetRoom: 'artwork:item-001'
});

// Artwork sends parameters
socket.on('request-parameter-dump', () => {
  socket.emit('parameter-dump', {
    type: 'parameter-dump',
    payload: tweakpane.exportState(),
    artworkId: 'item-001'
  });
});

3. Multi-Screen Entity Transfer

Transfer entities between screens:

// Entity exits screen on the right
socket.emit('entity:transfer', {
  entity: entityData,
  direction: 'right',
  sourceScreen: 'screen-1'
});

// Neighbor screen receives entity
socket.on('entity:receive', (data) => {
  spawnEntity(data.entity, 'left');
});

4. Input Broadcast

Shared inputs for all artworks:

// Broadcast mouse position
socket.emit('input:broadcast', {
  type: 'mouse',
  x: mouseX,
  y: mouseY
});

// All artworks receive
socket.on('input:broadcast', (data) => {
  sharedMouse.x = data.x;
  sharedMouse.y = data.y;
});

Event Types

Control Events

Data Events

System Events

Topology

For multi-screen installations:

socket.emit('topology:configure', {
  screens: [
    { id: 'screen-1', neighbors: { right: 'screen-2' } },
    { id: 'screen-2', neighbors: { left: 'screen-1', right: 'screen-3' } },
    { id: 'screen-3', neighbors: { left: 'screen-2' } }
  ]
});

Logging

Central log system:

// Send log
socket.emit('log', {
  level: 'info',
  message: 'Artwork started',
  artworkId: 'item-001',
  timestamp: Date.now()
});

// Receive logs (Studio)
socket.on('log', (data) => {
  console.log(`[${data.artworkId}] ${data.message}`);
});

Connection Status

socket.on('connect', () => {
  console.log('Connected:', socket.id);
});

socket.on('disconnect', (reason) => {
  console.log('Disconnected:', reason);
});

socket.on('connect_error', (error) => {
  console.error('Connection error:', error);
});

Best Practices

1. Work room-based – Don't broadcast globally
2. Minimize payload – Only send necessary data
3. Throttling – Throttle high-frequency events
4. Reconnect logic – Reconnect automatically
5. Error handling – Catch and log errors