$Revision: 1.78 $

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 almost trivial (and partly has been done).

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

"ORIGIN: CLIENT" means messages send from the client to the server, while "ORIGIN: SERVER" 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"), zero- or non-terminated UCS2-Strings ("ZSTRING" or "STRING"). Yes, I know java is supposed to do UTF-16, but no implementation seems to care...

To get a feel for the protocol, get the KGS perl module from CPAN, install it an run kgstrace, then conenct to with your client. kgstrace will dump all messages from and to the server.

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 do not. (version 3 probably is no longer supported).

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.

Beginning with version 2.5.x, a number is xored into the low byte of the length in sent packages only, as given by the following recurrence: rand[0] = 0; rand[i+1] = msg[i].length + (rand[i] * 0x04c2af9b + 0xfffffffb); xorbyte = rand >> 24, all in 32 bit unsigned iso-c arithmetic.

If the type is >= 0x4000 this is a message for a specific channel. The channel number is always the next U16. All of these channel values are valid, including zero.

Beginning with version 2.5.x, a number is added on received messages only. The algorithm is as follows:

         msglen < 44: type = typefield
         msglen > 44: type = (typefield + rand[i]) % 0x10000
            rand[0] = 0
            rand[i+1] = username[type % length username] + rand[i] * (type - 0x6cdd)
               where username is the user name of the logged-in user. coooool.

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 newer versions, as the packets itself are wasting lots of space.

Used in user_record.

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 accepting != 0 as true.

Komi values are multiplied by 2 or 4 to make them integer in the protocol.

The game result is also multiplied by 2 to give it higher resolution. There are also special values for wins by time etc., either in result or in the score* types, or both :)

A score value (used for displaying the score at the end of a game) are multiplied by 2 or 4 for a change (the 0.25 resolution is not used). In game structures it is encoded by dividing by two, though, so watch out! And in some others, it's encoded by multiplying by 1000... yuck!

Time values are multiplied by 1000, giving them millisecond accuracy.

64 bit timeval, milliseconds since posix epoch, e.g. my ($year, $month, $day) = (gmtime $date * 0.001)[5,4,3];

Password is a number calculated as follows (VERY insecure, basically plaintext!): password = 0; for char in characters do password ← password * 1055 + ascii_code (char)

An id chosen by the client, usually starting at one, to identify some handshakes initiated by the client, such as new games or memos.

Enumeration and set types used in the protocol.


Admins only(?)

Seems to be set on the english room. Or maybe not.

This room is private.

Special score values, in addition to numerical scores. Some are also used with their negative value. Unfortunately, these are the raw vaues, before scaling. WMS loves code duplication.

Also used negatively to score for white instead of black. Also used negatively to score for white instead of black. Also used negatively to score for white instead of black.

Convinience constants used in several places.

Sometimes used to mark absence of marks, or no player or etc...

Structs used in send & receive messages

Almost 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 challenges as well as in the special TREE "subprotocol". It tightly encodes the game parameters.

byo-yomi time / canadian time periods / moves

Structs used in messages from the client

Client-generated messages

Sent to login, usually the first message sent. The password needs to be set when the guest flag is true. Possible replies: . Followed by:

The "default" is the java vm version, not exactly he client version. However, you should always send a text like "Jonathan's C client version 0.6" or somesuch, so the server can, if necessary, block broken clients or client versions.

Request info about a certain user. Possible reply:

Update user info. Message structure is very similar to .

Should the password be updated?

This message is sent to initiate or continue a private chat with a user. You'll always receive a copy of what you have sent back from the server (as usual).

Name of sender ("yourself"). Name of recipient. The message.

Request server statistics. Replied with

Send in response to to keep the server from disconnecting.

No idea. Not used anymore?

Request user graph data, replied with .

Request a user picture from the server. Results in a 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.

A boolean, probably. Always true for me.

Unconditionally deletes all memos.

Send a global message. Maybe. Never tried, for obvious reasons :/. Results in a sent to all users.

Probably setting a notifier on a username, to get informed about changes using messages. sending your own username gives you a disconnect, so don't do that at home, kids!

Probably remove the notifier again.

List the rooms in a specific group/category. Results in a message.

Create a new room. Not verified. See ROOMFLAGs

Request a rooms update message for the given room.

Requests part of the users game record to be sent. Results in a or maybe a timeout.

If zero, start at the newest games, else this should be the timestamp of the first gamerecord sent in the response.

Joins the given 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.

Create a new game.

The room where to start the new game


0x2 == global open game list

When cloning a game, the rules are set up like this: count => 65535, ruleset => 0, time => 4294967295, timesys => 0, interval => 4294967295. Cloning itself seems to be implemented solely in the client (somewhat sane, for a change).

Load an existing game into a room(?) There is no indication that a new game is there except for a upd_observers message with your name in it. Which means you have to watch upd_observers messages that are not for any currently open game and open one. Ugh. The room to load the game into. From the game record. 0 == public, 2 == private Request to update room game list (send this once per minute to get updated). Results in upd_games messages. Request room description.

Used to send challenges to existing games.

Possibly an id. No idea. Better echo this from the challenge request.

Join a game. See join_room. Leave (or kick as admin?) a certain user from a game. Possibly upload an initial game to an empty room. Not tested.

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.

Marks stones ad dead (or alive?) by the client. Details unclear

Possibly true means mark dead and false unmark, but that's just a wild guess.

Request the game tree starting at a given node. This is used when the server only sends a partial tree (with end code "more").

Sent by the client to mark the game as done.

An id field (start at one please) to make sure that the client responds to the correct done click.

Used by the client to claim a win.

Adds the given amount of time to your opponent's clock.

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). If the name is empty, the game will continue normally.

Unclear. Maybe allow users to talk? No idea, really.

; # gives user access to the game (to what? ;)
Probably sets the "quiet" flag. Not checked.

Only during playing, moves.

Reject a challenge from a given user. Not checked.

Possibly an id. No idea. Better echo this from the challenge request.

Quite brokenly, the want this to send you more comments. Reply to .

Is send when a game is closed and should be saved on the gamerecord.

I forgot.

Sets (or clears) the quiet flag on a game.

Sent by the client just before it logs out.

Structs mainly used in messages send by the server

Send soon after log-in to set the defaults for game challenges.

The ruleset member is a pure guess, please verify. it could also be after size for example.

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 This field reflects either the movenum or the score, sorry, not even guards help, as the flags to determine that are _after_ the field. Arg. Divide by two to get the actual score (arg²). A game with the room id prepended.

The room channel.

Obsolete. Apparently the i3, f2, i4 are zero.

A single game record entry, as seen in .

Time this game was played.

A revision number in case there are multiple similar games.

0:11 == komi * 2; 12:15 == no idea, always 1-0-0-0?

0:5 == size; 6 no idea; 7 == inprogress

No idea. I see many values here.

Server-generated messages

User info. When the user registered (0 == never registered). When the user logged in for the last time.

Sent when no userinfo for the requested user could be found(?)

Name of sender (either yourself (echo) or other) Name of recipient.

idle warning, autologout soon (10 minutes...). Responding with usually helps.

I was blocked sooo many times for developing this client that it was easy to figure out. The KGS admins sure need no extra nazi training :( WILD guess autologout Sent by the server regularly, but not answering them isn't valid. Strange form of keepalive? User graph data. If empty, no graph is available. The unit seems to be centi-kyu, with 1 dan == 0, 2 dan == 100, 1 kyu == -100. There is probably one entry per day, the newest one last. Reply to pic_req, contains an image in jpeg format.

Account unknown.

Just a guess.

User is currently online, please use chat.

Just a guess.

The memo was sent successfully

global notice, sent to everybody # maybe soe notify? Totally unclear. # loc 0" type="userinfo, flags etc. loc 1 => gameinfo?, loc 2 => game result (more data)

Game result record?

Is sent after the initial messages, probably to signify the end of the login process.

"permission denied" when joining a room Unable to create new game.

The cid of the new_game etc. request.

The users game record.

Wether more games are available (must be requested manually by another message with the timestamp set to the timestamp of the first game of this packet.

Game records, from oldest to newest.


Adds or updates a global challenge (open game list).

The game. The "moves" member contains a small number. Probably garbage.

Room messages

Not all room messages are for rooms only, and rooms need to parse not only these messages. Orthogonality, what for?

Game messages


Possibly an id. No idea. Better echo this from the challenge request.

This field is optional


Send by the server when one of the players sends a done.

An id field to make sure that the client responds to the correct done click.

The high bit has the "please press done again" warning function, i.e. if set, opponent has changed board.

Sent when the opponent is out of time and moves, or when the other requests .

Colour who ran out of time (lost).


See . In addition, flags the tree as being uploaded completely.

Reject a challenge by a given user. Not checked.

Possibly an id. No idea. Better echo this from the challenge request.

Sent at end of games to set the comments not seen previously.

Sent at end of games to add all game commentary.

Quite brokenly, the server sends you this to make you ask for more comments. Reply with .

Notifies the client that a new game has been created. This message is sent long *after* upd_games and upd_observers etc. have been received. *sigh*

The newly created game.

The ID sent to the server in new_game.

Unclear. # # recv_result(?)

Sets (or clears) the quiet flag on a game.

Sent when joining a running game. Gives the remaining time + periods/moves for the players, to correctly initialize the clocks.

Remove a game from the global challenge list (open game list).

The game id to remove.

Probably the same. I suggest to use this id for no good reason.