The protocol uses a simple structure of commands and parameters delimited by a + sign and terminated by a new line. Commands are sent over a simple socket connection. Every command has to be sent on a new line. The order of the parameters is strictly defined in the command and it is assumed this order is followed. As such no flags or identifiers need to be provided.
The protocol is started when a player opens a socket connection to the server. The first player to connect will have control over the game configuration (e.g. board size, preferred color, number of players).
The first step is for the player to identify himself to the server and providing a player name. If the game acknowledges the player it will answer and if it is the first player it sends a request for the configuration. The client responds accordingly.
If both players are identified and the configuration is set the server sends out initial game status (e.g. who you are playing, whose turn it is and the current board layout).
After this the currently active player can send a move to the server which can acknowledge the move and broadcast a new status. This is continued until the game is finished after which the server broadcasts the finished game status and the winner.
When the game is finished the server asks the players if they want to play a rematch, if both respond with yes the game is restarted with the same config. If one of the players responds negative the other player is notified.
This new game is commenced with a new ACKNOWLEDGE_CONFIG command.
The server is responsible for maintaining a valid gamestate, so it handles things like removing captured stones, calculating the scores and making sure the game flow is maintained.
In the following description commands and parameters will be given in full caps where parameters are preceeded by a $ sign. Commands have a set String representation which will be provided in a later section.
HANDSHAKE+$PLAYER_NAMEUsed to identify yourself to the server with your preferred username.
$PLAYERNAME:String. Preferred username, is not allowed to contain the character '+'.
Example:
HANDSHAKE+Thiery BaudetSET_CONFIG+$GAME_ID+$PREFERRED_COLOR+$BOARD_SIZESet the game configuration and the color you'd like to play with.
-
$GAME_ID: Int. Game id provided by the server in the initial handshake. -
$PREFERRED_COLOR: Int. integer representation of the color you'd like to play with. (0=random, 1=black, 2=white, 3-9=implemented later) -
$BOARD_SIZE: Int. Preferred board dimensions. Givenfor ann * nboard.
Example:
SET_CONFIG+0+1+10SET_REMATCH+$REMATCHSent as a response to REQUEST_REMATCH.
$REMATCH: int. 1 if you would like a rematch, 0 if you would not.
Example:
SET_REMATCH+1MOVE+$GAME_ID+$PLAYER_NAME+$TILE_INDEXPlace a stone on a tile.
$GAME_ID: int. Game id provided by the server on the initial handshake.$PLAYER_NAME: String. Username as set in the initial handshake.$TILE_INDEX: int. Tile you want to place your stone on. The index is one dimensional so for ann * nboard placing a tile on rowicolumnjthe index isi * n + j.-1for passing.
example:
MOVE+1+Thiery Baudet+9EXIT+$GAME_ID+$PLAYER_NAMEUsed to exit the game at any moment.
$GAME_ID: int; Game id provided by the server on the initial handshake$PLAYER_NAME: String; Username as set in the initial handshake.
example:
EXIT+1+Thiery BaudetACKNOWLEDGE_HANDSHAKE+$GAME_ID+$IS_LEADERServer acknowledges the player and provides a game_id for the client.
$GAME_ID: int. Game id generated by the server;$IS_LEADER: Boolean. Boolean represented as an integer (0=false, 1=true) indicating wether the player is leader and has to provide the game settings.
example:
ACKNOWLEDGE_HANDSHAKE+1+1REQUEST_CONFIG+$REQUEST_CONFIG_MESSAGEAsk a client to provide configuration.
$REQUEST_CONFIG_MESSAGE$: String. String containing the message to be displayed requesting the config message.
example:
REQUEST_CONFIG+Please provide a preferred configuration using the SET_CONFIG+$PREFERRED_COLOR+$BOARD_SIZEREQUEST_REMATCHSent to both players after the game is finished by 2 passes
example:
REQUEST_REMATCHACKNOWLEDGE_CONFIG+$PLAYER_NAME+$COLOR+$SIZE+$GAME_SATE+$OPPONENTSent to both players after 2 players have connected and identified themselves and the leader has provided the configuration.
$PLAYER_NAME$: String. Username granted to you by the server, this is the username you are obliged to use.$COLOR:int. Integer representing the color to you by the server (1=black, 2=white, 3-9=implemented later)$SIZE: int. Board size.nfor ann * nboard.$GAME_STATE: State. String representation of the current game state. The format of the State object is explained in the next section.$OPPONENT: String. Username of the opponent.
example:
ACKNOWLEDGE_CONFIG+Thiery Baudet+1+4+PLAYING;2;0000011120001200ACKNOWLEDGE_MOVE+$GAME_ID+$MOVE+$GAME_STATE$GAME_ID: Int Game id provided by the server in the initial handshake.$MOVE: Move Move object following the format described in the next section. Represents the move that has been acknowledged.$GAME_STATE: State. Representation of the current game state. The format of the State object is explained in the types section.
example:
ACKNOWLEDGE_MOVE+1+30;1+PLAYING;2;0000011120001200ACKNOWLEDGE_REMATCH+$REMATCHSent when either both players agree to a rematch or one person rejects a rematch.
$REMATCH: int. 1 if you would like a rematch, 0 if you would not.
example:
ACKNOWLEDGE_REMATCH+1INVALID_MOVE+$ERROR_MESSAGESent when an invalid move is sent to the server.
$ERROR_MESSAGE: String. Error message.
example:
INVALID_MOVE+Invalid move: Tile not empty.UNKNOWN_COMMAND+$MESSAGEReturned when a command is not recognized or invalid.
$MESSAGE: String. Message.
GAME_FINISHED+$GAME_ID+$WINNER+$SCORE+$MESSAGESent when a game is finished in any way. If someone disconnects or exits, the winner is the other person.
$GAME_ID: Int. Id provided in the initial handshake$WINNER: String. Username of the winning player.$SCORE: String.$POINTS_BLACK;$POINTS_WHITEMESSAGE: String. Message to the players. For instance the reason the game ended (disconnect, 2 passes, no more valid moves, etc..).
$STATUS;$CURRENT_PLAYER;$BOARDCurrent game state represented as a ; delimited string.
$STATUS: String. Status of the game. Can bePLAYING,FINISHED.$CURRENT_PLAYER: Int. Color of the player who should make the next move.$BOARD: String; String representing the current board layout as a one dimensional array with the color of the tile at it's respective index. (0=empty, 1=black, 2=white, 3-9=implemented later).
$INDEX;$COLORMove represented as a ; delimited string.
$INDEX: Int. Index of the affected tile.$COLOR: Int. Integer representing the color of the stone placed on the tile (1=black, 2=white, 3-9=implemented later).