2023-08-27 03:33:16 +00:00
|
|
|
# Specification of bgammon.org protocol
|
|
|
|
|
|
|
|
Connect to `bgammon.org:1337` via TCP.
|
|
|
|
|
|
|
|
All commands and events are separated by newlines.
|
2023-08-21 04:21:49 +00:00
|
|
|
|
2023-09-30 17:43:49 +00:00
|
|
|
When sending a password to the server, replace spaces with underscores.
|
|
|
|
|
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-08-27 03:59:52 +00:00
|
|
|
- `login [username] [password]`
|
|
|
|
- Log in to bgammon. 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-09-12 02:59:31 +00:00
|
|
|
- This (or `loginjson`) must be the first command sent when a client connects to bgammon.
|
2023-09-10 22:27:33 +00:00
|
|
|
- Aliases: `l`
|
2023-08-21 04:21:49 +00:00
|
|
|
|
2023-08-27 03:59:52 +00:00
|
|
|
- `loginjson [username] [password]`
|
|
|
|
- Log in to bgammon and enable JSON formatted responses.
|
|
|
|
- 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-09-10 22:27:33 +00:00
|
|
|
- Aliases: `lj`
|
2023-08-27 03:50:12 +00:00
|
|
|
|
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
|
|
|
|
2023-10-19 02:59:48 +00:00
|
|
|
- `create <public>/<private [password]> <points> [name]`
|
2023-09-12 02:59:31 +00:00
|
|
|
- Create a match.
|
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
|
|
|
|
2023-10-20 20:51:32 +00:00
|
|
|
- `double`
|
|
|
|
- Offer double to opponent.
|
|
|
|
- Aliases: `d`
|
|
|
|
|
|
|
|
- `resign`
|
|
|
|
- Decline double offer and resign game.
|
|
|
|
|
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-08-27 03:59:52 +00:00
|
|
|
- `ok`
|
2023-10-20 20:51:32 +00:00
|
|
|
- Accept double offer or confirm checker movement and pass turn to next player.
|
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
|
|
|
|
must write some data to the server at least once every ten minutes.
|
|
|
|
|
2023-08-27 03:59:52 +00:00
|
|
|
- `disconnect`
|
|
|
|
- Disconnect from the server.
|
2023-08-23 00:05:35 +00:00
|
|
|
|
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>`
|
|
|
|
- Initial welcome message sent by the server. It provides instructions on how to log in.
|
|
|
|
- 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,
|
|
|
|
clients must write some data to the server at least once every ten minutes.
|