2023-08-27 03:33:16 +00:00
# Specification of bgammon.org protocol
2023-11-15 01:51:36 +00:00
Connect via `bgammon.org:1337` (TCP) or `wss://ws.bgammon.org` (WebSocket).
2023-08-27 03:33:16 +00:00
2023-11-15 01:51:36 +00:00
Replace spaces with underscores when sending a password to the server.
2023-08-21 04:21:49 +00:00
2023-11-15 01:51:36 +00:00
When connected via TCP, commands and events are separated by newlines.
2023-09-30 17:43:49 +00:00
2023-11-15 22:41:56 +00:00
Players always perceive games from the perspective of player number 1 (black).
2023-08-21 04:21:49 +00:00
## User commands
2023-08-27 03:59:52 +00:00
### Format
2023-08-21 04:21:49 +00:00
2023-08-27 03:59:52 +00:00
`command <required argument> [optional argument]`
2023-08-21 04:21:49 +00:00
2023-09-09 07:01:01 +00:00
### Client commands
2023-08-21 04:21:49 +00:00
2023-12-14 03:04:02 +00:00
Clients must send a register command, reset command or login command before sending any other commands.
2023-12-13 06:46:37 +00:00
- `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`
2023-12-14 03:04:02 +00:00
- `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.
2023-08-27 03:59:52 +00:00
- `login [username] [password]`
2023-12-13 06:46:37 +00:00
- Log in. A random username is assigned when none is provided.
2023-09-10 03:08:43 +00:00
- Usernames must contain at least one non-numeric character.
2023-08-21 04:21:49 +00:00
2023-10-23 07:15:13 +00:00
- `loginjson <client name> [username] [password]`
2023-12-13 06:46:37 +00:00
- Log in and enable JSON formatted responses.
2023-08-27 03:59:52 +00:00
- All client applications should use the `loginjson` command to log in, as JSON
2023-08-27 03:50:12 +00:00
formatted responses are more easily parsed by computers.
2023-10-23 07:15:13 +00:00
- The name of the client must be specified.
2023-09-10 22:27:33 +00:00
- Aliases: `lj`
2023-08-27 03:50:12 +00:00
2023-12-15 07:20:50 +00:00
- `password <old> <new>`
- Change account password.
2023-12-15 08:23:45 +00:00
- `set <name> <value>`
- Change account setting.
- Available settings: `highlight` , `pips` and `moves` .
2023-12-16 07:27:24 +00:00
- `replay <id>`
- Retrieve replay of the specified game.
2024-01-14 01:45:02 +00:00
- `history <username> [page]`
2023-12-20 00:26:05 +00:00
- Retrieve match history of the specified player.
2023-08-27 03:59:52 +00:00
- `json <on/off>`
- Turn JSON formatted messages on or off. JSON messages are not sent by default.
2023-08-21 04:21:49 +00:00
2023-08-27 03:59:52 +00:00
- `help [command]`
- Request help for all commands, or optionally a specific command.
2023-09-10 22:27:33 +00:00
- Aliases: `h`
2023-08-27 03:50:12 +00:00
2023-08-27 03:59:52 +00:00
- `list`
2023-09-12 02:59:31 +00:00
- List all matches.
2023-09-10 22:27:33 +00:00
- Aliases: `ls`
2023-08-21 04:21:49 +00:00
2024-07-20 00:32:30 +00:00
- `create <public>/<private [password]> <points> <variant> [name]`
- Create a match. A `variant` value of 0 represents a standard game, a value of 1 represents an acey-deucey game and a value of 2 represents a tabula game.
2023-09-10 22:27:33 +00:00
- Aliases: `c`
2023-08-21 04:21:49 +00:00
2023-09-10 03:08:43 +00:00
- `join <id>/<username> [password]`
2023-09-12 02:59:31 +00:00
- Join match by match ID or by player.
2023-09-10 22:27:33 +00:00
- Aliases: `j`
2023-08-27 03:50:12 +00:00
2024-07-20 00:32:30 +00:00
- `leave`
- Leave match.
2023-10-20 20:51:32 +00:00
- `double`
- Offer double to opponent.
- Aliases: `d`
- `resign`
2024-06-28 01:55:40 +00:00
- Resign game. Resigning when a double is offered will decline the offer.
2023-10-20 20:51:32 +00:00
2023-08-27 03:59:52 +00:00
- `roll`
- Roll dice.
2023-09-10 22:27:33 +00:00
- Aliases: `r`
2023-08-23 00:05:35 +00:00
2023-08-27 03:59:52 +00:00
- `move <from-to> [from-to]...`
- Move checkers.
2023-09-10 22:27:33 +00:00
- Aliases: `m` , `mv`
2023-08-23 00:05:35 +00:00
2023-08-27 03:59:52 +00:00
- `reset`
- Reset pending checker movement.
2023-09-10 22:27:33 +00:00
- Aliases: `r`
2023-08-23 00:05:35 +00:00
2023-11-25 03:15:50 +00:00
- `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.
2023-09-10 22:27:33 +00:00
- Aliases: `k`
- `rematch`
- Request (or accept) a rematch after a match has been finished.
- Aliases: `rm`
2023-08-27 03:50:12 +00:00
2023-08-27 03:59:52 +00:00
- `say <message>`
- Send a chat message.
2023-09-12 02:59:31 +00:00
- This command can only be used after creating or joining a match.
2023-09-10 22:27:33 +00:00
- Aliases: `s`
2023-08-23 00:05:35 +00:00
2023-08-27 03:59:52 +00:00
- `board`
2023-09-12 02:59:31 +00:00
- Print current match state in human-readable form.
- This command is not normally used, as the match state is provided in JSON format.
2023-09-10 22:27:33 +00:00
- Aliases: `b`
2023-08-23 00:05:35 +00:00
2023-08-27 21:10:18 +00:00
- `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
2023-10-25 04:40:36 +00:00
must write some data to the server at least once every 40 seconds.
2023-08-27 21:10:18 +00:00
2023-08-27 03:59:52 +00:00
- `disconnect`
- Disconnect from the server.
2023-08-23 00:05:35 +00:00
2024-07-20 00:32:30 +00:00
- `motd [message]`
- View (or set) message of the day.
- Specifying a new message of the day is only available to server administrators.
- `broadcast <message>`
2024-07-08 18:46:41 +00:00
- 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.
2023-09-09 07:01:01 +00:00
## Server events
2023-08-21 04:21:49 +00:00
2023-08-27 03:59:52 +00:00
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 ).
2023-08-21 04:21:49 +00:00
2023-08-27 03:59:52 +00:00
This document lists events in human-readable format.
2023-08-21 04:21:49 +00:00
2023-08-27 03:59:52 +00:00
### Data types
2023-08-21 04:21:49 +00:00
- `integer` a whole number
- `boolean` - `0` (representing false) or `1` (representing true)
- `text` - alphanumeric without spaces
- `line` - alphanumeric with spaces
2023-08-27 03:59:52 +00:00
### Events
2023-08-21 04:21:49 +00:00
2023-08-27 03:59:52 +00:00
- `hello <message:line>`
2023-11-15 01:51:36 +00:00
- Initial welcome message sent only to clients connected via TCP. It provides instructions on how to log in.
2023-08-27 03:59:52 +00:00
- This message does not normally need to be displayed when using a graphical client.
2023-08-21 04:21:49 +00:00
2023-09-12 02:59:31 +00:00
- `welcome <name:text> there are <clients:integer> clients playing <games:integer> matches.`
2023-08-27 03:59:52 +00:00
- Initial message sent by the server.
2023-08-21 04:21:49 +00:00
2023-08-27 03:59:52 +00:00
- `notice <message:line>`
- Server message. This should always be displayed to the user.
2023-08-21 04:21:49 +00:00
2023-09-12 02:59:31 +00:00
- `liststart Matches list:`
- Start of matches list.
2023-08-23 00:05:35 +00:00
2023-10-19 02:59:48 +00:00
- `game <id:integer> <password:boolean> <points:integer> <players:integer> <name:line>`
2023-09-12 02:59:31 +00:00
- Match description.
2023-08-23 00:05:35 +00:00
2023-09-12 02:59:31 +00:00
- `listend End of matches list.`
- End of matches list.
2023-08-23 00:05:35 +00:00
2023-08-27 21:10:18 +00:00
- `joined <id:integer> <playerNumber:integer> <playerName:text>`
2023-09-12 02:59:31 +00:00
- Sent after successfully creating or joining a match, and when another player
joins a match you are in.
2023-09-09 07:01:01 +00:00
- The server will always send a `board` event immediately after `joined` to
2023-09-12 02:59:31 +00:00
provide clients with the initial match state.
2023-08-23 00:05:35 +00:00
2023-08-27 03:59:52 +00:00
- `failedjoin <message:line>`
2023-09-12 02:59:31 +00:00
- Sent after failing to join a match.
2023-08-25 08:39:43 +00:00
2023-09-12 02:59:31 +00:00
- `left <username:text>`
- Sent after leaving a match.
2023-08-25 08:39:43 +00:00
2023-08-27 03:59:52 +00:00
- `json <message:line>`
- Server confirmation of client requested JSON formatting.
- This message does not normally need to be displayed when using a graphical client.
2023-08-25 08:39:43 +00:00
2023-08-27 03:59:52 +00:00
- `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.
2023-08-23 00:05:35 +00:00
2023-09-08 06:35:27 +00:00
- `win <player:text> wins!`
- Sent after a player bears their final checker off the board.
2023-08-27 03:59:52 +00:00
- `say <player:text> <message:line>`
- Chat message from another player.
2023-08-27 21:10:18 +00:00
- `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,
2023-11-15 01:51:36 +00:00
clients must write some data to the server at least once every 40 seconds.
