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.
The current version of this document can always be found at
here, while
the HTML version of it can be found
here.
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
byo-yomi time / canadian time
periods / moves
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
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??