bgammon/PROTOCOL.md

192 lines
3.8 KiB
Markdown
Raw Normal View History

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
## User commands
Format: `command <required argument> [optional argument]`
### `login [username] [password]`
Log in to bgammon. A random username is assigned when none is provided.
This must be the first command sent when a client connects to bgammon.
2023-08-27 03:50:12 +00:00
*Aliases:* `l`
2023-08-27 02:47:12 +00:00
### `loginjson [username] [password]`
2023-08-23 00:05:35 +00:00
2023-08-27 02:47:12 +00:00
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.
*Aliases:* `lj`
2023-08-23 00:05:35 +00:00
2023-08-27 02:47:12 +00:00
### `json <on/off>`
Turn JSON formatted messages on or off. JSON messages are not sent by default.
2023-08-23 00:05:35 +00:00
2023-08-21 04:21:49 +00:00
### `help [command]`
Request help for all commands, or optionally a specific command.
2023-08-27 03:50:12 +00:00
*Aliases:* `h`
2023-08-21 04:21:49 +00:00
### `list`
List all games.
2023-08-27 03:50:12 +00:00
*Aliases:* `ls`
2023-08-27 02:47:12 +00:00
### `create <public/private> [password]`
2023-08-21 04:21:49 +00:00
List all games.
2023-08-27 03:50:12 +00:00
*Aliases:* `c`
2023-08-27 02:47:12 +00:00
### `join <id> [password]`
2023-08-21 04:21:49 +00:00
Join game.
2023-08-27 03:50:12 +00:00
*Aliases:* `j`
2023-08-21 04:21:49 +00:00
### `roll`
Roll dice.
2023-08-27 03:50:12 +00:00
*Aliases:* `r`
2023-08-21 04:21:49 +00:00
### `move <from-to> [from-to]...`
Move checkers.
2023-08-27 03:50:12 +00:00
*Aliases:* `m`, `mv`
2023-08-21 04:21:49 +00:00
### `reset`
Reset pending checker movement.
2023-08-27 03:50:12 +00:00
*Aliases:* `r`
2023-08-21 04:21:49 +00:00
### `ok`
Confirm checker movement and pass turn to next player.
2023-08-27 03:50:12 +00:00
*Aliases:* `k`
2023-08-23 00:05:35 +00:00
### `say <message>`
Send a chat message.
This command can only be used after creating or joining a game.
2023-08-27 03:50:12 +00:00
*Aliases:* `s`
2023-08-23 00:05:35 +00:00
### `board`
Print current game state in human-readable form.
This command is not normally used, as the game state is provided in JSON format.
2023-08-27 03:50:12 +00:00
*Aliases:* `b`
2023-08-21 04:21:49 +00:00
### `disconnect`
Disconnect from the server.
2023-08-27 03:33:16 +00:00
## Events (server responses)
2023-08-21 04:21:49 +00:00
Data types:
- `integer` a whole number
- `boolean` - `0` (representing false) or `1` (representing true)
- `text` - alphanumeric without spaces
- `line` - alphanumeric with spaces
2023-08-27 03:33:16 +00:00
All events are sent in either JSON or human-readable format. The human-readable
2023-08-27 03:43:23 +00:00
format is documented here. The structure of each JSON message is available via
[godoc](https://docs.rocket9labs.com/code.rocket9labs.com/tslocum/bgammon/#Event).
2023-08-27 03:33:16 +00:00
2023-08-21 04:21:49 +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.
### `welcome <name:text> there are <clients:integer> clients playing <games:integer> games.`
Initial message sent by the server.
### `notice <message:line>`
Server message. This should always be displayed to the user.
### `liststart Games list:`
Start of games list.
2023-08-23 00:05:35 +00:00
### `game <id:integer> <password:boolean> <players:integer> <name:line>`
2023-08-21 04:21:49 +00:00
Game description.
### `listend End of games list.`
2023-08-23 00:05:35 +00:00
End of games list.
2023-08-27 03:33:16 +00:00
### `joined <id:integer> <player:text>`
2023-08-23 00:05:35 +00:00
Sent after successfully creating or joining a game, and when another player
joins a game you are in.
The server will always send a `board` response immediately after `joined` to
provide clients with the initial game state.
### `failedjoin <message:line>`
Sent after failing to join a game.
### `parted <gameID:integer> <gameID:integer>`
Sent after leaving a game.
### `json <message:line>`
Server confirmation of client requested JSON formatting.
This message does not normally need to be displayed when using a graphical client.
### `board <json:line>`
Game state in JSON format.
This message is only sent to clients that have explicitly enabled JSON formatted messages.
```
type Player struct {
Number int // 1 black, 2 white
Name string
}
type Game struct {
Board []int
Player1 Player
Player2 Player
Turn int
Roll1 int
Roll2 int
}
```
2023-08-25 08:39:43 +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
### `say <player:text> <message:line>`
Chat message from another player.