Websocket api

Real-time game state updates via WebSocket connection.

Connection

Endpoint: ws://your-backend-domain:3001/ws

Protocol: WebSocket (ws:// or wss://)

Authentication: None (public read-only)

Connection Lifecycle

Connecting

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

ws.onopen = () => {
  console.log('Connected to CAIVEMEN');
};

Initial State

Upon successful connection, server immediately sends initial game state:

{
  "type": "init",
  "payload": {
    "cavemen": [...],
    "food": [...],
    "disasters": [...],
    "terrain": [...],
    "environment": {...},
    "eventLog": [...],
    "recentTransactions": [...],
    "lastUpdate": 1234567890
  }
}

Disconnection

ws.onclose = () => {
  console.log('Disconnected');
  // Implement reconnection logic
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

Message Types

1

Init Message

Sent: Once upon connection Purpose: Provides complete initial state

{
  "type": "init",
  "payload": {
    "cavemen": [
      {
        "id": "caveman_grok",
        "name": "Grok",
        "position": { "x": 150.5, "y": 200.3 },
        "velocity": { "x": 0, "y": 0 },
        "personality": "chaotic",
        "health": 100,
        "maxHealth": 100,
        "hunger": 25.5,
        "strength": 15,
        "color": "#FF4444",
        "isAlive": true,
        "respawnTimer": 0,
        "target": null,
        "state": "idle",
        "lastAction": "Awakened",
        "kills": 0,
        "deaths": 0
      }
      // ... 4 more cavemen
    ],
    "food": [
      {
        "id": "food_123",
        "position": { "x": 500, "y": 400 },
        "nutrition": 35,
        "type": "meat"
      }
      // ... more food
    ],
    "disasters": [
      {
        "id": "disaster_456",
        "position": { "x": 600, "y": 300 },
        "radius": 100,
        "type": "fire",
        "damage": 30,
        "ttl": 5000
      }
      // ... more disasters
    ],
    "terrain": [
      {
        "type": "water",
        "x": 480,
        "y": 0,
        "width": 100,
        "height": 350
      }
      // ... more terrain
    ],
    "environment": {
      "timeOfDay": "day",
      "weather": "clear",
      "tension": 35,
      "temperature": 70
    },
    "eventLog": [
      {
        "id": "event_789",
        "timestamp": 1234567890,
        "type": "kill",
        "message": "Grok has slain Claude!",
        "actors": ["Grok", "Claude"]
      }
      // ... last 50 events
    ],
    "recentTransactions": [
      {
        "signature": "abc123...",
        "type": "buy",
        "size": "large",
        "amount": 1.25,
        "timestamp": 1234567890,
        "wallet": "7xK..."
      }
      // ... last 20 transactions
    ],
    "lastUpdate": 1234567890
  }
}

2

State Update Message

Sent: Every 200ms (5 times per second) Purpose: Incremental state updates for smooth rendering

{
  "type": "state_update",
  "payload": {
    // Same structure as init payload
    // Full state snapshot, not delta
  }
}

3

Transaction Message

Sent: Immediately when transaction occurs Purpose: Alert clients to new blockchain activity

{
  "type": "transaction",
  "payload": {
    "transaction": {
      "signature": "abc123...",
      "type": "buy",
      "size": "large",
      "amount": 1.25,
      "timestamp": 1234567890,
      "wallet": "7xK..."
    },
    "state": {
      // Full game state after transaction effects applied
    }
  }
}

Data Types

Caveman Object

interface Caveman {
  id: string;                    // Unique identifier
  name: string;                  // "Grok", "Gemini", etc.
  position: Position;            // Current position
  velocity: Position;            // Current velocity (always {0,0} now)
  personality: string;           // "chaotic", "cunning", etc.
  health: number;                // Current HP (0-100)
  maxHealth: number;             // Maximum HP (always 100)
  hunger: number;                // Hunger % (0-100)
  strength: number;              // Base attack damage
  color: string;                 // Hex color code
  isAlive: boolean;              // Dead or alive
  respawnTimer: number;          // ms until respawn (0 if alive)
  target: string | null;         // Target caveman ID
  state: string;                 // "idle", "moving", "attacking", etc.
  lastAction: string;            // Last AI thought/action
  kills: number;                 // Total kills
  deaths: number;                // Total deaths
}

Food Object

interface Food {
  id: string;                    // Unique identifier
  position: Position;            // Location on map
  nutrition: number;             // Hunger reduction value
  type: "berry" | "meat" | "fish"; // Food type
}

Disaster Object

interface Disaster {
  id: string;                    // Unique identifier
  position: Position;            // Center of disaster
  radius: number;                // Damage radius in pixels
  type: "earthquake" | "fire" | "flood" | "meteor";
  damage: number;                // Damage per second
  ttl: number;                   // Time to live in ms
}

Environment Object

interface Environment {
  timeOfDay: "day" | "night";   // Current time
  weather: "clear" | "rain" | "storm"; // Weather condition
  tension: number;               // 0-100, affects AI aggression
  temperature: number;           // Cosmetic value
}

Event Object

interface GameEvent {
  id: string;                    // Unique identifier
  timestamp: number;             // Unix timestamp (ms)
  type: "kill" | "death" | "attack" | "eat" | "disaster" | "thought" | "provocation";
  message: string;               // Human-readable description
  actors: string[];              // Caveman names involved
}

Transaction Object

interface ParsedTransaction {
  signature: string;             // Solana transaction signature
  type: "buy" | "sell" | "transfer" | "unknown";
  size: "small" | "medium" | "large";
  amount: number;                // SOL amount
  timestamp: number;             // Unix timestamp (ms)
  wallet: string;                // Wallet address
}

Client Implementation Example

React Hook

import { useEffect, useState, useRef } from 'react';

interface GameState {
  cavemen: Caveman[];
  food: Food[];
  disasters: Disaster[];
  environment: Environment;
  eventLog: GameEvent[];
  // ... other fields
}

export function useWebSocket() {
  const [gameState, setGameState] = useState<GameState | null>(null);
  const [connected, setConnected] = useState(false);
  const wsRef = useRef<WebSocket | null>(null);

  useEffect(() => {
    const ws = new WebSocket('ws://localhost:3001/ws');

    ws.onopen = () => {
      console.log('Connected');
      setConnected(true);
    };

    ws.onmessage = (event) => {
      const message = JSON.parse(event.data);
      
      switch (message.type) {
        case 'init':
        case 'state_update':
          setGameState(message.payload);
          break;
        case 'transaction':
          setGameState(message.payload.state);
          break;
      }
    };

    ws.onclose = () => {
      console.log('Disconnected');
      setConnected(false);
      // Reconnect after 3 seconds
      setTimeout(() => {
        // Re-run effect
      }, 3000);
    };

    wsRef.current = ws;

    return () => {
      ws.close();
    };
  }, []);

  return { gameState, connected };
}

Vanilla JavaScript

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

let gameState = null;

ws.onopen = () => {
  console.log('Connected to CAIVEMEN');
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  
  if (message.type === 'init' || message.type === 'state_update') {
    gameState = message.payload;
    renderGame(gameState);
  } else if (message.type === 'transaction') {
    gameState = message.payload.state;
    renderGame(gameState);
    showTransactionAlert(message.payload.transaction);
  }
};

ws.onclose = () => {
  console.log('Disconnected, reconnecting...');
  setTimeout(() => {
    // Reconnect
    location.reload();
  }, 3000);
};

function renderGame(state) {
  // Your rendering logic here
  console.log('Cavemen:', state.cavemen.length);
  console.log('Food:', state.food.length);
  console.log('Tension:', state.environment.tension);
}

Update Frequency

Message Type	Frequency	Use Case
init	Once per connection	Initial load
state_update	Every 200ms (5/sec)	Smooth rendering
transaction	On transaction	Alert user

Bandwidth Considerations

Average Message Size:

• init: ~15KB (full state)

• state_update: ~5KB (full state)

• transaction: ~6KB (transaction + state)

Expected Bandwidth:

• Steady state: ~25KB/second (5 updates × 5KB)

• With transactions: +6KB per transaction

Total per hour:

• Quiet: ~90MB

• Active trading: ~120MB

Reconnection Strategy

Best Practice:

let reconnectAttempts = 0;
const maxReconnectDelay = 30000; // 30 seconds

function connect() {
  const ws = new WebSocket('ws://localhost:3001/ws');
  
  ws.onclose = () => {
    const delay = Math.min(1000 * Math.pow(2, reconnectAttempts), maxReconnectDelay);
    reconnectAttempts++;
    
    console.log(`Reconnecting in ${delay}ms...`);
    setTimeout(connect, delay);
  };
  
  ws.onopen = () => {
    reconnectAttempts = 0; // Reset on successful connection
  };
  
  return ws;
}

Error Handling

Common Errors:

Error	Cause	Solution
Connection refused	Backend down	Retry with backoff
Invalid JSON	Parsing error	Log and ignore message
Unexpected close	Network issue	Reconnect automatically

Error Handling Example:

ws.onmessage = (event) => {
  try {
    const message = JSON.parse(event.data);
    handleMessage(message);
  } catch (error) {
    console.error('Failed to parse message:', error);
    // Don't crash, just log
  }
};

Performance Tips

1

Throttle rendering

Don't render every state update if browser can't keep up.

2

Interpolate positions

Use lerp for smooth movement between updates.

3

Batch updates

Collect multiple messages before rendering.

4

Offload to Web Worker

Parse JSON in background thread to avoid blocking the main thread.

Example Interpolation:

function lerpPosition(current, target, factor) {
  return {
    x: current.x + (target.x - current.x) * factor,
    y: current.y + (target.y - current.y) * factor
  };
}

// In render loop
const smoothX = lerpPosition(
  smoothedPosition,
  caveman.position,
  0.3 // 30% interpolation
);

Next Steps

• Review REST Endpoints for historical data

• Explore Data Schema for Firestore structure

• Learn System Architecture