$Revision: 1.80 $

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

STRUCTURE message_header

NAME TYPE VALUE DESCRIPTION GUARD

length

U16

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

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.

type

U16

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

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_2

BASE TYPE I16, LENGTH , MULTIPLIER 2

TYPE komi16_4

BASE TYPE I16, LENGTH , MULTIPLIER 4

TYPE komi32_2

BASE TYPE I32, LENGTH , MULTIPLIER 2

TYPE komi32_4

BASE TYPE I32, LENGTH , MULTIPLIER 4

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

TYPE result

BASE TYPE I32, LENGTH , MULTIPLIER 2

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

TYPE score16_2

BASE TYPE I16, LENGTH , MULTIPLIER 2

TYPE score16_4

BASE TYPE I16, LENGTH , MULTIPLIER 4

TYPE score32_4

BASE TYPE I32, LENGTH , MULTIPLIER 4

TYPE score32_1000

BASE TYPE I32, LENGTH , MULTIPLIER 1000

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!

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)

TYPE CLIENTID16

BASE TYPE U16, LENGTH , MULTIPLIER 1

TYPE CLIENTID8

BASE TYPE U8, LENGTH , MULTIPLIER 1

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.

enum: GAMETYPE

NAME	VALUE	DESCRIPTION
DEMONSTRATION	0
EDITING	1
TEACHING	2
SIMUL	3
FREE	4
RATED	5
PRIVATE	128	PRIVATE is or'ed onto DEMONSTRATION or TEACHING

set: GAMEFLAG

NAME	TYPE	VALUE	DESCRIPTION	GUARD
SCORED		1
ADJOURNED		2
UPLOADED		4

set: ROOMFLAG

NAME	VALUE	DESCRIPTION
ADMIN	0x01	Admins only(?)
DEFAULT	0x04	Seems to be set on the english room. Or maybe not.
PRIVATE	0x10	This room is private.

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. Unfortunately, these are the raw vaues, before scaling. WMS loves code duplication.

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

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	VALUE	DESCRIPTION
BLACK	0
WHITE	1
NONE	2	Sometimes used to mark absence of marks, or no player or etc...

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_2
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	6
ver_micro	U32	12
name	username
password	password	0
guest	flag	1
_unknown3	U16	0
locale	locale	"en_US"
clientver	DATA	"1.4.2_03: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 version 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

No idea. Not used anymore?

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: 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	DESCRIPTION
name	username
cid	CLIENTID16	A boolean, probably. Always true for me.
msg	STRING

ORIGIN: CLIENT; MESSAGE: delete_memos

NUMERIC TYPE (hex): 0024

Unconditionally deletes all memos.

NAME	TYPE	VALUE	DESCRIPTION	GUARD

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 this should be the timestamp of the first gamerecord sent in the game_record(0414) response.

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

Create a new game.

NAME	TYPE	DESCRIPTION
channel	U16	The room where to start the new game
cid	CLIENTID16
gametype	U8	GAMETYPE_UPLOAD probably not allowed. GAMETYPE_PRIVATE only allowd together with GAMETYPE_TEACHING, GAMETYPE_DEMONSTRATION.
flags	U8	0x2 == global open game list
rules	rules	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).
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: challenge

NUMERIC TYPE (hex): 4400

Used to send challenges to existing games.

NAME	TYPE	DESCRIPTION
channel	U16
black	user
white	user
gametype	U8
cid	CLIENTID8	Possibly an id. No idea. Better echo this from the challenge request.
rules	rules

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

NUMERIC TYPE (hex): 4407

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

NAME	TYPE	DESCRIPTION
channel	U16
x	U8
y	U8
dead	flag	Possibly true means mark dead and false unmark, but that's just a wild guess.

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

NUMERIC TYPE (hex): 440a

Sent by the client to mark the game as done.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
id	U32		An id field (start at one please) to make sure that the client responds to the correct done click.

ORIGIN: CLIENT; MESSAGE: claim_win

NUMERIC TYPE (hex): 440c

Used by the client to claim a win.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
player	U8

ORIGIN: CLIENT; MESSAGE: add_time

NUMERIC TYPE (hex): 440d

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

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
time	U32
player	U8

ORIGIN: CLIENT; MESSAGE: req_undo

NUMERIC TYPE (hex): 440e

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16

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

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	flag

ORIGIN: CLIENT; MESSAGE: game_move

NUMERIC TYPE (hex): 4427

Only during playing, moves.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
x	U8
y	U8

ORIGIN: CLIENT; MESSAGE: reject_challenge

NUMERIC TYPE (hex): 4429

Reject a challenge from a given user. Not checked.

NAME	TYPE	DESCRIPTION
channel	U16
name	username
gametype	U8
cid	CLIENTID8	Possibly an id. No idea. Better echo this from the challenge request.
rules	rules

ORIGIN: CLIENT; MESSAGE: more_comments

NUMERIC TYPE (hex): 442d

Quite brokenly, the want this to send you more comments. Reply to more_comments(442d).

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
node	U32

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	flag

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	DESCRIPTION
gametype	U8
ruleset	U8	The ruleset member is a pure guess, please verify. it could also be after size for example.
size	U32
timesys	U32
time	U32
byo_time	U32
byo_periods	U32
can_time	U32
can_stones	U32
notes	STRING

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
black	user	White
white	user	Black
owner	user	Owner
size	U8
handicap	I8	< 0 not fully setup
komi	komi16_2
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 (arg²).
flags	U16
observers	U32
saved	flag
notes	ZSTRING		handicap < 0

STRUCTURE room_game

A game with the room id prepended.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16		The room channel.
game	game

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_4
territory	U32
captures	U32
i3	U32
f2	U32
komi	komi32_4
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.
type	U8
handicap	U8
revision	U16	A revision number in case there are multiple similar games.
black	user
white	user
owner	user
komi	U16	0:11 == komi * 2; 12:15 == no idea, always 1-0-0-0?
score	score16_2
size	U8	0:5 == size; 6 no idea; 7 == inprogress
flags	U8	No idea. I see many values here.

Server-generated messages

ORIGIN: SERVER; MESSAGE: login

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

NAME	TYPE	VALUE
message	CONSTANT	login successful
success	CONSTANT	1
user	user
unknown1	U16
unknown2	U16

ORIGIN: SERVER; MESSAGE: login

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

NAME	TYPE	VALUE
message	CONSTANT	login successful: client version is outdated.
success	CONSTANT	1
user	user
unknown1	U16
unknown2	U16

ORIGIN: SERVER; MESSAGE: login

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

NAME	TYPE	VALUE
message	CONSTANT	login failed: client version out of date
user	user
unknown1	U16
unknown2	U16

ORIGIN: SERVER; MESSAGE: login

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

NAME	TYPE	VALUE
message	CONSTANT	login failed: wrong password
user	user
unknown1	U16
unknown2	U16

ORIGIN: SERVER; MESSAGE: login

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

NAME	TYPE	VALUE
message	CONSTANT	login failed: specified user does not exist
user	user
unknown1	U16
unknown2	U16

ORIGIN: SERVER; MESSAGE: login

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

NAME	TYPE	VALUE
message	CONSTANT	login failed: other user of same name already exists
user	user
unknown1	U16
unknown2	U16

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...). Responding with ping(001d) usually helps.

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

NUMERIC TYPE (hex): 0025

Account unknown.

NAME	TYPE	VALUE
name	username
cid	CLIENTID16
message	CONSTANT	memo send failed: account already exists
subtype	CONSTANT	25

ORIGIN: SERVER; MESSAGE: memo_error

NUMERIC TYPE (hex): 0026

Just a guess.

NAME	TYPE	VALUE
name	username
cid	CLIENTID16
message	CONSTANT	memo send failed: error 26
subtype	CONSTANT	26

ORIGIN: SERVER; MESSAGE: memo_error

NUMERIC TYPE (hex): 0027

User is currently online, please use chat.

NAME	TYPE	VALUE
name	username
cid	CLIENTID16
message	CONSTANT	memo send failed: user is online, use chat
subtype	CONSTANT	27

ORIGIN: SERVER; MESSAGE: memo_error

NUMERIC TYPE (hex): 0028

Just a guess.

NAME	TYPE	VALUE
name	username
cid	CLIENTID16
message	CONSTANT	memo send failed: error 28
subtype	CONSTANT	28

ORIGIN: SERVER; MESSAGE: memo

NUMERIC TYPE (hex): 0029

NAME	TYPE	VALUE	DESCRIPTION	GUARD
name	username
time	timestamp
message	ZSTRING

ORIGIN: SERVER; MESSAGE: memo_sent

NUMERIC TYPE (hex): 002a

The memo was sent successfully

NAME	TYPE	VALUE	DESCRIPTION	GUARD
name	username
cid	CLIENTID16

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	DESCRIPTION	GUARD
event	U32
user	user
gamerecord	game_record	Game result record?	event == 2

ORIGIN: SERVER; MESSAGE: login_done

NUMERIC TYPE (hex): 030c

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

NAME	TYPE	VALUE	DESCRIPTION	GUARD

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

NUMERIC TYPE (hex): 0412

Unable to create new game.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
message	CONSTANT	Sorry, you are already playing in one game, so you can't start playing in another.
cid	CLIENTID16		The cid of the new_game etc. request.

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 by another message with the timestamp set to the timestamp of the first game of this packet.
games	game_record	Game records, from oldest to newest.

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_challenges

NUMERIC TYPE (hex): 043a

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

NAME	TYPE	VALUE	DESCRIPTION	GUARD
games	room_game		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?

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

NUMERIC TYPE (hex): 4400

Unclear.

NAME	TYPE	DESCRIPTION
channel	U16
black	user
white	user
gametype	U8
cid	CLIENTID8	Possibly an id. No idea. Better echo this from the challenge request.
rules	rules
notes	STRING	This field is optional

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

NUMERIC TYPE (hex): 440a

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

NAME	TYPE	DESCRIPTION
channel	U16
id	U32	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.
black	flag
white	flag

ORIGIN: SERVER; MESSAGE: final_result

NUMERIC TYPE (hex): 440b

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
blackscore	scorevalues
whitescore	scorevalues

ORIGIN: SERVER; MESSAGE: out_of_time

NUMERIC TYPE (hex): 440c

Sent when the opponent is out of time and moves, or when the other requests userinfo(0008).

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
player	U8		Colour who won the game.

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	DESCRIPTION
channel	U16
name	username
gametype	U8
cid	CLIENTID8	Possibly an id. No idea. Better echo this from the challenge request.
rules	rules

ORIGIN: SERVER; MESSAGE: set_comments

NUMERIC TYPE (hex): 442b

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

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
node	U32
comments	STRING

ORIGIN: SERVER; MESSAGE: add_comments

NUMERIC TYPE (hex): 442c

Sent at end of games to add all game commentary.

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
node	U32
comments	STRING

ORIGIN: SERVER; MESSAGE: more_comments

NUMERIC TYPE (hex): 442d

Quite brokenly, the server sends you this to make you ask for more comments. Reply with more_comments(442d).

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
node	U32

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		The newly created game.
cid	CLIENTID16		The ID sent to the server in new_game.

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	flag

ORIGIN: SERVER; MESSAGE: set_gametime

NUMERIC TYPE (hex): 4437

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

NAME	TYPE	VALUE	DESCRIPTION	GUARD
channel	U16
black_time	time
black_moves	U16
white_time	time
white_moves	U16

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		The game id to remove.
game	U16		Probably the same. I suggest to use this id for no good reason.