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.
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 are in little-endian format (what a shame).
Primitive types (in upper case) are mostly integers ("Ibits"), ascii
strings ("USERNAME", "Alength"), or 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 exchanged. It's the
major version number of the protocol the client uses. Version 3 and 4 are
mostly the same, except that Version 4 clients expect server messages to
be compressed, version 3 clients not.
After that, the server sends back his version 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.
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:
MACRO message_header
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| _unknown |
I16 |
|
|
|
|
| length |
I16 |
|
|
|
The length is the length of the full message including the header.
|
| type |
I16 |
|
|
|
If the type is >= 0x4000 this is a message for a specific channel. The channel
number is always the next I16.
|
Constants, enumartaion and set types used in the protocol.
Baaah... not yet.
Macros used in send & receive messages
MACRO user
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| name |
USERNAME |
|
|
|
|
| flags |
I32 |
1 |
|
|
|
Macros used in send messages
MESSAGE login
NUMERIC TYPE (hex): 0000 SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| ver_major |
I32 |
2 |
|
|
|
| ver_minor |
I32 |
4 |
|
|
|
| ver_micro |
I32 |
67 |
|
|
|
| login |
USERNAME |
|
|
|
|
| password |
i64 |
0 |
|
|
|
| guest |
FLAG |
1 |
|
|
|
| _unknown3 |
I16 |
0 |
|
|
|
| locale |
A5 |
en_US |
|
|
|
| clientver |
DATA |
|
|
|
|
MESSAGE server_stats
NUMERIC TYPE (hex): 0014
| NAME |
TYPE |
DEFAULT |
GUARD |
|
Request server statistics.
|
MESSAGE pic_req
NUMERIC TYPE (hex): 0021
| NAME |
TYPE |
DEFAULT |
GUARD |
|
Request a user picture from the server.
|
| name |
USERNAME |
|
|
|
|
MESSAGE pic_upload
NUMERIC TYPE (hex): 0021
| NAME |
TYPE |
DEFAULT |
GUARD |
|
Same code as pic_req, but with an additional data section that
should contain a JPEG image that is <=7KB. It must have 141×200 Pixels.
|
| name |
USERNAME |
|
|
|
|
| data |
DATA |
|
|
|
|
MESSAGE gnotice
NUMERIC TYPE (hex): 0100
| NAME |
TYPE |
DEFAULT |
GUARD |
|
Send a global message. Maybe. Never tried, for obvious reasons :/
|
| notice |
STRING |
|
|
|
|
MESSAGE list_rooms
NUMERIC TYPE (hex): 0318
| NAME |
TYPE |
DEFAULT |
GUARD |
|
List the rooms in a specific group/category.
|
| group |
I8 |
|
|
|
|
MESSAGE new_room
NUMERIC TYPE (hex): 031a
| NAME |
TYPE |
DEFAULT |
GUARD |
|
Create a new room. Not verified.
|
| name |
USERNAME |
|
|
|
|
| i1 |
I32 |
0 |
|
|
|
| b1 |
I8 |
0 |
|
|
|
| b2 |
I8 |
255 |
|
|
|
| b3 |
I8 |
255 |
|
|
|
| group |
I8 |
1 |
|
|
|
| name |
STRING |
|
|
|
|
| description |
STRING |
|
|
|
|
| flags |
I8 |
|
|
|
0x10 .. private room etc.. see code
|
MESSAGE join_room
NUMERIC TYPE (hex): 4300 SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| user |
user |
|
|
|
|
MESSAGE msg_room
NUMERIC TYPE (hex): 4301 SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| name |
USERNAME |
|
|
|
|
| message |
STRING |
|
|
|
|
MESSAGE part_room
NUMERIC TYPE (hex): 4302 SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| name |
USERNAME |
|
|
|
|
MESSAGE new_game
NUMERIC TYPE (hex): 4305 SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| id |
I16 |
|
|
|
|
| gametype |
I32 |
|
|
|
|
| rules |
rules |
|
|
|
|
| notes |
STRING |
|
|
|
|
MESSAGE req_games
NUMERIC TYPE (hex): 430b SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
request to update room game list (send once per minute)
|
| channel |
I16 |
|
|
|
|
MESSAGE req_desc
NUMERIC TYPE (hex): 4319 SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
Request room description.
|
| channel |
I16 |
|
|
|
|
MESSAGE send_chal
NUMERIC TYPE (hex): 4400 SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
No idea.
|
| channel |
I16 |
|
|
|
|
| black |
USERNAME |
|
|
|
|
| white |
USERNAME |
|
|
|
More following... TREE or challenge.
|
MESSAGE join_game
NUMERIC TYPE (hex): 4403 SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| user |
user |
|
|
|
|
| channel |
I16 |
|
|
|
|
MESSAGE part_game
NUMERIC TYPE (hex): 4404 SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| name |
USERNAME |
|
|
|
|
MESSAGE set_tree
NUMERIC TYPE (hex): 4405 SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| tree |
TREE |
|
|
|
|
MESSAGE get_tree
NUMERIC TYPE (hex): 4408 SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| node |
I32 |
|
|
|
|
MESSAGE claim_win
NUMERIC TYPE (hex): 440c SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| _byte |
I8 |
|
|
|
Player colour maybe? Unclear.
|
MESSAGE add_time
NUMERIC TYPE (hex): 440d SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| time |
I32 |
|
|
|
|
| player |
I8 |
|
|
|
|
MESSAGE grant_undo
NUMERIC TYPE (hex): 440f SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
MESSAGE resign_game
NUMERIC TYPE (hex): 4410 SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| player |
I8 |
|
|
|
|
MESSAGE set_teacher
NUMERIC TYPE (hex): 441a SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| name |
USERNAME |
|
|
|
|
MESSAGE add_user
NUMERIC TYPE (hex): 4422 SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| othername |
USERNAME |
|
|
|
|
| name |
USERNAME |
|
|
| ; # gives user access to the game (to what? ;)
|
MESSAGE set_privacy
NUMERIC TYPE (hex): 4423 SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| private |
I8 |
|
|
|
|
MESSAGE reject_chal
NUMERIC TYPE (hex): 4429 SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| name |
USERNAME |
|
|
|
|
MESSAGE req_result
NUMERIC TYPE (hex): 4433 SEND
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| channel |
I16 |
|
|
|
|
Macros mainly used in receive messages
MACRO challenge_defaults
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| gametype |
I32 |
|
|
|
|
| size |
I32 |
|
|
|
|
| timesys |
I32 |
|
|
|
|
| time |
I32 |
|
|
|
|
| byo_time |
I32 |
|
|
|
|
| byo_periods |
I32 |
|
|
|
|
| can_time |
I32 |
|
|
|
|
| can_stones |
I32 |
|
|
| )
|
MACRO
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| ruleset |
I8 |
|
|
|
|
| size |
I8 |
|
|
|
|
| handicap |
I8 |
|
|
|
|
| komi |
KOMI |
|
|
|
|
| timesys |
I8 |
|
|
|
|
| time |
I32 |
|
|
|
|
| interval |
I32 |
|
|
|
byo-yomi time / canadian time
|
| count |
I16 |
|
|
|
periods / moves
|
MACRO challenge
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| user1 |
user |
|
|
|
|
| user2 |
user |
|
|
|
|
| gametype |
I32 |
|
|
|
|
| rules |
rules |
|
|
|
Maybe the rules" are in TREE format. I forgot.
|
MACRO game
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| type |
I32 |
|
|
|
|
| user1 |
user |
|
|
|
White
|
| user2 |
user |
|
|
|
Black
|
| user3 |
user |
|
|
|
Owner
|
| size |
I32 |
|
|
|
|
| handicap |
I32 |
|
|
|
< 0 not fully setup
|
| komi |
I322 |
|
|
|
|
| moves |
I16 |
|
|
|
|
| flags |
I16 |
|
|
|
|
| observers |
I32 |
|
|
|
|
| saved |
FLAG |
|
|
|
|
| notes |
STRING |
|
handicap < 0 |
|
|
MACRO room_obs
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| name |
A50 |
|
|
|
|
| channel |
I16 |
|
|
|
|
| flags |
I32 |
|
|
|
|
| users |
I32 |
|
|
| )
|
MACRO room
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| flags |
I8 |
|
|
|
|
| group |
I8 |
|
|
|
|
| users |
I16 |
|
|
|
|
| games |
I16 |
|
|
|
|
| name |
STRING |
|
|
| )
|
MACRO score
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| score |
I324 |
|
|
|
|
| territory |
I32 |
|
|
|
|
| captures |
I32 |
|
|
|
|
| i3 |
I32 |
|
|
|
|
| f2 |
I324 |
|
|
|
|
| komi |
I324 |
|
|
|
|
| i4 |
I32 |
|
|
| )
Apperently the i3, f2, i4 are zero.
|
Receive messages
MESSAGE login
NUMERIC TYPE (hex): 0001 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| result |
CONSTANT |
login ok |
|
|
|
| success |
CONSTANT |
1 |
|
|
|
MESSAGE login
NUMERIC TYPE (hex): 0002 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| result |
CONSTANT |
guest login ok |
|
|
|
| success |
CONSTANT |
1 |
|
|
|
MESSAGE login
NUMERIC TYPE (hex): 0003 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| result |
CONSTANT |
login error 3 |
|
|
** maybe more following? **
|
MESSAGE login
NUMERIC TYPE (hex): 0004 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| result |
CONSTANT |
wrong password |
|
|
** maybe more following? **
|
MESSAGE login
NUMERIC TYPE (hex): 0005 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| result |
CONSTANT |
user unknown |
|
|
** maybe more following? **
|
MESSAGE login
NUMERIC TYPE (hex): 0006 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| result |
CONSTANT |
user exists |
|
|
** maybe more following? **
|
MESSAGE login
NUMERIC TYPE (hex): 0018 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| result |
CONSTANT |
login error 18 |
|
|
** maybe more following? **
|
MESSAGE login
NUMERIC TYPE (hex): 0022 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
|
|
| result |
CONSTANT |
user or ip blocked |
|
|
|
| reason |
STRING |
|
|
|
|
MESSAGE msg_chat
NUMERIC TYPE (hex): 0013 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| user1 |
USERNAME |
|
|
|
|
| user2 |
USERNAME |
|
|
|
|
| message |
STRING |
|
|
|
|
MESSAGE stats
NUMERIC TYPE (hex): 0015 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| ver_major |
I16 |
|
|
|
|
| ver_minor |
I16 |
|
|
|
|
| ver_micro |
I16 |
|
|
|
|
| boot_time |
i64 |
|
|
|
|
| users_cur |
I32 |
|
|
|
|
| users_max |
I32 |
|
|
|
|
| users_lim |
I32 |
|
|
|
|
| accts_cur |
I32 |
|
|
|
|
| accts_max |
I32 |
|
|
|
|
| unknown1 |
I32 |
|
|
|
|
| work_max |
I32 |
|
|
|
|
| rooms_cur |
I32 |
|
|
|
|
| rooms_max |
I32 |
|
|
|
|
| rooms_lim |
I32 |
|
|
|
|
| games_cur |
I32 |
|
|
|
|
| games_max |
I32 |
|
|
|
|
| games_lim |
I32 |
|
|
|
|
| results_cur |
I32 |
|
|
|
|
| results_max |
I32 |
|
|
|
|
| unknown2 |
I32 |
|
|
|
|
| params_cur |
I32 |
|
|
|
|
| params_max |
I32 |
|
|
|
|
| bytes_in |
i64 |
|
|
|
|
| packets_in |
i64 |
|
|
|
|
| bytes_out |
i64 |
|
|
|
|
| packets_out |
i64 |
|
|
| )
|
MESSAGE idle_warn
NUMERIC TYPE (hex): 0016 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
idle warning, autologout soon (10 minutes...)
|
MESSAGE timewarning_default
NUMERIC TYPE (hex): 001b RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
WILD guess
|
| channel |
I16 |
|
|
|
|
| time |
I16 |
|
|
|
|
MESSAGE idle_err
NUMERIC TYPE (hex): 001c RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
autologout
|
MESSAGE ping
NUMERIC TYPE (hex): 001d RECV
MESSAGE userpic
NUMERIC TYPE (hex): 0021 RECV
| NAME |
TYPE |
DEFAULT |
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 |
GUARD |
|
global notice, sent to everybody
|
| notice |
STRING |
|
|
|
|
MESSAGE priv_room
NUMERIC TYPE (hex): 0310 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
"permission denied" when joining a room
|
| name |
STRING |
|
|
|
|
MESSAGE upd_rooms
NUMERIC TYPE (hex): 0318 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| rooms |
room |
|
|
|
|
MESSAGE upd_game2
NUMERIC TYPE (hex): 041c RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel_junk |
I16 |
|
|
|
|
| game |
game |
|
|
|
|
MESSAGE upd_user
NUMERIC TYPE (hex): 0202 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
# loc 0" type="chat(?) loc 1 => gameinfo?, loc 2 => game result (more data)
|
| location |
I32 |
|
|
|
|
| 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 |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| users |
user |
|
|
|
|
MESSAGE msg_room
NUMERIC TYPE (hex): 4301 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| name |
USERNAME |
|
|
|
|
| message |
STRING |
|
|
|
|
MESSAGE part_room
NUMERIC TYPE (hex): 4302 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| user |
user |
|
|
|
|
MESSAGE del_room
NUMERIC TYPE (hex): 4303 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
MESSAGE upd_games
NUMERIC TYPE (hex): 4304 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| games |
game |
|
|
|
|
MESSAGE desc_room
NUMERIC TYPE (hex): 4319 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| owner |
USERNAME |
|
|
|
|
| description |
STRING |
|
|
|
|
MESSAGE chal_defaults
NUMERIC TYPE (hex): 0411 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| defaults |
challenge_defaults |
|
|
|
|
Game messages
MESSAGE upd_chal
NUMERIC TYPE (hex): 4400 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
Unclear.
|
| channel |
I16 |
|
|
|
|
| challenge |
challenge |
|
|
|
|
MESSAGE upd_game
NUMERIC TYPE (hex): 4401 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| game |
game |
|
|
|
|
MESSAGE del_game
NUMERIC TYPE (hex): 4402 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
MESSAGE upd_observers
NUMERIC TYPE (hex): 4403 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| users |
user |
|
|
|
|
MESSAGE del_observer
NUMERIC TYPE (hex): 4404 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| name |
USERNAME |
|
|
|
|
MESSAGE set_tree
NUMERIC TYPE (hex): 4405 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| tree |
TREE |
|
|
|
|
MESSAGE upd_tree
NUMERIC TYPE (hex): 4406 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| tree |
TREE |
|
|
|
|
MESSAGE set_node
NUMERIC TYPE (hex): 4407 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| node |
I32 |
|
|
|
|
MESSAGE superko
NUMERIC TYPE (hex): 4409 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
Superko-warning.
|
| channel |
I16 |
|
|
|
|
MESSAGE final_result
NUMERIC TYPE (hex): 440b RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| blackscore |
score |
|
|
|
|
| whitescore |
score |
|
|
|
|
MESSAGE req_undo
NUMERIC TYPE (hex): 440e RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
MESSAGE resign_game
NUMERIC TYPE (hex): 4410 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| player |
I8 |
|
|
|
|
MESSAGE set_teacher
NUMERIC TYPE (hex): 441a RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| name |
USERNAME |
|
|
|
|
MESSAGE owner_left
NUMERIC TYPE (hex): 441d RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
Unclear.
|
| channel |
I16 |
|
|
|
|
MESSAGE teacher_left
NUMERIC TYPE (hex): 441e RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
Unclear.
|
| channel |
I16 |
|
|
|
|
MESSAGE unknown4422
NUMERIC TYPE (hex): 4422 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
change teacher? something to do with editing?
|
| channel |
I16 |
|
|
|
|
| name1 |
USERNAME |
|
|
|
|
| name2 |
USERNAME |
|
|
|
|
MESSAGE req_result
NUMERIC TYPE (hex): 4433 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
Unclear.
|
| channel |
I16 |
|
|
|
# # recv_result(?)
|
MESSAGE unknown4434
NUMERIC TYPE (hex): 4434 RECV
| NAME |
TYPE |
DEFAULT |
GUARD |
|
|
| channel |
I16 |
|
|
|
|
| b1 |
I8 |
|
|
|
?? !demonstration game??
|