WebSocket Protocol Reference

1. Connect

Open a WebSocket connection to:

ws://<server-host>:<port>/ws

2. Identify (send immediately on connect)

Send this message as soon as the connection opens:

{
  "type": "identify",
  "role": "game",
  "instance": "A"  // or "B"
}

The instance ID must match the tablet controller it's paired with. If you connect with the same role + instance as an existing connection, the old one will be evicted.

3. Receive: start

When the tablet operator starts a game, you'll receive:

{
  "type": "start",
  "playerName": "John",
  "avatar": "male",    // "male" | "female" | "other"
  "height": "medium"   // "small" | "medium" | "large"
}

Your game should begin. avatar and height are selected by the operator — use them for character model selection, camera height, or however you see fit. You don't need to track or return any of these fields.

4. Receive: abort

If the operator resets mid-game, you'll receive:

{
  "type": "abort"
}

Your game should immediately return to its idle/start screen. Discard any in-progress state.

5. Send: end

When the game finishes, send the score:

{
  "type": "end",
  "score": 4200  // positive integer
}

The server will pair this with the player name and relay it to the tablet and leaderboard. You only need to send the score.

6. Reconnection

If your connection drops, reconnect and re-send the identify message. The server will evict the stale socket and slot you back in. Implement auto-reconnect with backoff (e.g. start at 500ms, cap at 5s).

7. Errors

If you send something the server doesn't understand, you'll receive:

{
  "type": "error",
  "message": "description of the problem"
}