Mercurial > hg > terminal-chess / file comparison
comparison: PROTOCOL.md
PROTOCOL.md
- changeset 191
- 6da16865a270
- parent 188
- bb967c8e51e9
- child 192
- e57e2874fb2a
equal
deleted
inserted
replaced
| 190:c90386d55cb2 | 191:6da16865a270 |
|---|---|
| 82 the game they want to play. The server can set up a completely new game or | 82 the game they want to play. The server can set up a completely new game or |
| 83 continue an unfinished game. | 83 continue an unfinished game. |
| 84 | 84 |
| 85 ### Starting a New Game | 85 ### Starting a New Game |
| 86 | 86 |
| 87 When the server wants to start a new game, they SHALL send a `NETCODE_GAMEINFO` | 87 When the server wants to start a new game, they SHALL send a `GAMEINFO` |
| 88 message. The payload of this message is as follows: | 88 message. The payload of this message is as follows: |
| 89 * one BYTE denoting the color the server wants to play | 89 * one BYTE denoting the color the server wants to play |
| 90 (16 or 0x10 = white, 32 or 0x20 = black) | 90 (16 or 0x10 = white, 32 or 0x20 = black) |
| 91 * one BYTE indicating if the game is played with time control (1 = yes, 0 = no) | 91 * one BYTE indicating if the game is played with time control (1 = yes, 0 = no) |
| 92 * one WORD for the initial clock time in seconds | 92 * one WORD for the initial clock time in seconds |
| 96 When the game is played without time control, the last three WORDs MAY be | 96 When the game is played without time control, the last three WORDs MAY be |
| 97 left uninitialized, but they SHALL be sent anyway. | 97 left uninitialized, but they SHALL be sent anyway. |
| 98 | 98 |
| 99 ### Continuing a Game | 99 ### Continuing a Game |
| 100 | 100 |
| 101 When the server wants to continue a game, they SHALL send a `NETCODE_PGNDATA` | 101 When the server wants to continue a game, they SHALL send a `PGNDATA` |
| 102 message. The payload of this message is as follows: | 102 message. The payload of this message is as follows: |
| 103 * the same two BYTEs and three WORDs as in `NETCODE_GAMEINFO`, followed by | 103 * the same two BYTEs and three WORDs as in `GAMEINFO`, followed by |
| 104 * one WORD for the number `n` of moves that will follow | 104 * one WORD for the number `n` of moves that will follow |
| 105 * the `n` MOVEs that have been played already | 105 * the `n` MOVEs that have been played already |
| 106 | 106 |
| 107 The server SHOULD NOT send a game that cannot be continued because it already | 107 The server SHOULD NOT send a game that cannot be continued because it already |
| 108 has reached a checkmate, stalemate, or forced draw position. | 108 has reached a checkmate, stalemate, or forced draw position. |
| 123 We call the player supposed to make the next move the _active_ player. | 123 We call the player supposed to make the next move the _active_ player. |
| 124 The other player we call the _waiting_ player. | 124 The other player we call the _waiting_ player. |
| 125 | 125 |
| 126 ### Make a Move | 126 ### Make a Move |
| 127 | 127 |
| 128 ### Resign | 128 If the active player wants to make a move, they SHALL send a `MOVE` message |
| 129 | 129 with one MOVE payload to the waiting player. |
| 130 ### Offer or Claim a Draw | 130 The active player SHALL then wait for an `ACCEPT_MOVE` or `DECLINE_MOVE` |
| 131 message. | |
| 132 | |
| 133 When the waiting player receives a `MOVE` message, they SHOULD validate the | |
| 134 move. When validation fails, they SHALL send a `DECLINE_MOVE` message with one | |
| 135 byte indicating the reason why the move is declined. | |
| 136 Otherwise, they SHALL send an `ACCEPT_MOVE` message. | |
| 137 | |
| 138 When the move is accepted, both players SHALL swap the active / waiting role. | |
| 139 | |
| 140 The reasons for declining a move are listed in the following table: | |
| 141 | |
| 142 | Reason | Value | Description | | |
| 143 |-----------------------|-------|---------------------------------------------| | |
| 144 | INVALID_MOVE_SYNTAX | 1 | E.g., indices out of bounds | | |
| 145 | PIECE_NOT_FOUND | 2 | The piece is not at the specified position. | | |
| 146 | NEED_PROMOTION | 4 | Target piece for promotion is missing. | | |
| 147 | PIECE_PINNED | 5 | Piece cannot move because it is pinned. | | |
| 148 | KING_IN_CHECK | 6 | The move would leave the king in check. | | |
| 149 | KING_MOVES_INTO_CHECK | 7 | The king would be moved into check. | | |
| 150 | MISSING_CHECK | 8 | The check-flag was not set. | | |
| 151 | MISSING_CHECKMATE | 9 | The checkmate-flag is not set. | | |
| 152 | INVALID_CHECK | 10 | The check-flag was incorrectly set. | | |
| 153 | INVALID_CHECKMATE | 11 | The checkmate-flag was incorrectly set. | | |
| 154 | RULES_VIOLATED | 32 | Other rules would be violated by this move. | | |
| 155 | |
| 156 ### End the Game | |
| 157 | |
| 158 The active player, before making a move, SHALL determine if the game has ended. | |
| 159 The game SHALL be ended if a [checkmate](#checkmate) or [stalemate](#stalemate) | |
| 160 position has been reached, or the [clock runs out](#clock-timeout). | |
| 161 | |
| 162 The game SHOULD be ended if a draw can be [claimed](#claim-a-draw) due to a | |
| 163 threefold repetition of the same position, insufficient material, or playing | |
| 164 50 moves without any captures or pawn moves. | |
| 165 | |
| 166 The game MAY be ended at any time by any (including the waiting) player by | |
| 167 [resignation](#resign). | |
| 168 | |
| 169 #### Checkmate | |
| 170 | |
| 171 Whe the active player determines they were checkmated with the last move, | |
| 172 they SHALL send a `CHECKMATE` message to the waiting player. | |
| 173 When receiving such a message, the waiting player SHALL end the game without | |
| 174 sending any confirmation. | |
| 175 | |
| 176 #### Stalemate | |
| 177 | |
| 178 When the active player determines a stalemate position, they SHALL send a | |
| 179 `STALEMATE` message to the waiting player. | |
| 180 The waiting player SHOULD verify this claim. | |
| 181 When verification fails, they SHALL send a `DECLINE` message, and they SHALL | |
| 182 send an `ACCEPT` message, otherwise. | |
| 183 | |
| 184 Both parties SHALL end the game when the stalemate was agreed on. | |
| 185 Otherwise, both parties SHOULD continue playing. | |
| 186 | |
| 187 #### Clock Timeout | |
| 188 | |
| 189 When the clock of the active player times out, they SHALL send a `TIMEOVER` | |
| 190 message to the waiting player. | |
| 191 When receiving such a message, the waiting player SHALL end the game without | |
| 192 sending any confirmation. | |
| 193 | |
| 194 #### Claim a Draw | |
| 195 | |
| 196 The active player SHOULD claim a draw, when | |
| 197 * the position is already repeated a third time (threefold repetition rule) | |
| 198 * there is not enough material for both players on the board (nobody can win) | |
| 199 * no capture or pawn move was made within the last 50 moves | |
| 200 | |
| 201 The draw is claimed by sending a `THREEFOLD`, `NOMATERIAL`, or `50MOVES` | |
| 202 message, respectively. | |
| 203 The waiting player SHOULD verify this claim. | |
| 204 When verification fails, they SHALL send a `DECLINE` message, and they SHALL | |
| 205 send an `ACCEPT` message, otherwise. | |
| 206 | |
| 207 Both parties SHALL end the game when the draw was agreed on. | |
| 208 Otherwise, both parties SHOULD continue playing. | |
| 209 | |
| 210 #### Resign | |
| 211 | |
| 212 Both the active and the waiting player MAY send a `RESIGN` message any time. | |
| 213 When a player receives a `RESIGN` message, they SHALL end the game without | |
| 214 any further confirmation. | |
| 215 | |
| 216 ### Offer a Draw | |
| 217 | |
| 218 _TODO: draw offers by the active player are bugged - see issue #980_ | |
| 219 | |
| 220 _TODO: the description is very confusing and should be cleaned up after fixing issue #980_ | |
| 221 | |
| 222 Both the active and the waiting player MAY send a `REMIS` message any time to | |
| 223 offer a draw. | |
| 224 | |
| 225 When the waiting player receives such an offer, they MAY choose to answer it | |
| 226 with either an `ACCEPT` or a `DECLINE` message. | |
| 227 | |
| 228 When the offer was accepted, both players SHALL end the game. | |
| 229 Otherwise, they SHALL continue playing. | |
| 230 When an offer was declined, the requesting player SHOULD NOT send another offer | |
| 231 for the same position. | |
| 232 | |
| 233 When the active player receives such an offer, they MAY ignore it. | |
| 234 No confirmation is sent. | |
| 235 Instead, if the player chooses to accept the offer, they SHALL send a `REMIS` | |
| 236 message on their own. | |
| 131 | 237 |
| 132 ### Propose Resignation | 238 ### Propose Resignation |
| 133 | 239 |
| 240 The waiting player MAY propose resignation by sending a `TAUNT` message. | |
| 241 | |
| 242 The active player MAY ignore such messages completely. | |
| 243 Implementations MAY choose to display a message to the active player. | |
| 244 If the active player decides to follow the proposal, they SHOULD send a | |
| 245 `RESIGN` message, as described [above](#resign). | |
| 246 | |
| 247 The waiting player SHOULD NOT use this message excessively or inappropriately. | |
| 248 It serves to inform the opponent about a decisive position and is intended to | |
| 249 encourage them to resign a lost game so that both players can make better use | |
| 250 of their time. | |
| 251 | |
| 134 ## Message Code Table | 252 ## Message Code Table |
| 135 | 253 |
| 136 The following table shows the definitions of the network codes. | 254 The following table shows the definitions of the network codes. |
| 137 | 255 |
| 138 | Code Name | Byte | With Payload | | 256 | Code Name | Byte | With Payload | |
| 139 |----------------------|------|--------------| | 257 |--------------|------|--------------| |
| 140 | NETCODE_ACCEPT | 0x02 | no | | 258 | ACCEPT | 0x01 | no | |
| 141 | NETCODE_DECLINE | 0x04 | no | | 259 | DECLINE | 0x02 | no | |
| 142 | NETCODE_DECLINE_MOVE | 0x05 | yes | | 260 | GAMEINFO | 0x10 | yes | |
| 143 | NETCODE_GAMEINFO | 0x10 | yes | | 261 | PGNDATA | 0x11 | yes | |
| 144 | NETCODE_PGNDATA | 0x11 | yes | | 262 | MOVE | 0x20 | yes | |
| 145 | NETCODE_MOVE | 0x20 | yes | | 263 | ACCEPT_MOVE | 0x21 | no | |
| 146 | NETCODE_CHECKMATE | 0x23 | no | | 264 | DECLINE_MOVE | 0x22 | yes | |
| 147 | NETCODE_STALEMATE | 0x28 | no | | 265 | CHECKMATE | 0x30 | no | |
| 148 | NETCODE_NOMATERIAL | 0x29 | no | | 266 | STALEMATE | 0x31 | no | |
| 149 | NETCODE_THREEFOLD | 0x30 | no | | 267 | NOMATERIAL | 0x32 | no | |
| 150 | NETCODE_RESIGN | 0x41 | no | | 268 | THREEFOLD | 0x33 | no | |
| 151 | NETCODE_REMIS | 0x42 | no | | 269 | 50MOVES | 0x34 | no | |
| 152 | NETCODE_TAUNT | 0x43 | no | | 270 | RESIGN | 0x41 | no | |
| 153 | NETCODE_TIMEOVER | 0x44 | no | | 271 | REMIS | 0x42 | no | |
| 272 | TAUNT | 0x43 | no | | |
| 273 | TIMEOVER | 0x44 | no | | |
| 154 | 274 |
| 155 The following codes are reserved for implementation. | 275 The following codes are reserved for implementation. |
| 156 They are not used during transmissions and can be used as return values | 276 They are not used during transmissions and can be used as return values |
| 157 for functions to indicate errors. | 277 for functions to indicate errors. |
| 158 | 278 |
| 159 | Code Name | Byte | | 279 | Code Name | Byte | |
| 160 |----------------------|------| | 280 |-----------|------| |
| 161 | NETCODE_AGAIN | 0x70 | | 281 | AGAIN | 0x70 | |
| 162 | NETCODE_CONNLOST | 0x80 | | 282 | CONNLOST | 0x80 | |
| 163 | NETCODE_ERROR | 0xFF | | 283 | ERROR | 0xFF | |
| 164 | 284 |
| 165 | 285 |
