bgammon/PROTOCOL.md
2023-08-22 17:05:35 -07:00

3 KiB

Secification of bgammon protocol

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.

json [on/off]

Turn JSON formatted messages on or off. JSON messages are not sent by default.

Graphical clients should send the json on command immediately after sending login.

help [command]

Request help for all commands, or optionally a specific command.

list

List all games.

create [public/private] [password]

List all games.

join [id] [password]

Join game.

roll

Roll dice.

move <from-to> [from-to]...

Move checkers.

reset

Reset pending checker movement.

ok

Confirm checker movement and pass turn to next player.

say <message>

Send a chat message.

This command can only be used after creating or joining a game.

board

Print current game state in human-readable form.

This command is not normally used, as the game state is provided in JSON format.

disconnect

Disconnect from the server.

Server responses

Data types:

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

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.

game <id:integer> <password:boolean> <players:integer> <name:line>

Game description.

listend End of games list.

End of games list.

joined <id:integer> <player:text> <name:line>

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
}

say <player:text> <message:line>

Chat message from another player.