$Revision: 1.48 $

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.

Please note that wms has told me that he will change the protocol in response to my efforts. No problems with changing the protocol for good, but he does this just to make it more difficult to reverse-engineer it, since his changes are neither required, nor useful (they just make the protocol less robust, without adding added value). He doesn't even care that this locks out some users who cannot upgrade (cgoban2 isn't available for their platform anymore). It hurts to see such a waste of time and efforts that could have been used to fix bugs or improve the client...

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. (update: sourceforge is weeks behind on their anonymous cvs servers so the above might be out-of-date. sorry.)

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...

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:

STRUCTURE message_header

NAME	TYPE	VALUE	DESCRIPTION	GUARD
_unknown	U16
length	U16
type	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)).

TYPE username

BASE TYPE A, LENGTH 10, MULTIPLIER

The basic user or login name, used throughout the protocol as a handle to the user.

TYPE roomname

BASE TYPE S, LENGTH 25, MULTIPLIER

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.

TYPE realname

BASE TYPE S, LENGTH 50, MULTIPLIER

TYPE email

BASE TYPE S, LENGTH 70, MULTIPLIER

TYPE userinfo

BASE TYPE S, LENGTH 1000, MULTIPLIER

TYPE url

BASE TYPE A, LENGTH 100, MULTIPLIER

Used in user_record.

TYPE locale

BASE TYPE A, LENGTH 5, MULTIPLIER

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.

TYPE flag

BASE TYPE U8, LENGTH , MULTIPLIER 1

Just a simple boolean value. 0 means false, and 1 generally true, but I suggest accepting != 0 as true.

TYPE komi16

BASE TYPE I16, LENGTH , MULTIPLIER 2

TYPE komi32

BASE TYPE I32, LENGTH , MULTIPLIER 2

TYPE komi324

BASE TYPE I32, LENGTH , MULTIPLIER 4

Komi values are multiplied by 2 to make them integer in the protocol. Well, *most* of the time at least...

TYPE result

BASE TYPE I32, LENGTH , MULTIPLIER 2

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 :)

TYPE score16

BASE TYPE I16, LENGTH , MULTIPLIER 4

TYPE score32

BASE TYPE I32, LENGTH , MULTIPLIER 4

TYPE score1000

BASE TYPE I32, LENGTH , MULTIPLIER 1000

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! And in some others, it's encoded by multiplying by 1000... yuck!

TYPE time

BASE TYPE U32, LENGTH , MULTIPLIER 1000

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

TYPE timestamp

BASE TYPE U64, LENGTH , MULTIPLIER 1000

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

TYPE password

BASE TYPE U64, LENGTH , MULTIPLIER

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

Enumeration and set types used in the protocol.

enum: GAMETYPE

NAME	VALUE	DESCRIPTION
DEMONSTRATION	0
TEACHING	1
FREE	2
RATED	3
TYPE4	4	Probably not used, but the protocol has space for it it seems.

enum: GAMEOPT

NAME	TYPE	VALUE	DESCRIPTION	GUARD
NONE		0
LECTURE		1
PRIVATE		2
SIMUL		3

set: GAMEFLAG

NAME	TYPE	VALUE	DESCRIPTION	GUARD
SCORED		1
ADJOURNED		2
UPLOADED		4

set: ROOMFLAG

NAME	TYPE	VALUE	DESCRIPTION	GUARD
ADMIN		0x01
DEFAULT		0x04
PRIVATE		0x10

set: GAMESTATUS

NAME	TYPE	VALUE	DESCRIPTION	GUARD
INPLAY		0x80

enum: SCORE

Special score values, in addition to numerical scores. Some are also used with their negative value.

NAME	VALUE	DESCRIPTION
TIMEOUT	16384 / 4	Also used negatively to score for white instead of black.
RESIGN	16385 / 4	Also used negatively to score for white instead of black.
FORFEIT	0 / 4	Also used negatively to score for white instead of black.
JIGO	16386 / 4
NO_RESULT	16386 / 4
ADJOURNED	16387 / 4
UNKNOWN	16389 / 4

enum: RULESET

NAME	TYPE	VALUE	DESCRIPTION	GUARD
JAPANESE		0
CHINESE		1
AGA		2
NEW_ZEALAND		3

enum: TIMESYS

NAME	TYPE	VALUE	DESCRIPTION	GUARD
NONE		0
ABSOLUTE		1
BYO_YOMI		2
CANADIAN		3

enum: COLOUR

Convinience constants used in several places.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
BLACK		0
WHITE		1

Structs used in send & receive messages

STRUCTURE user

CLASS: KGS::User

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.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
name	username
flags	U32	1

STRUCTURE rules

CLASS: KGS::Rules

This structure is used for challenges as well as in the special TREE "subprotocol". It tightly encodes the game parameters.

NAME	TYPE	DESCRIPTION
ruleset	U8
size	U8
handicap	U8
komi	komi16
timesys	U8
time	U32
interval	U32	byo-yomi time / canadian time
count	U16	periods / moves

Structs used in messages from the client

Client-generated messages

ORIGIN: CLIENT; MESSAGE: login

NUMERIC TYPE (hex): 0000

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(001c) login(0022). Followed by: timewarning_default(001b) chal_defaults(0411)

NAME	TYPE	VALUE	DESCRIPTION
ver_major	U32	2
ver_minor	U32	5
ver_micro	U32	2
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.

ORIGIN: CLIENT; MESSAGE: req_userinfo

NUMERIC TYPE (hex): 0007

Request info about a certain user. Possible reply: userinfo(0008)

NAME	TYPE	VALUE	DESCRIPTION	GUARD
name	username

ORIGIN: CLIENT; MESSAGE: update_userinfo

NUMERIC TYPE (hex): 0007

Update user info. Message structure is very similar to userinfo(0008).

NAME	TYPE	VALUE	DESCRIPTION
setpass	flag		Should the password be updated?
password	password	0
realname	realname
email	email
info	userinfo
homepage	url
_unused	U64	0
_unused	U64	0

ORIGIN: CLIENT; MESSAGE: msg_chat

NUMERIC TYPE (hex): 0013

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	TYPE	DESCRIPTION
name	username	Name of sender ("yourself").
name2	username	Name of recipient.
message	STRING	The message.

ORIGIN: CLIENT; MESSAGE: req_stats

NUMERIC TYPE (hex): 0014

Request server statistics. Replied with stats(0015)

NAME	TYPE	VALUE	DESCRIPTION	GUARD

ORIGIN: CLIENT; MESSAGE: idle_reset

NUMERIC TYPE (hex): 0016

Send in response to idle_warn(0016) to keep the server from disconnecting.

NAME	TYPE	VALUE	DESCRIPTION	GUARD

ORIGIN: CLIENT; MESSAGE: ping

NUMERIC TYPE (hex): 001d

Wild guess, I send it in idle_warn(0016).

NAME	TYPE	VALUE	DESCRIPTION	GUARD

ORIGIN: CLIENT; MESSAGE: req_usergraph

NUMERIC TYPE (hex): 001e

Request user graph data, replied with usergraph(001e).

NAME	TYPE	VALUE	DESCRIPTION	GUARD
name	username

ORIGIN: CLIENT; MESSAGE: fetch_memos

NUMERIC TYPE (hex): 001f

Unclear. Fetch all outstanding memos? Replied with memo(001f)

NAME	TYPE	VALUE	DESCRIPTION	GUARD

ORIGIN: CLIENT; MESSAGE: req_pic

NUMERIC TYPE (hex): 0021

Request a user picture from the server. Results in a userpic(0021) or a timeout.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
name	username

ORIGIN: CLIENT; MESSAGE: upload_pic

NUMERIC TYPE (hex): 0021

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	VALUE	DESCRIPTION	GUARD
name	username
data	DATA

ORIGIN: CLIENT; MESSAGE: send_memo

NUMERIC TYPE (hex): 0023

NAME	TYPE	VALUE	DESCRIPTION	GUARD
name	username
msg	STRING

ORIGIN: CLIENT; MESSAGE: gnotice

NUMERIC TYPE (hex): 0100

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

NAME	TYPE	VALUE	DESCRIPTION	GUARD
notice	STRING

ORIGIN: CLIENT; MESSAGE: notify_add

NUMERIC TYPE (hex): 0200

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!

NAME	TYPE	VALUE	DESCRIPTION	GUARD
name	username

ORIGIN: CLIENT; MESSAGE: notify_del

NUMERIC TYPE (hex): 0201

Probably remove the notifier again.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
name	username

ORIGIN: CLIENT; MESSAGE: list_rooms

NUMERIC TYPE (hex): 0318

List the rooms in a specific group/category. Results in a upd_rooms(0318) message.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
group	U8

ORIGIN: CLIENT; MESSAGE: new_room

NUMERIC TYPE (hex): 031a

Create a new room. Not verified.

NAME	TYPE	VALUE	DESCRIPTION
name	username
i1	U32	0
b1	U8	0
b2	U8	255
b3	U8	255
group	U8	1
name	ZSTRING
description	ZSTRING
flags	U8		See ROOMFLAGs

ORIGIN: CLIENT; MESSAGE: req_upd_rooms

NUMERIC TYPE (hex): 031b

Request a rooms update message for the given room.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16

ORIGIN: CLIENT; MESSAGE: req_game_record

NUMERIC TYPE (hex): 0413

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

NAME	TYPE	VALUE	DESCRIPTION	GUARD
name	username
timestamp	timestamp		If zero, start at the newest games, else only send games before the given timestap.

ORIGIN: CLIENT; MESSAGE: join_room

NUMERIC TYPE (hex): 4300

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	VALUE	DESCRIPTION	GUARD
channel	U16
user	user

ORIGIN: CLIENT; MESSAGE: msg_room

NUMERIC TYPE (hex): 4301

Send a message to the room.

NAME	TYPE	DESCRIPTION
channel	U16
name	username	Must be the login-name of the user.
message	STRING

ORIGIN: CLIENT; MESSAGE: part_room

NUMERIC TYPE (hex): 4302

Remove yourself (or maybe others as admin) from a room.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
name	username

ORIGIN: CLIENT; MESSAGE: new_game

NUMERIC TYPE (hex): 4305

Unclear. Start a new game.

Clone: 00000: 20202020 20202020 20202020 20203238 28 00010: 9d000543 0d000000 00000000 00130201 ...C............ 00020: 0000ffff ffffffff ffffffff 00000000 ..ÿÿÿÿÿÿÿÿÿÿ....

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
id	U16
gametype	U32
rules	rules
notes	STRING

ORIGIN: CLIENT; MESSAGE: load_game

NUMERIC TYPE (hex): 430a

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.

NAME	TYPE	DESCRIPTION
channel	U16	The room to load the game into.
timestamp	timestamp	From the game record.
user	username
flags	U8	0 == public, 2 == private

ORIGIN: CLIENT; MESSAGE: req_games

NUMERIC TYPE (hex): 430b

Request to update room game list (send this once per minute to get updated). Results in upd_games messages.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16

ORIGIN: CLIENT; MESSAGE: req_desc

NUMERIC TYPE (hex): 4319

Request room description.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16

ORIGIN: CLIENT; MESSAGE: send_challenge

NUMERIC TYPE (hex): 4400

Unclear.

NAME	TYPE	DESCRIPTION
channel	U16
black	username
white	username	More following... TREE or challenge.

ORIGIN: CLIENT; MESSAGE: join_game

NUMERIC TYPE (hex): 4403

Join a game. See join_room.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
user	user

ORIGIN: CLIENT; MESSAGE: part_game

NUMERIC TYPE (hex): 4404

Leave (or kick as admin?) a certain user from a game.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
name	username

ORIGIN: CLIENT; MESSAGE: set_tree

NUMERIC TYPE (hex): 4405

Possibly upload an initial game to an empty room. Not tested.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
tree	TREE

ORIGIN: CLIENT; MESSAGE: upd_tree

NUMERIC TYPE (hex): 4406

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	VALUE	DESCRIPTION	GUARD
channel	U16
tree	TREE

ORIGIN: CLIENT; MESSAGE: get_tree

NUMERIC TYPE (hex): 4408

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	VALUE	DESCRIPTION	GUARD
channel	U16
node	U32

ORIGIN: CLIENT; MESSAGE: claim_win

NUMERIC TYPE (hex): 440c

Unclear.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
_byte	U8		Player colour maybe? Unclear.

ORIGIN: CLIENT; MESSAGE: add_time

NUMERIC TYPE (hex): 440d

Not checked.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
time	U32
player	U8

ORIGIN: CLIENT; MESSAGE: grant_undo

NUMERIC TYPE (hex): 440f

Can be send after a req_undo message was received to grant the undo.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16

ORIGIN: CLIENT; MESSAGE: resign_game

NUMERIC TYPE (hex): 4410

Resign the game.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
player	U8

ORIGIN: CLIENT; MESSAGE: set_teacher

NUMERIC TYPE (hex): 441a

Change the teacher to somebody else (or possibly yourself == take it).

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
name	username

ORIGIN: CLIENT; MESSAGE: allow_user

NUMERIC TYPE (hex): 4422

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

NAME	TYPE	DESCRIPTION
channel	U16
othername	username
name	username	; # gives user access to the game (to what? ;)

ORIGIN: CLIENT; MESSAGE: set_privacy

NUMERIC TYPE (hex): 4423

Probably sets the "quiet" flag. Not checked.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
private	U8

ORIGIN: CLIENT; MESSAGE: reject_challenge

NUMERIC TYPE (hex): 4429

Reject a challenge from a given user. Not checked.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
name	username

ORIGIN: CLIENT; MESSAGE: save_game

NUMERIC TYPE (hex): 442e

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

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16

ORIGIN: CLIENT; MESSAGE: req_result

NUMERIC TYPE (hex): 4433

I forgot.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16

ORIGIN: CLIENT; MESSAGE: set_quiet

NUMERIC TYPE (hex): 4434

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

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
quiet	U8

ORIGIN: CLIENT; MESSAGE: msg_game

NUMERIC TYPE (hex): 4436

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
message	STRING

ORIGIN: CLIENT; MESSAGE: quit

NUMERIC TYPE (hex): ffff

Sent by the client just before it logs out.

NAME	TYPE	VALUE	DESCRIPTION	GUARD

Structs mainly used in messages send by the server

STRUCTURE challenge_defaults

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

NAME	TYPE	VALUE	DESCRIPTION	GUARD
gametype	U32
size	U32
timesys	U32
time	U32
byo_time	U32
byo_periods	U32
can_time	U32
can_stones	U32

STRUCTURE challenge

CLASS: KGS::Challenge

A challenge.

NAME	TYPE	DESCRIPTION
user1	user
user2	user
gametype	U32
rules	rules	Maybe the rules" are in TREE format. I forgot.

STRUCTURE game

CLASS: KGS::Game

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	DESCRIPTION	GUARD
channel	U16
type	U8
user1	user	White
user2	user	Black
user3	user	Owner
size	U8
handicap	I8	< 0 not fully setup
komi	komi16
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!) (arg²).
flags	U16
observers	U32
saved	flag
notes	STRING		handicap < 0

STRUCTURE room_obs

Obsolete.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
name	roomname
channel	U16
flags	U32
users	U32

STRUCTURE room

CLASS: KGS::Room

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
flags	U8
group	U8
users	U16
games	U16
name	STRING

STRUCTURE scorevalues

CLASS: KGS::Score

NAME	TYPE	DESCRIPTION
score	score32
territory	U32
captures	U32
i3	U32
f2	U32
komi	komi324
i4	U32	Apparently the i3, f2, i4 are zero.

STRUCTURE game_record

CLASS: KGS::GameRecord

A single game record entry, as seen in userinfo(0008).

NAME	TYPE	DESCRIPTION
timestamp	timestamp	Time this game was played.
flags1	U8
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
flags2	U16
score	score16
flags3	U8

Server-generated messages

ORIGIN: SERVER; MESSAGE: login

NUMERIC TYPE (hex): 0001 (possibly in response to login(0000) )

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	login successful
success	CONSTANT	1

ORIGIN: SERVER; MESSAGE: login

NUMERIC TYPE (hex): 0002 (possibly in response to login(0000) )

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	login successful: client version is outdated.
success	CONSTANT	1

ORIGIN: SERVER; MESSAGE: login

NUMERIC TYPE (hex): 0003 (possibly in response to login(0000) )

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	login failed: client version out of date	maybe more following?

ORIGIN: SERVER; MESSAGE: login

NUMERIC TYPE (hex): 0004 (possibly in response to login(0000) )

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	login failed: wrong password	maybe more following?

ORIGIN: SERVER; MESSAGE: login

NUMERIC TYPE (hex): 0005 (possibly in response to login(0000) )

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	login failed: specified user does not exist

ORIGIN: SERVER; MESSAGE: login

NUMERIC TYPE (hex): 0006 (possibly in response to login(0000) )

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	login failed: registered user of same name exists

ORIGIN: SERVER; MESSAGE: userinfo

NUMERIC TYPE (hex): 0008 (possibly in response to req_userinfo(0007) )

User info.

NAME	TYPE	DESCRIPTION
_unused0	flag
user	user
_unused1	U64
realname	realname
email	email
info	userinfo
homepage	url
regdate	timestamp	When the user registered (0 == never registered).
lastlogin	timestamp	When the user logged in for the last time.

ORIGIN: SERVER; MESSAGE: upd_userinfo_result

NUMERIC TYPE (hex): 0009

NAME	TYPE	VALUE	DESCRIPTION	GUARD
name	username
message	CONSTANT	Thanks for registering.

ORIGIN: SERVER; MESSAGE: upd_userinfo_result

NUMERIC TYPE (hex): 000a

NAME	TYPE	VALUE	DESCRIPTION	GUARD
name	username
message	CONSTANT	The user "%s" has been successfully updated.

ORIGIN: SERVER; MESSAGE: upd_userinfo_result

NUMERIC TYPE (hex): 000b

NAME	TYPE	VALUE	DESCRIPTION	GUARD
name	username
message	CONSTANT	There is no user "%s". Update failed.

ORIGIN: SERVER; MESSAGE: userinfo_failed

NUMERIC TYPE (hex): 0012

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

NAME	TYPE	VALUE	DESCRIPTION	GUARD
name	username

ORIGIN: SERVER; MESSAGE: msg_chat

NUMERIC TYPE (hex): 0013

NAME	TYPE	DESCRIPTION
name	username	Name of sender (either yourself (echo) or other)
name2	username	Name of recipient.
message	STRING

ORIGIN: SERVER; MESSAGE: stats

NUMERIC TYPE (hex): 0015 (possibly in response to req_stats(0014) )

NAME	TYPE	VALUE	DESCRIPTION	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

ORIGIN: SERVER; MESSAGE: idle_warn

NUMERIC TYPE (hex): 0016 (possibly in response to idle_reset(0016) )

idle warning, autologout soon (10 minutes...)

NAME	TYPE	VALUE	DESCRIPTION	GUARD

ORIGIN: SERVER; MESSAGE: login

NUMERIC TYPE (hex): 0018 (possibly in response to login(0000) )

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	logged out: another client logged in with your username

ORIGIN: SERVER; MESSAGE: login

NUMERIC TYPE (hex): 001c (possibly in response to login(0000) )

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	logged out: idle for too long

ORIGIN: SERVER; MESSAGE: error

NUMERIC TYPE (hex): 0020

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	Sorry, you have too many unfinished games. You cannot turn on your rank. Please finish some of your games, then try again.

ORIGIN: SERVER; MESSAGE: login

NUMERIC TYPE (hex): 0022 (possibly in response to login(0000) )

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	VALUE	DESCRIPTION	GUARD
reason	STRING
result	CONSTANT	user or ip blocked

ORIGIN: SERVER; MESSAGE: timewarning_default

NUMERIC TYPE (hex): 001b (possibly in response to login(0000) )

WILD guess

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
time	U16

ORIGIN: SERVER; MESSAGE: idle_err

NUMERIC TYPE (hex): 001c

autologout

NAME	TYPE	VALUE	DESCRIPTION	GUARD

ORIGIN: SERVER; MESSAGE: ping

NUMERIC TYPE (hex): 001d

Sent by the server regularly, but not answering them isn't valid. Strange form of keepalive?

NAME	TYPE	VALUE	DESCRIPTION	GUARD

ORIGIN: SERVER; MESSAGE: usergraph

NUMERIC TYPE (hex): 001e (possibly in response to req_usergraph(001e) )

User graph data.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
name	username
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.

ORIGIN: SERVER; MESSAGE: memo

NUMERIC TYPE (hex): 001f (possibly in response to fetch_memos(001f) )

Unclear. "Leave Message"? 6 strings following.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
s1	ZSTRING
s2	ZSTRING
s3	ZSTRING
s4	ZSTRING
s5	ZSTRING
s6	ZSTRING

ORIGIN: SERVER; MESSAGE: userpic

NUMERIC TYPE (hex): 0021 (possibly in response to req_pic(0021) )

NAME	TYPE	VALUE	DESCRIPTION	GUARD
name	username		Reply to pic_req, contains an image in jpeg format.
data	DATA

ORIGIN: SERVER; MESSAGE: gnotice

NUMERIC TYPE (hex): 0100 (possibly in response to gnotice(0100) )

global notice, sent to everybody

NAME	TYPE	VALUE	DESCRIPTION	GUARD
notice	STRING

ORIGIN: SERVER; MESSAGE: notify_event

NUMERIC TYPE (hex): 0202

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

NAME	TYPE	GUARD
event	U32
user	user
gamerecord	game_record	event == 2

ORIGIN: SERVER; MESSAGE: priv_room

NUMERIC TYPE (hex): 0310

"permission denied" when joining a room

NAME	TYPE	VALUE	DESCRIPTION	GUARD
name	STRING

ORIGIN: SERVER; MESSAGE: upd_rooms

NUMERIC TYPE (hex): 0318 (possibly in response to list_rooms(0318) )

NAME	TYPE	VALUE	DESCRIPTION	GUARD
rooms	room

ORIGIN: SERVER; MESSAGE: chal_defaults

NUMERIC TYPE (hex): 0411 (possibly in response to login(0000) )

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
defaults	challenge_defaults

ORIGIN: SERVER; MESSAGE: game_error

NUMERIC TYPE (hex): 0412

Unable to create challenge. The channel is be optional.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	Sorry, you are already playing in one game, so you can't start playing in another.
channel	U16

ORIGIN: SERVER; MESSAGE: game_record

NUMERIC TYPE (hex): 0414 (possibly in response to req_game_record(0413) )

The users game record.

NAME	TYPE	DESCRIPTION
name	username
more	flag	Wether more games are available (must be requested manually)
games	game_record

ORIGIN: SERVER; MESSAGE: error

NUMERIC TYPE (hex): 0417

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	Sorry, your opponent is currently not logged in, so you can't resume this game.

ORIGIN: SERVER; MESSAGE: error

NUMERIC TYPE (hex): 0418

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	Sorry, your opponent is already playing in a game, so you cannot continue this one.

ORIGIN: SERVER; MESSAGE: error

NUMERIC TYPE (hex): 0419

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	Sorry, the server is out of boards! Please wait a few minutes and try to start a game again.

ORIGIN: SERVER; MESSAGE: upd_game2

NUMERIC TYPE (hex): 041c

Unclear.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel_junk	U16
game	game

ORIGIN: SERVER; MESSAGE: error

NUMERIC TYPE (hex): 041f

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	Sorry, the game you tried to load was not correctly saved...probably caused by the server crashing. It cannot be recovered.

ORIGIN: SERVER; MESSAGE: error

NUMERIC TYPE (hex): 0420

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	Sorry, user "%s" has left the game you are starting before you could challenge them. You will have to play against somebody else.

ORIGIN: SERVER; MESSAGE: error

NUMERIC TYPE (hex): 0421

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	Sorry, this game is a private lesson. You will not be allowed to observe it.

ORIGIN: SERVER; MESSAGE: add_global_challenge

NUMERIC TYPE (hex): 043a

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

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
game	game

Room messages

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

ORIGIN: SERVER; MESSAGE: join_room

NUMERIC TYPE (hex): 4300 (possibly in response to join_room(4300) )

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
users	user

ORIGIN: SERVER; MESSAGE: msg_room

NUMERIC TYPE (hex): 4301

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
name	username
message	STRING

ORIGIN: SERVER; MESSAGE: part_room

NUMERIC TYPE (hex): 4302

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
user	user

ORIGIN: SERVER; MESSAGE: del_room

NUMERIC TYPE (hex): 4303

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16

ORIGIN: SERVER; MESSAGE: upd_games

NUMERIC TYPE (hex): 4304

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
games	game

ORIGIN: SERVER; MESSAGE: desc_room

NUMERIC TYPE (hex): 4319

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
owner	username
description	STRING

Game messages

ORIGIN: SERVER; MESSAGE: upd_challenge

NUMERIC TYPE (hex): 4400

Unclear.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
challenge	challenge

ORIGIN: SERVER; MESSAGE: upd_game

NUMERIC TYPE (hex): 4401

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
game	game

ORIGIN: SERVER; MESSAGE: del_game

NUMERIC TYPE (hex): 4402

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16

ORIGIN: SERVER; MESSAGE: upd_observers

NUMERIC TYPE (hex): 4403

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
users	user

ORIGIN: SERVER; MESSAGE: del_observer

NUMERIC TYPE (hex): 4404

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
name	username

ORIGIN: SERVER; MESSAGE: set_tree

NUMERIC TYPE (hex): 4405

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
tree	TREE

ORIGIN: SERVER; MESSAGE: upd_tree

NUMERIC TYPE (hex): 4406

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
tree	TREE

ORIGIN: SERVER; MESSAGE: superko

NUMERIC TYPE (hex): 4409

Superko-warning.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16

ORIGIN: SERVER; MESSAGE: final_result

NUMERIC TYPE (hex): 440b

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
blackscore	scorevalues
whitescore	scorevalues

ORIGIN: SERVER; MESSAGE: req_undo

NUMERIC TYPE (hex): 440e

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16

ORIGIN: SERVER; MESSAGE: resign_game

NUMERIC TYPE (hex): 4410

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
player	U8

ORIGIN: SERVER; MESSAGE: game_error

NUMERIC TYPE (hex): 4415

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
message	CONSTANT	Sorry, this is a lecture game. Only authorized players are allowed to make comments.

ORIGIN: SERVER; MESSAGE: set_teacher

NUMERIC TYPE (hex): 441a

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
name	username

ORIGIN: SERVER; MESSAGE: owner_left

NUMERIC TYPE (hex): 441d

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
message	CONSTANT	Sorry, the owner of this game has left. Nobody will be allowed to edit it until the owner returns.

ORIGIN: SERVER; MESSAGE: teacher_left

NUMERIC TYPE (hex): 441e

Unclear.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16

ORIGIN: SERVER; MESSAGE: allow_user_result

NUMERIC TYPE (hex): 4422

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	User "%s" will now be allowed full access to your game.
channel	U16

ORIGIN: SERVER; MESSAGE: allow_user_result

NUMERIC TYPE (hex): 4424

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	Sorry, user "%s" is a guest and cannot be allowed full access to your game.
channel	U16

ORIGIN: SERVER; MESSAGE: allow_user_result

NUMERIC TYPE (hex): 4425

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	Sorry, user "%s" does not seem to exist and cannot be allowed into your game.
channel	U16

ORIGIN: SERVER; MESSAGE: add_tree

NUMERIC TYPE (hex): 4428

See set_tree(4405). In addition, flags the tree as being uploaded completely.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
tree	TREE

ORIGIN: SERVER; MESSAGE: reject_challenge

NUMERIC TYPE (hex): 4429

Reject a challenge by a given user. Not checked.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
name	username

ORIGIN: SERVER; MESSAGE: new_game

NUMERIC TYPE (hex): 442f

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*

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
id	U16

ORIGIN: SERVER; MESSAGE: req_result

NUMERIC TYPE (hex): 4433

Unclear.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16		# # recv_result(?)

ORIGIN: SERVER; MESSAGE: set_quiet

NUMERIC TYPE (hex): 4434

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

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
quiet	U8

ORIGIN: SERVER; MESSAGE: del_global_challenge

NUMERIC TYPE (hex): 443b

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

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
game	U16