$Revision: 1.13 $
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.
Please note that the author of KGS has told me that he will
change the protocol in response to my efforts. This does not
necessarily mean that he will change the protocol just to make it
difficult to reverse-engineer the protocol, but if this happens,
I might not have the resources the track them, if they are too
extensive. Anyway, he made it clear that no help whatsoever is to be
expected.
If you feel you need to update the visual appearance of this
document, feel free to look 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.
Apart from the basic types, I need to define some extra types to
deal with fixed-point values (based on integer types) or fixed-length
strings (either 7-bit-ascii or more limited (A), or UCS-2
based (S)).
The basic user or login name, used throughout the protocol
as a handle to the user.
Many strings in the protocol are fixed-width for no good reason
(maybe this is one reason for using compression in enwer versions, as
the packets itself are wasting lots of space.
A kind of locale specifier. It seems the general format seems to be
lowercase language, underscore, uppercase location, e.g. en_US. More
fancy specifications don't fit.
Just a simple boolean value. 0 means false, and 1 generally true,
but I suggest ccepting != 0 as true.
Komi values are multiplied by 2 to make them integer in the
protocol.
The game result is also multiplied by four to give it higher
resolution. There are also special values for wins by time etc.
A score value (used for displaying the score at the end of a game)
are multiplied by four for a change. I have not yet seen 0.25 scores,
please somebody tell me where they happen, or if they happen.
Time values are multiplied by 1000, giving them millisecond
accuracy.
Constants, enumeration and set types used in the protocol.
Baaah... not yet.
Structs used in send & receive messages
Everywhere a user + flags is required, even used in some places
where only a username is required. I see no general rule on when a
complete user and when a partial user is required.
This structure is used for challanges as well as in the special
TREE "subprotocol". It tightly encodes the game parameters.
byo-yomi time / canadian time
periods / moves
Structs used in send messages
Send on the initial login. The password needs to be set when the
guest flag is true.
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. Results in a userpic-reply
or a timeout :/.
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. Results in a upd_rooms message.
Create a new room. Not verified.
0x10 .. private room etc.. see code
Joins the given room. join_room messages for yourself
and all users in that room, as well as the initial gamelist, are
send if the room exists. If not, timeout...
Send a message to the room.
Must be the login-name of the user.
Remove yourself (or maybe others as admin) from a room.
Unclear.
Request to update room game list (send this once per minute to get
updated). Results in upd_games messages.
Request room description.
Unclear.
More following... TREE or challenge.
Join a game. See join_room.
Leave (or kick as admin?) a certain user from a game.
Upload a partial game tree to the server. This is used
to send moves and even in-game comments to the server. For the comments,
the server prepends the username and rank.
Request the game tree starting at a given node. This is used
when the server only sends a partial tree (with end code "more").
Unclear.
Player colour maybe? Unclear.
Not checked.
Can be send after a req_undo message was received to grant the undo.
Resign the game.
Change the teacher to somebody else (or possibly yourself == take it).
Unclear. Maybe allow users to talk? No idea, really.
; # gives user access to the game (to what? ;)
Probably sets the "quiet" flag. Not checked.
Reject a challenge from a given user. Not checked.
I forgot.
Structs mainly used in receive messages
Send soon after log-in to set the defaults for game challenges.
A challenge.
Maybe the rules" are in TREE format. I forgot.
Basic information about a game. Used in rooms for the gamelist and
in games to detect when a game is saved, changed type (e.g. R => D)
etc.
White
Black
Owner
< 0 not fully setup
Obsolete.
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??