Mercurial > hg > terminal-chess / file comparison

comparison: PROTOCOL.md

PROTOCOL.md

changeset 182
04c65336777f
equal deleted inserted replaced
181:8bda076d0a16 182:04c65336777f
1 # terminal-chess Network Protocol
2
3 The network protocol for terminal-chess is designed in an interoperable manner,
4 allowing for playing chess with other clients that implement the same protocol.
5
6 This document describes the protocol in detail, including the message formats
7 and the expected behavior of clients and the server.
8
9 The current protocol version is 24.
10
11 ## Message Format
12
13 The terminal-chess network protocol has two different message types:
14
15 * a code consisting of a single byte
16 * a message composed of a single byte indicating the type plus a payload
17
18 An example implementation covering both types is the following struct:
19
20 ```C
21 struct message {
22 unsigned char code;
23 unsigned char message[]; // flexible array member
24 }
25 ```
26
27 A table with all message codes can be found [below](#message-code-table).
28
29 The datatypes used in the message payloads are as follows:
30
31 * BYTE — a single byte
32 * WORD — two bytes integer (big-endian)
33 * DWORD — four bytes integer (big-endian)
34 * MOVE — a data structure describing a move, consisting of
35 * a DWORD for the elapsed move time in seconds
36 * a DWORD for additional elapsed move time in microseconds
37 * a BYTE describing the moved piece (see below)
38 * a BYTE index for the file the piece was moved from
39 * a BYTE index for the row the piece was moved from
40 * a BYTE index for the file the piece was moved to
41 * a BYTE index for the row the piece was moved to
42 * a BYTE describing the selected piece for promotion (otherwise zero)
43
44 The following table shows the possible values for the BYTEs describing a piece.
45
46 | Piece | Value (Hex) |
47 |--------------|-------------|
48 | White Pawn | 0x11 |
49 | White Rook | 0x12 |
50 | White Knight | 0x13 |
51 | White Bishop | 0x14 |
52 | White Queen | 0x15 |
53 | White King | 0x16 |
54 | Black Pawn | 0x21 |
55 | Black Rook | 0x22 |
56 | Black Knight | 0x23 |
57 | Black Bishop | 0x24 |
58 | Black Queen | 0x25 |
59 | Black King | 0x26 |
60
61 ## Handshake
62
63 Immediately after a connection between a server and a client is established,
64 the server SHALL send one single byte denoting the protocol version to the
65 client.
66 The client SHALL then immediately answer with their protocol version.
67 After both parties have sent their version to the other party, they SHALL both
68 compare their own version with the received version.
69 When the versions do not match, both parties SHALL terminate the connection.
70 The users SHOULD be informed about the protocol mismatch.
71
72 ## Game Setup
73
74 After a successful handshake, the server SHALL send the client information about
75 the game they want to play. The server can set up a completely new game or
76 continue an unfinished game.
77
78 ### Starting a New Game
79
80 When the server wants to start a new game, they SHALL send a `NETCODE_GAMEINFO`
81 message. The payload of this message is as follows:
82 * one BYTE denoting the color the server wants to play
83 (16 or 0x10 = white, 32 or 0x20 = black)
84 * one BYTE indicating if the game is played with time control (1 = yes, 0 = no)
85 * one WORD for the initial clock time in seconds
86 * one WORD for the number of seconds that are added per move
87 * one WORD for the delay in seconds for each move
88
89 When the game is played without time control, the last three WORDs MAY be
90 left uninitialized, but they SHALL be sent anyway.
91
92 ### Continuing a Game
93
94 When the server wants to continue a game, they SHALL send a `NETCODE_PGNDATA`
95 message. The payload of this message is as follows:
96 * the same two BYTES and three WORDS as in `NETCODE_GAMEINFO`, followed by
97 *
98
99 ### Clock Setup
100
101 For clock synchronization, the following rules SHALL be applied:
102
103 * the clock of each player starts after their first move
104 * the _increment_ is added _after_ a move, except…
105 * … when the initial clock is zero, then the clock starts with the increment
106 * when the used time for a move is less than the delay, the move costs no time
107 * the delay is always subtracted from the actual move time
108
109 ## Message Code Table
110
111 The following table shows the definitions of the network codes.
112
113 | Code Name | Byte | With Payload |
114 |----------------------|------|--------------|
115 | NETCODE_ACCEPT | 0x02 | no |
116 | NETCODE_DECLINE | 0x04 | no |
117 | NETCODE_DECLINE_MOVE | 0x05 | yes |
118 | NETCODE_GAMEINFO | 0x10 | yes |
119 | NETCODE_PGNDATA | 0x11 | yes |
120 | NETCODE_MOVE | 0x20 | yes |
121 | NETCODE_CHECK | 0x22 | no |
122 | NETCODE_CHECKMATE | 0x23 | no |
123 | NETCODE_STALEMATE | 0x28 | no |
124 | NETCODE_NOMATERIAL | 0x29 | no |
125 | NETCODE_THREEFOLD | 0x30 | no |
126 | NETCODE_RESIGN | 0x41 | no |
127 | NETCODE_REMIS | 0x42 | no |
128 | NETCODE_TAUNT | 0x43 | no |
129 | NETCODE_TIMEOVER | 0x44 | no |
130
131 The following codes are reserved for implementation.
132 They are not used during transmissions and can be used as return values
133 for functions to indicate errors.
134
135 | Code Name | Byte |
136 |----------------------|------|
137 | NETCODE_AGAIN | 0x70 |
138 | NETCODE_CONNLOST | 0x80 |
139 | NETCODE_ERROR | 0xFF |
140
141

Mercurial Repository: terminal-chess

mercurial