Drone Battles - WebSocket Documentation

Connection Details

Real-time message delivery via WebSocket

Endpoint & Transport

Endpoint: /socket.io
Transport: Socket.IO (WebSocket with fallback)

Connection Flow

How to establish and authenticate a WebSocket connection.

1. Connect to /socket.io using Socket.IO client
2. Receive 'connected' event
3. Emit 'authenticate' with {token: 'your_bearer_token'}
4. Receive 'authenticated' confirmation
5. Receive 'message' events in real-time as game events occur

Client → Server Events

Events your client emits to the server.

authenticate

Authenticate WebSocket connection

{
  "token": "string (bearer token from login)"
}

ping

Keepalive ping

No payload

Server → Client Events

Events your client listens for from the server.

connected

Connection established, awaiting authentication

{
  "message": "Connected. Please authenticate.",
  "status": "ok"
}

authenticated

Authentication successful

{
  "status": "ok",
  "user_id": "string"
}

message

Game message (action results, notifications)

{
  "action_id": "string (optional)",
  "details": "object",
  "drone_id": "string (optional)",
  "message_id": "string",
  "message_type": "string (action_completed, action_failed, etc.)",
  "subject": "string",
  "timestamp": "integer (cycle count)"
}

error

Error message

{
  "code": "string",
  "message": "string"
}

pong

Keepalive response

{
  "status": "ok"
}

Message Types

Types of messages delivered via the message event.

action_queued action_started action_completed action_failed action_rejected drone_destroyed equipment_destroyed building_action_queued building_action_completed building_action_failed building_destroyed score_update info warning error

Code Examples

Complete examples for connecting and receiving messages.

Python

# pip install python-socketio requests
import socketio
import requests

# Get auth token
resp = requests.post('http://localhost:5000/api/v1/auth/login',
    json={'username': 'player1', 'password': 'secret'})
token = resp.json()['token']

# Connect to WebSocket
sio = socketio.Client()

@sio.on('connected')
def on_connected(data):
    print('Connected, authenticating...')
    sio.emit('authenticate', {'token': token})

@sio.on('authenticated')
def on_authenticated(data):
    print(f"Authenticated as {data['user_id']}")

@sio.on('message')
def on_message(data):
    print(f"[{data['message_type']}] {data['subject']}")
    print(f"  Details: {data['details']}")

@sio.on('error')
def on_error(data):
    print(f"Error: {data['message']}")

sio.connect('http://localhost:5000')
sio.wait()  # Block and listen for messages

JavaScript

// npm install socket.io-client
import { io } from 'socket.io-client';

// Get auth token first
const loginResp = await fetch('http://localhost:5000/api/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ username: 'player1', password: 'secret' })
});
const { token } = await loginResp.json();

// Connect to WebSocket
const socket = io('http://localhost:5000');

socket.on('connected', (data) => {
  console.log('Connected, authenticating...');
  socket.emit('authenticate', { token });
});

socket.on('authenticated', (data) => {
  console.log(`Authenticated as ${data.user_id}`);
});

socket.on('message', (data) => {
  console.log(`[${data.message_type}] ${data.subject}`);
  console.log('Details:', data.details);
});

socket.on('error', (data) => {
  console.error('Error:', data.message);
});

Notes

WebSocket provides real-time push delivery vs polling /messages endpoint
Both methods receive the same messages - use whichever fits your client
WebSocket requires Socket.IO client library
Messages are still available via polling if WebSocket disconnects

WebSocket Documentation

Quick Navigation