KGS Protocol Description
This XML document describes the KGS protocol. It is also used
to automatically generate the perl parser for all the messages and
structures in the protocol. Adapting it to other languages should be
trivial.
Structure and conventions of this document and the protocol
"Send" means messages send from the client to the server, while
"received" means messages send by the server to the client.
Everything on the wire are in little-endian format (what a shame).
Primitive types are mostly integers (signed "I<bits>",
unsigned "I<bits>"), ascii strings ("username"), or
zero-terminated UCS2-Strings ("STRING"). Yes, I know java is supposed
to do UTF-16, but no implementation seems to care...
For the rest, go figure or bug me, Marc Lehmann <pcg@goof.com>
Stream and message structure.
After connecting to the server, a handshake byte is exchanged. It's the
major version number of the protocol the client uses. Version 3 and 4 are
mostly the same, except that Version 4 clients expect server messages to
be compressed, version 3 clients not.
After that, the server sends back his version number, which is
always 3 in the current protocol. Most of the protocol variation is
determined by the server using the client version that is used in the
initial login message.
After the initial handshake, the client sends uncompressed
messages, while the server sends back a zlib-compressed
stream (rfc1950 and rfc1951).
All messages have the same header:
The length is the length of the full message including the header.
If the type is >= 0x4000 this is a message for a specific channel. The channel
number is always the next U16.
Primitive types used in the protocol.
Baaah... not much yet.
Constants, enumeration and set types used in the protocol.
Baaah... not yet.
Structs used in send & receive messages
Structs used in send messages
Password is a number calculated as follows (VERY insecure, basically plaintext!):
password = 0; for (characters) { password = password * 1055 + ascii (char) }
Request server statistics.
Request a user picture from the server.
Same code as pic_req, but with an additional data section that
should contain a JPEG image that is <=7KB. It must have 141×200 Pixels.
Send a global message. Maybe. Never tried, for obvious reasons :/
List the rooms in a specific group/category.
Create a new room. Not verified.
0x10 .. private room etc.. see code
request to update room game list (send once per minute)
Request room description.
No idea.
More following... TREE or challenge.
Player colour maybe? Unclear.
; # gives user access to the game (to what? ;)
Structs mainly used in receive messages
byo-yomi time / canadian time
periods / moves
Maybe the rules" are in TREE format. I forgot.
White
Black
Owner
< 0 not fully setup
)
)
)
Apparently the i3, f2, i4 are zero.
Receive messages
** maybe more following? **
** maybe more following? **
** maybe more following? **
** maybe more following? **
** maybe more following? **
)
idle warning, autologout soon (10 minutes...)
WILD guess
autologout
Reply to pic_req, contains an image in jpeg format.
global notice, sent to everybody
"permission denied" when joining a room
# loc 0" type="chat(?) loc 1 => gameinfo?, loc 2 => game result (more data)
Room messages
Not all room messages are for rooms only, and rooms need to parse
not only these messages. Orthogonality, what for?
Game messages
Unclear.
Superko-warning.
Unclear.
Unclear.
change teacher? something to do with editing?
Unclear.
# # recv_result(?)
?? !demonstration game??