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.

If you feel you need to update the visual appearance of this document, feel free to look at doc/doc2html.xsl and improve it.

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 is in little-endian format (what a shame).

Primitive types are mostly integers (signed "I<bits>", unsigned "U<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 sent. It's the major version number of the protocol the client expects to receive. Version 3 and 4 are mostly the same, except that Version 4 clients expect server messages to be compressed, version 3 clients not.

The server sends back his protocol 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, not the initial handshake byte.

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 char in characters do password ← password * 1055 + ascii_code (char); The "default" is the java vm version, not exactly he client version. However, you should always send a tetx like "Jonathan's C client bersion 0.6" or somesuch, so the server can, if necessary, block broken clients or client versions. Request server statistics. Request a user picture from the server. Same code as pic_req, but with an additional data section that must 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??