bgammon/PROTOCOL.md

# Specification of bgammon.org protocol

Connect via `bgammon.org:1337` (TCP) or `wss://ws.bgammon.org` (WebSocket).

Replace spaces with underscores when sending a password to the server.

When connected via TCP, commands and events are separated by newlines.

Players always perceive games from the perspective of player number 1 (black).

## User commands

### Format

`command <required argument> [optional argument]`

### Client commands

Clients must send a register command, reset command or login command before sending any other commands.

- `register <email> <username> <password>`
  - Register an account. A valid email address must be provided.
  - Usernames must contain at least one non-numeric character.

- `registerjson <client name> <email> <username> <password>`
  - Register an account and enable JSON formatted responses.
  - All client applications should use the `registerjson` command to register, as JSON 
formatted responses are more easily parsed by computers.
  - The name of the client must be specified.
  - Aliases: `rj`

- `resetpassword <email>`
  - Request a password reset link via email.
  - This command always terminates the client with the message "resetpasswordok", even if an account is not found.

- `login [username] [password]`
  - Log in. A random username is assigned when none is provided.
  - Usernames must contain at least one non-numeric character.

- `loginjson <client name> [username] [password]`
  - Log in and enable JSON formatted responses.
  - All client applications should use the `loginjson` command to log in, as JSON 
formatted responses are more easily parsed by computers.
  - The name of the client must be specified.
  - Aliases: `lj`

- `password <old> <new>`
  - Change account password.

- `set <name> <value>`
  - Change account setting.
  - Available settings: `highlight`, `pips` and `moves`.

- `replay <id>`
  - Retrieve replay of the specified game.

- `history <username> [page]`
  - Retrieve match history of the specified player.

- `json <on/off>`
  - Turn JSON formatted messages on or off. JSON messages are not sent by default.

- `help [command]`
  - Request help for all commands, or optionally a specific command.
  - Aliases: `h`

- `list`
  - List all matches.
  - Aliases: `ls`

- `create <public>/<private [password]> <points> <acey> [name]`
  - Create a match. An `acey` value of 0 represents a standard game, while a value of 1 represents an acey-deucey game.
  - Aliases: `c`

- `join <id>/<username> [password]`
  - Join match by match ID or by player.
  - Aliases: `j`

- `double`
  - Offer double to opponent.
  - Aliases: `d`

- `resign`
  - Resign game. Resigning when a double is offered will decline the offer.

- `roll`
  - Roll dice.
  - Aliases: `r`

- `move <from-to> [from-to]...`
  - Move checkers.
  - Aliases: `m`, `mv`

- `reset`
  - Reset pending checker movement.
  - Aliases: `r`

- `ok [1-6]`
  - Accept double offer or confirm checker movement. The parameter for this command only applies in acey-deucey games.
  - In normal games, confirming checker movement passes the turn to the next player.
  - In acey-deucey games, when confirming moves after rolling an acey-deucey, the double roll the player chooses must be specified.
  - Aliases: `k`

- `rematch`
  - Request (or accept) a rematch after a match has been finished.
  - Aliases: `rm`

- `say <message>`
  - Send a chat message.
  - This command can only be used after creating or joining a match.
  - Aliases: `s`

- `board`
  - Print current match state in human-readable form.
  - This command is not normally used, as the match state is provided in JSON format.
  - Aliases: `b`

- `pong <message>`
  - Sent in response to server `ping` event to prevent the connection from timing out.
  - Whether the client sends a `pong` command, or any other command, clients
must write some data to the server at least once every 40 seconds.

- `disconnect`
  - Disconnect from the server.

- `broadcast`
  - Send a message to all players.
  - This command is only available to server administrators.

- `shutdown <minutes> <reason>`
  - Prevent the creation of new matches and periodically warn players about the server shutting down.
  - This command is only available to server administrators.

## Server events

All events are sent in either JSON or human-readable format. The structure of
messages sent in JSON format is available via [godoc](https://docs.rocket9labs.com/code.rocket9labs.com/tslocum/bgammon/#Event).

This document lists events in human-readable format.

### Data types

- `integer` a whole number
- `boolean` - `0` (representing false) or `1` (representing true)
- `text` - alphanumeric without spaces
- `line` - alphanumeric with spaces

### Events

- `hello <message:line>`
  - Initial welcome message sent only to clients connected via TCP. It provides instructions on how to log in.
  - This message does not normally need to be displayed when using a graphical client.

- `welcome <name:text> there are <clients:integer> clients playing <games:integer> matches.`
  - Initial message sent by the server.

- `notice <message:line>`
  - Server message. This should always be displayed to the user.

- `liststart Matches list:`
  - Start of matches list.

- `game <id:integer> <password:boolean> <points:integer> <players:integer> <name:line>`
  - Match description.

- `listend End of matches list.`
  - End of matches list.

- `joined <id:integer> <playerNumber:integer> <playerName:text>`
  - Sent after successfully creating or joining a match, and when another player
joins a match you are in.
  - The server will always send a `board` event immediately after `joined` to
provide clients with the initial match state.

- `failedjoin <message:line>`
  - Sent after failing to join a match.

- `left <username:text>`
  - Sent after leaving a match.

- `json <message:line>`
  - Server confirmation of client requested JSON formatting.
  - This message does not normally need to be displayed when using a graphical client.

- `failedok <reason:line>`
  - Sent after sending `ok` when there are one or more legal moves still available to the player.
  - Players must make moves using all available dice rolls before ending their turn.

- `win <player:text> wins!`
  - Sent after a player bears their final checker off the board.

- `say <player:text> <message:line>`
  - Chat message from another player.

- `ping <message:text>`
  - Sent to clients to prevent their connection from timing out.
  - Whether the client replies with a `pong` command, or any other command,
clients must write some data to the server at least once every 40 seconds.