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.
"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>
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:
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
_unknown | U16 | |||
length | U16 | |||
type | U16 |
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 ccepting != 0 as true.
Komi values are multiplied by 2 to make them integer in the protocol. Well, *most* of the time at least...
The game result is also multiplied by two 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 four for a change (the 0.25 resolution is not used). In game structures it is encoded by dividing by two, though, so watch out!
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)
Baaah... not yet.
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.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
name | username | |||
flags | U32 | 1 |
This structure is used for challanges as well as in the special TREE "subprotocol". It tightly encodes the game parameters.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
ruleset | U8 | |||
size | U8 | |||
handicap | U8 | |||
komi | komi16 | |||
timesys | U8 | |||
time | U32 | |||
interval | U32 | byo-yomi time / canadian time | ||
count | U16 | periods / moves |
Sent to login, usually the first message sent. The password needs to be set when the guest flag is true. Possible replies: login(0001) login(0002) login(0003) login(0004) login(0005) login(0006) login(0018) login(0022). Followed by: timewarning_default(001b) chal_defaults(0411)
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
ver_major | U32 | 2 | ||
ver_minor | U32 | 4 | ||
ver_micro | U32 | 67 | ||
name | username | |||
password | password | 0 | ||
guest | flag | 1 | ||
_unknown3 | U16 | 0 | ||
locale | locale | "en_US" | ||
clientver | DATA | "1.4.1_01:Swing app:Sun Microsystems Inc." | The "default" is the java vm version, not exactly he client version. However, you should always send a text like "Jonathan's C client bersion 0.6" or somesuch, so the server can, if necessary, block broken clients or client versions. |
Request info about a certain user. Possible reply: userinfo(0008)
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
name | username |
Update user info. Message structure is very similar to userinfo(0008).
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
setpass | flag | Should the password be updated? | ||
password | password | 0 | ||
realname | realname | |||
info | userinfo | |||
homepage | url | |||
_unused | U64 | 0 | ||
_unused | U64 | 0 |
Request server statistics. Replied with stats(0015)
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|
Wild guess, I send it in idle_warn(0016).
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|
Request user graph data, replied with usergraph(001e).
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
name | username |
Unclear. Fetch all outstanding memos? Replied with memo(001f)
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|
Request a user picture from the server. Results in a userpic(0021) or a timeout.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
name | username |
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.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
name | username | |||
data | DATA |
Send a global message. Maybe. Never tried, for obvious reasons :/. Results in a gnotice(0100) sent to all users.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
notice | STRING |
List the rooms in a specific group/category. Results in a upd_rooms(0318) message.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
group | U8 |
Create a new room. Not verified.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
name | username | |||
i1 | U32 | 0 | ||
b1 | U8 | 0 | ||
b2 | U8 | 255 | ||
b3 | U8 | 255 | ||
group | U8 | 1 | ||
name | STRING | |||
description | STRING | |||
flags | U8 | 0x10 .. private room etc.. see code |
Requests part of the users game record to be sent. Results in a game_record(0414) or maybe a timeout.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
name | username | |||
timestamp | timestamp | If zero, start at the newest games, else only send games before the given timestap. |
Joins the given room. join_room(4300) messages for yourself and all users in that room, as well as the initial gamelist, are send if the room exists. If not, timeout...
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
user | user |
Send a message to the room.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
name | username | Must be the login-name of the user. | ||
message | STRING |
Remove yourself (or maybe others as admin) from a room.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
name | username |
Unclear. Start a new game.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
id | U16 | |||
gametype | U32 | |||
rules | rules | |||
notes | STRING |
Request to update room game list (send this once per minute to get updated). Results in upd_games messages.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 |
Request room description.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 |
Unclear.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
black | username | |||
white | username | More following... TREE or challenge. |
Join a game. See join_room.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
user | user |
Leave (or kick as admin?) a certain user from a game.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
name | username |
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.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
tree | TREE |
Request the game tree starting at a given node. This is used when the server only sends a partial tree (with end code "more").
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
node | U32 |
Unclear.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
_byte | U8 | Player colour maybe? Unclear. |
Not checked.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
time | U32 | |||
player | U8 |
Can be send after a req_undo message was received to grant the undo.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 |
Resign the game.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
player | U8 |
Change the teacher to somebody else (or possibly yourself == take it).
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
name | username |
Unclear. Maybe allow users to talk? No idea, really.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
othername | username | |||
name | username | ; # gives user access to the game (to what? ;) |
Probably sets the "quiet" flag. Not checked.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
private | U8 |
Reject a challenge from a given user. Not checked.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
name | username |
I forgot.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 |
Send soon after log-in to set the defaults for game challenges.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
gametype | U32 | |||
size | U32 | |||
timesys | U32 | |||
time | U32 | |||
byo_time | U32 | |||
byo_periods | U32 | |||
can_time | U32 | |||
can_stones | U32 |
A challenge.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
user1 | user | |||
user2 | user | |||
gametype | U32 | |||
rules | rules | 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.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
type | U32 | |||
user1 | user | White | ||
user2 | user | Black | ||
user3 | user | Owner | ||
size | U32 | |||
handicap | I32 | < 0 not fully setup | ||
komi | komi32 | |||
moves | I16 | 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 (NOT score16!). | ||
flags | U16 | |||
observers | U32 | |||
saved | flag | |||
notes | STRING | handicap < 0 |
Obsolete.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
name | roomname | |||
channel | U16 | |||
flags | U32 | |||
users | U32 |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
flags | U8 | |||
group | U8 | |||
users | U16 | |||
games | U16 | |||
name | STRING |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
score | score32 | |||
territory | U32 | |||
captures | U32 | |||
i3 | U32 | |||
f2 | U32 | |||
komi | komi324 | |||
i4 | U32 | Apparently the i3, f2, i4 are zero. |
A single game record entry, as seen in userinfo(0008).
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
timestamp | timestamp | Time this game was played. | ||
flags | U8 | High four bits are handicap, low four bits are gametype (encoded strangely? unclear). | ||
user1 | user | White, flags contain low 8 bits of revision (bits 16-23). | ||
user2 | user | Black, flags contain high 8 bits of revision (bits 16-23). | ||
user3 | user | Owner (or empty) | ||
komi | komi16 | |||
score | score16 | |||
status | U8 | 0x80 inprogress |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
result | CONSTANT | "login ok" | ||
success | CONSTANT | 1 |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
result | CONSTANT | "guest login ok" | ||
success | CONSTANT | 1 |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
result | CONSTANT | "login error 3" | ** maybe more following? ** |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
result | CONSTANT | "wrong password" | ** maybe more following? ** |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
result | CONSTANT | "user unknown" | ** maybe more following? ** |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
result | CONSTANT | "user exists" | ** maybe more following? ** |
User info.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
user | user | |||
_unused | U64 | |||
realname | realname | |||
info | userinfo | |||
homepage | url | |||
regdate | timestamp | When the user registered (0 == never registered). | ||
lastlogin | timestamp | When the user logged in for the last time. |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
result | CONSTANT | "login error 18" | ** maybe more following? ** |
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 :(
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
reason | STRING | |||
result | CONSTANT | "user or ip blocked" |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
user1 | username | |||
user2 | username | |||
message | STRING |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
ver_major | U16 | |||
ver_minor | U16 | |||
ver_micro | U16 | |||
boot_time | timestamp | |||
users_cur | U32 | |||
users_max | U32 | |||
users_lim | U32 | |||
accts_cur | U32 | |||
accts_max | U32 | |||
unknown1 | U32 | |||
work_max | U32 | |||
rooms_cur | U32 | |||
rooms_max | U32 | |||
rooms_lim | U32 | |||
games_cur | U32 | |||
games_max | U32 | |||
games_lim | U32 | |||
results_cur | U32 | |||
results_max | U32 | |||
unknown2 | U32 | |||
params_cur | U32 | |||
params_max | U32 | |||
bytes_in | U64 | |||
packets_in | U64 | |||
bytes_out | U64 | |||
packets_out | U64 |
idle warning, autologout soon (10 minutes...)
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|
WILD guess
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
time | U16 |
autologout
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|
Sent by the server regularly, but not answering them isn't valid. Strange form of keepalive?
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|
User graph data.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
data | I16 | 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. |
Unclear. "Leave Message"? 6 strings following.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
s1 | STRING | |||
s2 | STRING | |||
s3 | STRING | |||
s4 | STRING | |||
s5 | STRING | |||
s6 | STRING |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
name | username | Reply to pic_req, contains an image in jpeg format. | ||
data | DATA |
global notice, sent to everybody
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
notice | STRING |
# maybe soe notify? Totally unclear. # loc 0" type="chat(?) loc 1 => gameinfo?, loc 2 => game result (more data)
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
location | U32 | |||
user | user | |||
lotsofinfo | DATA | location == 2 |
"permission denied" when joining a room
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
name | STRING |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
rooms | room |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
defaults | challenge_defaults |
Unable to create challenge. The channel might be optional.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 |
The users game record.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
name | username | |||
more | flag | Wether more games are available (must be requested manually) | ||
games | game_record |
Unclear.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel_junk | U16 | |||
game | game |
Not all room messages are for rooms only, and rooms need to parse not only these messages. Orthogonality, what for?
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
users | user |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
name | username | |||
message | STRING |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
user | user |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
games | game |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
owner | username | |||
description | STRING |
Unclear.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
challenge | challenge |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
game | game |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
users | user |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
name | username |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
tree | TREE |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
tree | TREE |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
node | U32 |
Superko-warning.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
blackscore | scorevalues | |||
whitescore | scorevalues |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
player | U8 |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
name | username |
Unclear.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 |
Unclear.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 |
change teacher? something to do with editing?
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
name1 | username | |||
name2 | username |
Unclear.
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | # # recv_result(?) |
NAME | TYPE | DEFAULT | DESCRIPTION | DEC-GUARD |
---|---|---|---|---|
channel | U16 | |||
b1 | U8 | ?? !demonstration game?? |