WebSocket Protocol

Areloria uses WebSocket for real-time bidirectional communication between clients and server.

Connection

Standard Connection

const ws = new WebSocket('ws://localhost:3000/ws');

With Authentication

const ws = new WebSocket(`ws://localhost:3000/ws?token=${authToken}`);

Connection Lifecycle

Client                    Server
  │                          │
  │──── CONNECT ────────────▶│
  │                          │
  │◀─── WELCOME ─────────────│
  │                          │
  │──── INTENTS ────────────▶│ (10 Hz)
  │◀─── SNAPSHOTS ───────────│ (10 Hz)
  │◀─── EVENTS ─────────────│ (as needed)
  │                          │
  │──── DISCONNECT ─────────▶│

Message Types

Client → Server

Type	Frequency	Description
`intent`	On action	Player action intent
`chat`	On message	Chat message
`ping`	~1 Hz	Keepalive

Server → Client

Type	Frequency	Description
`welcome`	Once	Connection confirmed
`snapshot`	10 Hz	World state
`event`	As needed	Discrete events
`causal_catchup_summary`	After catchup window	Render-only side-channel summary of significant missed events
`player_join`	As needed	Player connected
`player_leave`	As needed	Player disconnected
`pong`	On ping	Keepalive response

Intent Protocol

The client sends wishes. The server assigns truth. Client time is diagnostic only. Server tickId, logicalIndex, receivedOrder, and deterministic hashes are authoritative.

Movement Intent

// Client sends: A wish
{
  type: 'intent',
  clientIntentId: 'move-0001', // debug/dedupe only
  payload: {
    action: 'move',
    data: {
      position: { x: 100, y: 200 },
      direction: 45  // degrees
    }
  }
}

// Server responds with accepted truth (in snapshot)
{
  tickId: 12345,           // Authoritative tick
  logicalIndex: 123450,    // Logical execution index
  receivedOrder: 7,        // Order among intents this tick
  canonicalIntentHash: '0xabc123...'  // Deterministic hash
}

Attack Intent

// Client sends: A wish
{
  type: 'intent',
  clientIntentId: 'attack-0001',
  payload: {
    action: 'attack',
    data: {
      targetId: 'npc-456',
      skillId: 'slash'  // optional
    }
  }
}

Skill Intent

// Client sends: A wish
{
  type: 'intent',
  clientIntentId: 'skill-0001',
  payload: {
    action: 'useSkill',
    data: {
      skillId: 'fireball',
      targetId: 'enemy-789'  // or position for AOE
    }
  }
}

Interact Intent

// Client sends: A wish
{
  type: 'intent',
  clientIntentId: 'interact-0001',
  payload: {
    action: 'interact',
    data: {
      targetId: 'npc-456',  // or 'resource-node-123'
      interactionType: 'talk' | 'trade' | 'gather'
    }
  }
}

Inventory Intent

// Client sends: A wish
{
  type: 'intent',
  clientIntentId: 'inventory-0001',
  payload: {
    action: 'inventory',
    data: {
      subAction: 'equip' | 'unequip' | 'move' | 'drop' | 'use',
      itemId: 'item-123',
      targetSlot: 5  // optional
    }
  }
}

Intent Truth Assignment

// Server assigns truth to accepted intents
interface ServerAcceptedIntent {
  tickId: TickId;              // When intent was processed
  logicalIndex: number;        // Order within tick
  receivedOrder: number;       // Among all intents this tick
  canonicalIntentHash: string; // Deterministic hash
}

// Client receives truth in snapshot
interface IntentConfirmation {
  clientIntentId: string;      // Client request ID for debugging/dedupe only
  serverTruth: ServerAcceptedIntent;
  success: boolean;
  reason?: string;             // If success=false
}

Snapshot Protocol

Full Snapshot

{
  type: 'snapshot',
  tickId: 12345,
  previousTickId: 12344,
  stateHash: '0xstate...',
  previousStateHash: '0xprev...',
  payload: {
    players: [
      {
        id: 'player-123',
        name: 'Hero',
        position: { x: 100, y: 200 },
        health: 100,
        maxHealth: 100,
        mana: 50,
        maxMana: 50,
        level: 5,
        equipment: { ... }
      }
    ],
    npcs: [
      {
        id: 'npc-456',
        name: 'Elder',
        position: { x: 150, y: 180 },
        health: 200,
        state: 'idle'
      }
    ],
    world: {
      time: 'day',
      weather: 'clear',
      chunkX: 0,
      chunkY: 0
    }
  }
}

Snapshot metadata must be server-derived from tick/runtime state. Wall-clock timestamps are telemetry only and must not drive simulation.

Delta Snapshot

For efficiency, servers may send deltas:

{
  type: 'snapshot',
  tickId: 12346,
  stateHash: '0xstate2...',
  payload: {
    delta: {
      players: {
        'player-123': { health: 95 }  // Only changed fields
      }
    },
    previousTickId: 12345,
    previousStateHash: '0xstate1...'
  }
}

Causal Catchup Summary

When a client rejoins after a disconnect or falls behind the live tick window, the server may emit a causal_catchup_summary message on the same WebSocket connection. The summary is a render-only side channel that describes significant events the client missed, so the UI can show a catchup banner without replaying every snapshot. The summary is advisory and never authoritative. Clients must not mutate gameplay state from it. Authoritative state still arrives through snapshot and event messages. The sideChannelOnly: true flag routes the payload to passive overlays or notifications.

Payload

type CausalCatchupEventType =
  | 'resource_depleted'
  | 'market_price_changed'
  | 'npc_activity_changed'
  | 'quest_completed'
  | 'combat_result'
  | 'governance_action'
  | 'legend_recorded';

interface CausalCatchupEventPayload {
  eventId: string;
  type: CausalCatchupEventType;
  tick: number;
  significancePerMille: number;  // 0-1000 importance score
  regionId: string;
  chunkKey: string;
  payloadHash: string;           // Deterministic hash of event data
  eventHash: string;             // Deterministic hash of event identity
}

interface CausalCatchupSummaryPayload {
  eventCount: number;
  firstTick: number | null;      // null when eventCount === 0
  lastTick: number | null;
  events: CausalCatchupEventPayload[];
  summaryHash: string;           // Deterministic hash of the full summary
  sideChannelOnly: true;
}

Example

{
  type: 'causal_catchup_summary',
  payload: {
    eventCount: 2,
    firstTick: 41200,
    lastTick: 41460,
    events: [
      {
        eventId: 'evt-001',
        type: 'resource_depleted',
        tick: 41200,
        significancePerMille: 720,
        regionId: 'region-north-3',
        chunkKey: '3:5',
        payloadHash: '0xabc...',
        eventHash: '0xdef...'
      },
      {
        eventId: 'evt-002',
        type: 'market_price_changed',
        tick: 41460,
        significancePerMille: 540,
        regionId: 'region-north-3',
        chunkKey: '3:5',
        payloadHash: '0x123...',
        eventHash: '0x456...'
      }
    ],
    summaryHash: '0x789...',
    sideChannelOnly: true
  }
}

Clients can render this through a passive overlay, for example: “Causal catchup observed: 2 event(s), ticks 41200–41460.”

Event Protocol

Combat Events

{
  type: 'event',
  tickId: 12347,
  payload: {
    eventType: 'damage',
    data: {
      sourceId: 'player-123',
      targetId: 'enemy-789',
      damage: 45,
      isCrit: false,
      damageType: 'physical'
    }
  }
}

Loot Events

{
  type: 'event',
  tickId: 12348,
  payload: {
    eventType: 'loot_drop',
    data: {
      lootId: 'loot-001',
      items: [
        { id: 'gold-coin', quantity: 100 }
      ],
      position: { x: 100, y: 200 }
    }
  }
}

Quest Events

{
  type: 'event',
  tickId: 12349,
  payload: {
    eventType: 'quest_progress',
    data: {
      questId: 'gather-wood',
      objectiveIndex: 0,
      current: 15,
      target: 20
    }
  }
}

Rate Limiting

Setting	Value
Max intents/second/player	60
Max chat messages/second/player	5
Max connections/player	1

Reconnection

Clients should implement reconnection:

class ReconnectingWS {
  maxRetries = 5;
  retryDelay = 1000;  // ms, client-side network backoff only

  onDisconnect() {
    this.state = 'reconnecting';
    this.retryCount++;

    if (this.retryCount <= this.maxRetries) {
      setTimeout(() => this.connect(), this.retryDelay * this.retryCount);
    }
  }
}

Client reconnect timers are network-side behavior only. They do not create simulation ticks or authoritative time.

State Recovery

After reconnect:

Client sends last known stateHash and tickId
Server compares with runtime truth
Server sends authoritative snapshot/delta and optional causal_catchup_summary
Client resumes normal rendering from server truth

Next Steps

REST API

REST endpoint reference

API Overview

Complete API reference

Client Architecture

Client networking implementation

Server Architecture

Server WebSocket handling

​WebSocket Protocol

​Connection

​Standard Connection

​With Authentication

​Connection Lifecycle

​Message Types

​Client → Server

​Server → Client

​Intent Protocol

​Movement Intent

​Attack Intent

​Skill Intent

​Interact Intent

​Inventory Intent

​Intent Truth Assignment

​Snapshot Protocol

​Full Snapshot

​Delta Snapshot

​Causal Catchup Summary

​Payload

​Example

​Event Protocol

​Combat Events

​Loot Events

​Quest Events

​Rate Limiting

​Reconnection

​State Recovery

​Next Steps