API

WebSocket

WebSocket is optional. You can play using REST polling only. A WebSocket subscription simply delivers every change instantly, for example your opponent’s shot, a match being found or the game ending.

Connect

ws://<server>/ws

(use wss:// if the server runs behind HTTPS)

Subscribe to a game

After connecting, send:

{ "type": "subscribe", "token": "<token>", "lobbyId": "<game id>" }

The server answers with the current state right away and then sends a new message after every change:

{ "type": "state", "game": { ... } }

game is the same game object as in the REST API, seen from your side.

One connection follows one game at a time. Sending subscribe again switches to another game.

Errors

{ "type": "error", "error": "Invalid token" }

Possible errors: Invalid token, Lobby not found, Not a member of this lobby.

Keep-alive

The server pings every connection every 30 seconds and closes connections that don’t answer. Standard WebSocket libraries answer pings automatically. If your library can’t do that, you can send this message instead:

{ "type": "ping" }

and you will get { "type": "pong" } back.

While you wait in the public queue, a live WebSocket subscription counts as ā€œstill waitingā€, so you don’t need to keep calling find-game.

Actions

All actions (placing ships, shooting, leaving) are sent over REST. The WebSocket only delivers updates.