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