KGS Protocol Description

This XML document describes the KGS protocol. It is also used to automatically generate the perl parser for all the messages and structures in the protocol. Adapting it to other languages should be trivial.

If you feel you need to update the visual appearance of this document, feel free to look at doc/doc2html.xsl and improve it.

Structure and conventions of this document and the protocol

"Send" means messages send from the client to the server, while "received" means messages send by the server to the client.

Everything on the wire is in little-endian format (what a shame).

Primitive types are mostly integers (signed "I<bits>", unsigned "U<bits>"), ascii strings ("username"), or zero-terminated UCS2-Strings ("STRING"). Yes, I know java is supposed to do UTF-16, but no implementation seems to care...

For the rest, go figure or bug me, Marc Lehmann <pcg@goof.com>

Stream and message structure.

After connecting to the server, a handshake byte is sent. It's the major version number of the protocol the client expects to receive. Version 3 and 4 are mostly the same, except that Version 4 clients expect server messages to be compressed, version 3 clients not.

The server sends back his protocol number, which is always 3 in the current protocol. Most of the protocol variation is determined by the server using the client version that is used in the initial login message, not the initial handshake byte.

After the initial handshake, the client sends uncompressed messages, while the server sends back a zlib-compressed stream (rfc1950 and rfc1951).

All messages have the same header:

STRUCTURE message_header

NAME TYPE DEFAULT DEC-GUARD
_unknown U16
length U16
The length is the length of the full message including the header.
type U16
If the type is >= 0x4000 this is a message for a specific channel. The channel number is always the next U16.

Primitive types used in the protocol.

Baaah... not much yet.

TYPE username

BASE TYPE: A
LENGTH: 12
MULTIPLIER:

TYPE roomname

BASE TYPE: S
LENGTH: 25
MULTIPLIER:

TYPE locale

BASE TYPE: A
LENGTH: 5
MULTIPLIER:

TYPE flag

BASE TYPE: U8
LENGTH:
MULTIPLIER: 1

TYPE komi

BASE TYPE: I32
LENGTH:
MULTIPLIER: 2

TYPE result

BASE TYPE: I32
LENGTH:
MULTIPLIER: 2

TYPE score

BASE TYPE: I32
LENGTH:
MULTIPLIER: 4

TYPE time

BASE TYPE: U32
LENGTH:
MULTIPLIER: 100

Constants, enumeration and set types used in the protocol.

Baaah... not yet.

Structs used in send & receive messages

STRUCTURE user

CLASS: KGS::User
NAME TYPE DEFAULT DEC-GUARD
name username
flags U32 1

Structs used in send messages

MESSAGE login

NUMERIC TYPE (hex): 0000 SEND
NAME TYPE DEFAULT DEC-GUARD
ver_major U32 2
ver_minor U32 4
ver_micro U32 67
name username
password U64 0
Password is a number calculated as follows (VERY insecure, basically plaintext!): password = 0; for char in characters do password ← password * 1055 + ascii_code (char);
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 tetx like "Jonathan's C client bersion 0.6" or somesuch, so the server can, if necessary, block broken clients or client versions.

MESSAGE server_stats

NUMERIC TYPE (hex): 0014 SEND
NAME TYPE DEFAULT DEC-GUARD
Request server statistics.

MESSAGE pic_req

NUMERIC TYPE (hex): 0021 SEND
NAME TYPE DEFAULT DEC-GUARD
Request a user picture from the server.
name username

MESSAGE pic_upload

NUMERIC TYPE (hex): 0021 SEND
NAME TYPE DEFAULT DEC-GUARD
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 username
data DATA

MESSAGE gnotice

NUMERIC TYPE (hex): 0100 SEND
NAME TYPE DEFAULT DEC-GUARD
Send a global message. Maybe. Never tried, for obvious reasons :/
notice STRING

MESSAGE list_rooms

NUMERIC TYPE (hex): 0318 SEND
NAME TYPE DEFAULT DEC-GUARD
List the rooms in a specific group/category.
group U8

MESSAGE new_room

NUMERIC TYPE (hex): 031a SEND
NAME TYPE DEFAULT DEC-GUARD
Create a new room. Not verified.
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

MESSAGE join_room

NUMERIC TYPE (hex): 4300 SEND
NAME TYPE DEFAULT DEC-GUARD
channel U16
user user

MESSAGE msg_room

NUMERIC TYPE (hex): 4301 SEND
NAME TYPE DEFAULT DEC-GUARD
channel U16
name username
message STRING

MESSAGE part_room

NUMERIC TYPE (hex): 4302 SEND
NAME TYPE DEFAULT DEC-GUARD
channel U16
name username

MESSAGE new_game

NUMERIC TYPE (hex): 4305 SEND
NAME TYPE DEFAULT DEC-GUARD
channel U16
id U16
gametype U32
rules rules
notes STRING

MESSAGE req_games

NUMERIC TYPE (hex): 430b SEND
NAME TYPE DEFAULT DEC-GUARD
request to update room game list (send once per minute)
channel U16

MESSAGE req_desc

NUMERIC TYPE (hex): 4319 SEND
NAME TYPE DEFAULT DEC-GUARD
Request room description.
channel U16

MESSAGE send_chal

NUMERIC TYPE (hex): 4400 SEND
NAME TYPE DEFAULT DEC-GUARD
No idea.
channel U16
black username
white username
More following... TREE or challenge.

MESSAGE join_game

NUMERIC TYPE (hex): 4403 SEND
NAME TYPE DEFAULT DEC-GUARD
user user
channel U16

MESSAGE part_game

NUMERIC TYPE (hex): 4404 SEND
NAME TYPE DEFAULT DEC-GUARD
channel U16
name username

MESSAGE set_tree

NUMERIC TYPE (hex): 4405 SEND
NAME TYPE DEFAULT DEC-GUARD
channel U16
tree TREE

MESSAGE get_tree

NUMERIC TYPE (hex): 4408 SEND
NAME TYPE DEFAULT DEC-GUARD
channel U16
node U32

MESSAGE claim_win

NUMERIC TYPE (hex): 440c SEND
NAME TYPE DEFAULT DEC-GUARD
channel U16
_byte U8
Player colour maybe? Unclear.

MESSAGE add_time

NUMERIC TYPE (hex): 440d SEND
NAME TYPE DEFAULT DEC-GUARD
channel U16
time U32
player U8

MESSAGE grant_undo

NUMERIC TYPE (hex): 440f SEND
NAME TYPE DEFAULT DEC-GUARD
channel U16

MESSAGE resign_game

NUMERIC TYPE (hex): 4410 SEND
NAME TYPE DEFAULT DEC-GUARD
channel U16
player U8

MESSAGE set_teacher

NUMERIC TYPE (hex): 441a SEND
NAME TYPE DEFAULT DEC-GUARD
channel U16
name username

MESSAGE add_user

NUMERIC TYPE (hex): 4422 SEND
NAME TYPE DEFAULT DEC-GUARD
channel U16
othername username
name username
; # gives user access to the game (to what? ;)

MESSAGE set_privacy

NUMERIC TYPE (hex): 4423 SEND
NAME TYPE DEFAULT DEC-GUARD
channel U16
private U8

MESSAGE reject_chal

NUMERIC TYPE (hex): 4429 SEND
NAME TYPE DEFAULT DEC-GUARD
channel U16
name username

MESSAGE req_result

NUMERIC TYPE (hex): 4433 SEND
NAME TYPE DEFAULT DEC-GUARD
channel U16

Structs mainly used in receive messages

STRUCTURE challenge_defaults

NAME TYPE DEFAULT DEC-GUARD
gametype U32
size U32
timesys U32
time U32
byo_time U32
byo_periods U32
can_time U32
can_stones U32

STRUCTURE rules

CLASS: KGS::Rules
NAME TYPE DEFAULT DEC-GUARD
ruleset U8
size U8
handicap U8
komi komi
timesys U8
time U32
interval U32
byo-yomi time / canadian time
count U16
periods / moves

STRUCTURE challenge

CLASS: KGS::Challenge
NAME TYPE DEFAULT DEC-GUARD
user1 user
user2 user
gametype U32
rules rules
Maybe the rules" are in TREE format. I forgot.

STRUCTURE game

CLASS: KGS::Game
NAME TYPE DEFAULT DEC-GUARD
channel U16
type U32
user1 user
White
user2 user
Black
user3 user
Owner
size U32
handicap I32
< 0 not fully setup
komi komi
moves U16
flags U16
observers U32
saved flag
notes STRING handicap < 0

STRUCTURE room_obs

NAME TYPE DEFAULT DEC-GUARD
name roomname
channel U16
flags U32
users U32

STRUCTURE room

CLASS: KGS::Room
NAME TYPE DEFAULT DEC-GUARD
channel U16
flags U8
group U8
users U16
games U16
name STRING

STRUCTURE score

CLASS: KGS::Score
NAME TYPE DEFAULT DEC-GUARD
score score
territory U32
captures U32
i3 U32
f2 U32
komi komi
i4 U32
Apparently the i3, f2, i4 are zero.

Receive messages

MESSAGE login

NUMERIC TYPE (hex): 0001 RECV
NAME TYPE DEFAULT DEC-GUARD
result CONSTANT "login ok"
success CONSTANT 1

MESSAGE login

NUMERIC TYPE (hex): 0002 RECV
NAME TYPE DEFAULT DEC-GUARD
result CONSTANT "guest login ok"
success CONSTANT 1

MESSAGE login

NUMERIC TYPE (hex): 0003 RECV
NAME TYPE DEFAULT DEC-GUARD
result CONSTANT "login error 3"
** maybe more following? **

MESSAGE login

NUMERIC TYPE (hex): 0004 RECV
NAME TYPE DEFAULT DEC-GUARD
result CONSTANT "wrong password"
** maybe more following? **

MESSAGE login

NUMERIC TYPE (hex): 0005 RECV
NAME TYPE DEFAULT DEC-GUARD
result CONSTANT "user unknown"
** maybe more following? **

MESSAGE login

NUMERIC TYPE (hex): 0006 RECV
NAME TYPE DEFAULT DEC-GUARD
result CONSTANT "user exists"
** maybe more following? **

MESSAGE login

NUMERIC TYPE (hex): 0018 RECV
NAME TYPE DEFAULT DEC-GUARD
result CONSTANT "login error 18"
** maybe more following? **

MESSAGE login

NUMERIC TYPE (hex): 0022 RECV
NAME TYPE DEFAULT DEC-GUARD
result CONSTANT "user or ip blocked"
reason STRING

MESSAGE msg_chat

NUMERIC TYPE (hex): 0013 RECV
NAME TYPE DEFAULT DEC-GUARD
user1 username
user2 username
message STRING

MESSAGE stats

NUMERIC TYPE (hex): 0015 RECV
NAME TYPE DEFAULT DEC-GUARD
ver_major U16
ver_minor U16
ver_micro U16
boot_time U64
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

MESSAGE idle_warn

NUMERIC TYPE (hex): 0016 RECV
NAME TYPE DEFAULT DEC-GUARD
idle warning, autologout soon (10 minutes...)

MESSAGE timewarning_default

NUMERIC TYPE (hex): 001b RECV
NAME TYPE DEFAULT DEC-GUARD
WILD guess
channel U16
time U16

MESSAGE idle_err

NUMERIC TYPE (hex): 001c RECV
NAME TYPE DEFAULT DEC-GUARD
autologout

MESSAGE ping

NUMERIC TYPE (hex): 001d RECV
NAME TYPE DEFAULT DEC-GUARD

MESSAGE userpic

NUMERIC TYPE (hex): 0021 RECV
NAME TYPE DEFAULT DEC-GUARD
name username
Reply to pic_req, contains an image in jpeg format.
data DATA

MESSAGE gnotice

NUMERIC TYPE (hex): 0100 RECV
NAME TYPE DEFAULT DEC-GUARD
global notice, sent to everybody
notice STRING

MESSAGE priv_room

NUMERIC TYPE (hex): 0310 RECV
NAME TYPE DEFAULT DEC-GUARD
"permission denied" when joining a room
name STRING

MESSAGE upd_rooms

NUMERIC TYPE (hex): 0318 RECV
NAME TYPE DEFAULT DEC-GUARD
rooms room

MESSAGE upd_game2

NUMERIC TYPE (hex): 041c RECV
NAME TYPE DEFAULT DEC-GUARD
channel_junk U16
game game

MESSAGE upd_user

NUMERIC TYPE (hex): 0202 RECV
NAME TYPE DEFAULT DEC-GUARD
# loc 0" type="chat(?) loc 1 => gameinfo?, loc 2 => game result (more data)
location U32
user user
lotsofinfo DATA location == 2

Room messages

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

MESSAGE join_room

NUMERIC TYPE (hex): 4300 RECV
NAME TYPE DEFAULT DEC-GUARD
channel U16
users user

MESSAGE msg_room

NUMERIC TYPE (hex): 4301 RECV
NAME TYPE DEFAULT DEC-GUARD
channel U16
name username
message STRING

MESSAGE part_room

NUMERIC TYPE (hex): 4302 RECV
NAME TYPE DEFAULT DEC-GUARD
channel U16
user user

MESSAGE del_room

NUMERIC TYPE (hex): 4303 RECV
NAME TYPE DEFAULT DEC-GUARD
channel U16

MESSAGE upd_games

NUMERIC TYPE (hex): 4304 RECV
NAME TYPE DEFAULT DEC-GUARD
channel U16
games game

MESSAGE desc_room

NUMERIC TYPE (hex): 4319 RECV
NAME TYPE DEFAULT DEC-GUARD
channel U16
owner username
description STRING

MESSAGE chal_defaults

NUMERIC TYPE (hex): 0411 RECV
NAME TYPE DEFAULT DEC-GUARD
channel U16
defaults challenge_defaults

Game messages

MESSAGE upd_chal

NUMERIC TYPE (hex): 4400 RECV
NAME TYPE DEFAULT DEC-GUARD
Unclear.
channel U16
challenge challenge

MESSAGE upd_game

NUMERIC TYPE (hex): 4401 RECV
NAME TYPE DEFAULT DEC-GUARD
channel U16
game game

MESSAGE del_game

NUMERIC TYPE (hex): 4402 RECV
NAME TYPE DEFAULT DEC-GUARD
channel U16

MESSAGE upd_observers

NUMERIC TYPE (hex): 4403 RECV
NAME TYPE DEFAULT DEC-GUARD
channel U16
users user

MESSAGE del_observer

NUMERIC TYPE (hex): 4404 RECV
NAME TYPE DEFAULT DEC-GUARD
channel U16
name username

MESSAGE set_tree

NUMERIC TYPE (hex): 4405 RECV
NAME TYPE DEFAULT DEC-GUARD
channel U16
tree TREE

MESSAGE upd_tree

NUMERIC TYPE (hex): 4406 RECV
NAME TYPE DEFAULT DEC-GUARD
channel U16
tree TREE

MESSAGE set_node

NUMERIC TYPE (hex): 4407 RECV
NAME TYPE DEFAULT DEC-GUARD
channel U16
node U32

MESSAGE superko

NUMERIC TYPE (hex): 4409 RECV
NAME TYPE DEFAULT DEC-GUARD
Superko-warning.
channel U16

MESSAGE final_result

NUMERIC TYPE (hex): 440b RECV
NAME TYPE DEFAULT DEC-GUARD
channel U16
blackscore score
whitescore score

MESSAGE req_undo

NUMERIC TYPE (hex): 440e RECV
NAME TYPE DEFAULT DEC-GUARD
channel U16

MESSAGE resign_game

NUMERIC TYPE (hex): 4410 RECV
NAME TYPE DEFAULT DEC-GUARD
channel U16
player U8

MESSAGE set_teacher

NUMERIC TYPE (hex): 441a RECV
NAME TYPE DEFAULT DEC-GUARD
channel U16
name username

MESSAGE owner_left

NUMERIC TYPE (hex): 441d RECV
NAME TYPE DEFAULT DEC-GUARD
Unclear.
channel U16

MESSAGE teacher_left

NUMERIC TYPE (hex): 441e RECV
NAME TYPE DEFAULT DEC-GUARD
Unclear.
channel U16

MESSAGE unknown4422

NUMERIC TYPE (hex): 4422 RECV
NAME TYPE DEFAULT DEC-GUARD
change teacher? something to do with editing?
channel U16
name1 username
name2 username

MESSAGE req_result

NUMERIC TYPE (hex): 4433 RECV
NAME TYPE DEFAULT DEC-GUARD
Unclear.
channel U16
# # recv_result(?)

MESSAGE unknown4434

NUMERIC TYPE (hex): 4434 RECV
NAME TYPE DEFAULT DEC-GUARD
channel U16
b1 U8
?? !demonstration game??