Everything about playing: finding an opponent, private rooms, placing ships and shooting.
All endpoints in this section need Authorization: Bearer <token> and return:
{ "game": { ... } }
The game as you see it. Your opponent’s ships are hidden until they are sunk (or until the game ends).
{
"id": "66ca0c1fe4b0a1c2d3e4f5b7",
"status": "playing",
"private": false,
"code": null,
"fleet": [4, 3, 3, 2, 2, 2, 1, 1, 1, 1],
"you": {
"nickname": "alice",
"ready": true,
"board": "SSSS.o.... ...100 chars",
"ships": [
{ "x": 0, "y": 0, "length": 4, "vertical": false, "sunk": false }
]
},
"opponent": {
"nickname": "bob",
"ready": true,
"board": "..o.X#.... ...100 chars",
"sunkShips": [
{ "x": 5, "y": 0, "length": 1, "vertical": false }
]
},
"yourTurn": true,
"timeLeftMs": 27450,
"lastShot": { "by": "you", "x": 4, "y": 0, "result": "hit" },
"winner": null,
"reason": null
}
| Field | Description |
|---|---|
status |
waiting: looking for an opponent. placing: ship placement. playing: battle. finished: the game is over. cancelled: someone left before the battle. |
private / code |
Private room and its 5-character code (only for private rooms). |
fleet |
Ship lengths every player must place. |
you.board |
Your board with your ships. |
you.ships |
Your ships, with sunk flags. |
opponent |
null while waiting for an opponent. |
opponent.board |
What you know about the opponent’s board. After the game ends, the remaining ships are revealed as S. |
opponent.sunkShips |
The opponent’s ships you have already sunk. |
yourTurn |
true if you should shoot now. |
timeLeftMs |
Milliseconds until the current timer (placement or turn) runs out, null if there is no timer. |
lastShot |
The latest shot by anyone: by is you or opponent, result is miss, hit or sunk. |
winner |
you, opponent or null. |
reason |
Why the game ended: all_sunk, surrender, timeout (too many missed turns), left (cancelled before the battle). |
A board is a string of 100 characters, row by row. The cell (x, y) is at index y * 10 + x.
| Char | Meaning |
|---|---|
. |
Unknown / empty water |
S |
A ship that hasn’t been hit (only on your own board, or on the opponent’s after the game) |
o |
Miss, or an empty cell revealed around a sunk ship |
X |
Hit: a part of a ship that is still afloat |
# |
A part of a sunk ship |
Printing a board in a terminal takes just a few lines:
for y in range(10):
print(" ".join(board[y * 10:(y + 1) * 10]))
{ "x": 2, "y": 3, "length": 3, "vertical": true }
(x, y) is the top (or left) cell. A vertical ship goes down, a horizontal one goes right. This ship takes the cells (2,3), (2,4) and (2,5).
Joins the queue, or returns the game you are already in.
POST /api/find-game
status: "waiting" while there is nobody to play with. Repeat the request every 3–5 s (or keep a WebSocket subscription): a player who goes quiet for 20 s is removed from the queue.placing.POST /api/rooms
Returns a game with status: "waiting", private: true and a code such as "K7MPQ". Give the code to a friend. The room expires after 15 minutes.
POST /api/rooms/join
{ "code": "K7MPQ" }
The code is case-insensitive. The game switches to placing.
| Status | error |
|---|---|
404 |
Room not found |
409 |
You are already in a game |
GET /api/current-game
Returns { "game": {...} } for your unfinished game, or { "game": null }.
GET /api/lobby/:id
Use it to poll the state if you don’t use WebSocket.
POST /api/lobby/:id/ready
{
"ships": [
{ "x": 0, "y": 0, "length": 4, "vertical": false },
{ "x": 0, "y": 2, "length": 3, "vertical": false },
{ "x": 4, "y": 2, "length": 3, "vertical": false },
{ "x": 0, "y": 4, "length": 2, "vertical": false },
{ "x": 3, "y": 4, "length": 2, "vertical": false },
{ "x": 6, "y": 4, "length": 2, "vertical": false },
{ "x": 0, "y": 6, "length": 1 },
{ "x": 2, "y": 6, "length": 1 },
{ "x": 4, "y": 6, "length": 1 },
{ "x": 9, "y": 9, "length": 1 }
]
}
Send an empty body {} to get a random fleet. That is the easiest way to start a minimal client.
When both players are ready, the game switches to playing and a random player goes first.
| Status | error |
|---|---|
400 |
Fleet must contain exactly 10 ships. / Ships must not touch each other. / Ship is out of the board. / … |
409 |
Ships can be placed only before the battle |
POST /api/lobby/:id/shoot
{ "x": 4, "y": 4 }
Check lastShot.result in the answer. After a hit or a sunk it is still your turn (yourTurn: true).
| Status | error |
|---|---|
400 |
Cell was already shot. / Cell is out of the board. |
409 |
Not your turn / Battle is not in progress |
POST /api/lobby/:id/leave
cancelled.reason: "surrender").| Status | error |
|—|—|
| 401 | No token provided / Invalid token |
| 403 | Not a member of this lobby |
| 404 | Lobby not found |