ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/kgsueme/doc/protocol.xml
Revision: 1.28
Committed: Sun Jul 20 15:01:24 2003 UTC (23 years, 3 months ago) by pcg
Content type: text/xml
Branch: MAIN
Changes since 1.27: +90 -88 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 pcg 1.1 <?xml version="1.0" encoding="utf-8"?>
2     <html>
3     <head>
4     <title>KGS Protocol Description</title>
5     <!--
6     Copyright (C) 2003 Marc Lehmannn &lt;pcg@goof.com&gt;
7    
8     You can redistribute and/or modify this document under the terms of
9     the GNU General Public License as published by the Free Software
10     Foundation; either version 2 of the License, or (at your option) any
11     later version.
12    
13     This document is distributed in the hope that it will be useful,
14     but WITHOUT ANY WARRANTY; without even the implied warranty of
15     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16     General Public License for more details.
17    
18     You should have received a copy of the GNU General Public License
19     along with this program; if not, write to the Free Software
20     Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
21     -->
22     </head>
23     <body>
24    
25 pcg 1.28 <h1>$Revision: 1.27 $</h1>
26 pcg 1.10
27 pcg 1.1 <h1>KGS Protocol Description</h1>
28    
29     <p>This XML document describes the KGS protocol. It is also used
30     to automatically generate the perl parser for all the messages and
31     structures in the protocol. Adapting it to other languages should be
32     trivial.</p>
33 pcg 1.10
34     <p><b>Please note that the author of KGS has told me that he will
35 pcg 1.25 change the protocol in response to my efforts. Unfortunately, he does
36     this just to make it more difficult to reverse-engineer it, since his
37     changes are neither required, nor useful (they just make the protocol
38     less robust, without adding added value).</b></p>
39 pcg 1.1
40 pcg 1.4 <p>If you feel you need to update the visual appearance of this
41 pcg 1.11 document, feel free to look <tt>doc/doc2html.xsl</tt> and improve
42 pcg 1.4 it.</p>
43    
44 pcg 1.8 <p>The current version of this document can always be found at
45     <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/kgsueme/kgsueme/doc/protocol.xml?rev=HEAD&amp;content-type=text/xml">here</a>, while
46     the HTML version of it can be found
47     <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/kgsueme/kgsueme/doc/protocol.html?rev=HEAD&amp;content-type=text/html">here</a>.
48     </p>
49    
50 pcg 1.24 <h2>Changes for server version 2.5</h2>
51 pcg 1.23
52     <p>Sorry - I have little time to dissect the protocol, but as far
53     as I can see, there was no deeper need for the protocol change, as
54 pcg 1.25 the protocol itself didn't change in a significant way. The only
55 pcg 1.23 significant change was the addition of a linear congruence generator
56 pcg 1.25 that is xor'ed into the packet length, and some heavy foolery to change
57     receive packets. It seems that wms prefers to lock out many of his own
58     users than to have a few people write their own client. I didn't really
59     expect that from him, but instead expected real changes for the good,
60     as he is claiming all the time.</p>
61 pcg 1.23
62 pcg 1.25 <p>Well, that is just what he accouned earlier, so he just did what he
63 pcg 1.23 said...</p>
64    
65     <p>Anything I know about changes in 2.5.x are reflected in this
66 pcg 1.27 document already. You can log-in, chat, log-out, watch games, but you
67     cannot comment games nor play nor privately chat.</p>
68 pcg 1.23
69 pcg 1.1 <h2>Structure and conventions of this document and the protocol</h2>
70    
71     <p>"Send" means messages send from the client to the server, while
72     "received" means messages send by the server to the client.</p>
73    
74 pcg 1.4 <p>Everything on the wire is in little-endian format (what a shame).</p>
75 pcg 1.1
76 pcg 1.4 <p>Primitive types are mostly integers (signed
77     "<code>I</code>&lt;bits&gt;", unsigned "<code>U</code>&lt;bits&gt;"),
78     ascii strings ("<code>username</code>"), or zero-terminated
79     UCS2-Strings ("<code>STRING</code>"). Yes, I know java is supposed to
80     do UTF-16, but no implementation seems to care...</p>
81 pcg 1.1
82 pcg 1.17 <p>For the rest, go figure or bug me, <a href="mailto:pcg@goof.com">Marc Lehmann &lt;pcg@goof.com&gt;</a></p>
83 pcg 1.1
84     <h2>Stream and message structure.</h2>
85    
86 pcg 1.4 <p>After connecting to the server, a handshake byte is sent. It's
87     the major version number of the protocol the client expects to
88     receive. Version 3 and 4 are mostly the same, except that Version 4
89     clients expect server messages to be compressed, version 3 clients
90     not.</p>
91    
92     <p>The server sends back his protocol number, which is always 3 in
93     the current protocol. Most of the protocol variation is determined by
94     the server using the client version that is used in the initial login
95     message, not the initial handshake byte.</p>
96 pcg 1.1
97     <p>After the initial handshake, the client sends uncompressed
98     messages, while the server sends back a zlib-compressed
99     stream (<a href="http://rfc1950.x42.com/">rfc1950</a> and <a
100     href="http://rfc1950.x42.com/">rfc1951</a>).</p>
101    
102     <p>All messages have the same header:</p>
103    
104 pcg 1.28 <struct name="message_header">
105 pcg 1.3 <member name="_unknown" type="U16"/>
106     <member name="length" type="U16"/>
107 pcg 1.23
108 pcg 1.18 <p>The length is the length of the full message including the header.</p>
109 pcg 1.23
110 pcg 1.24 <p>Beginning with version 2.5.x, a number is xored into the low
111     byte of the length in <em>sent</em> packages only, as given by the
112     following recurrence: <code>rand[0] = 0; rand[i+1] = msg[i].length
113     + (rand[i] * 0x04c2af9b + 0xfffffffb); xorbyte = rand &gt;&gt;
114     24</code>, all in 32 bit unsigned iso-c arithmetic.</p>
115 pcg 1.23
116 pcg 1.3 <member name="type" type="U16"/>
117 pcg 1.18 <p>If the type is &gt;= 0x4000 this is a message for a specific channel. The channel
118     number is always the next U16.</p>
119 pcg 1.24
120     <p>Beginning with version 2.5.x, a number is <em>added</em> on <em>received</em>
121     messages only. The algorithm is as follows:
122    
123     <pre>
124     msglen &lt; 44: type = typefield
125     msglen &gt; 44: type = (typefield + rand[i]) % 0x10000
126     rand[0] = 0
127     rand[i+1] = username[type % length username] + rand[i] * (type - 0x6cdd)
128     where username is the user name of the logged-in user. coooool.
129     </pre>
130     </p>
131    
132 pcg 1.3 </struct>
133    
134     <h2>Primitive types used in the protocol.</h2>
135    
136 pcg 1.9 <p>Apart from the basic types, I need to define some extra types to
137     deal with fixed-point values (based on integer types) or fixed-length
138     strings (either 7-bit-ascii or more limited (<code>A</code>), or UCS-2
139     based (<code>S</code>)).</p>
140 pcg 1.3
141 pcg 1.23 <type name="username" type="A" length="10"/>
142 pcg 1.9
143     <p>The basic user or login name, used throughout the protocol
144     as a handle to the user.</p>
145    
146 pcg 1.3 <type name="roomname" type="S" length="25"/><!-- argh, how horribly broken -->
147 pcg 1.9
148     <p>Many strings in the protocol are fixed-width for no good reason
149 pcg 1.18 (maybe this is one reason for using compression in newer versions, as
150 pcg 1.9 the packets itself are wasting lots of space.</p>
151    
152 pcg 1.16 <type name="realname" type="S" length="50"/>
153     <type name="email" type="S" length="70"/>
154     <type name="userinfo" type="S" length="1000"/>
155     <type name="url" type="A" length="100"/>
156    
157     <p>Used in user_record.</p>
158    
159 pcg 1.3 <type name="locale" type="A" length="5"/>
160 pcg 1.9
161     <p>A kind of locale specifier. It seems the general format seems to be
162     lowercase language, underscore, uppercase location, e.g. en_US. More
163     fancy specifications don't fit.</p>
164    
165 pcg 1.3 <type name="flag" type="U8" multiplier="1"/>
166 pcg 1.9
167     <p>Just a simple boolean value. 0 means false, and 1 generally true,
168     but I suggest ccepting != 0 as true.</p>
169    
170 pcg 1.6 <type name="komi16" type="I16" multiplier="2"/>
171     <type name="komi32" type="I32" multiplier="2"/>
172 pcg 1.20 <type name="komi324" type="I32" multiplier="4"/>
173 pcg 1.9
174     <p>Komi values are multiplied by 2 to make them integer in the
175 pcg 1.20 protocol. Well, *most* of the time at least...</p>
176 pcg 1.9
177 pcg 1.3 <type name="result" type="I32" multiplier="2"/>
178 pcg 1.9
179 pcg 1.15 <p>The game result is also multiplied by two to give it higher
180     resolution. There are also special values for wins by time etc., either
181     in result or in the score* types, or both :)</p>
182 pcg 1.9
183 pcg 1.13 <type name="score16" type="I16" multiplier="4"/>
184     <type name="score32" type="I32" multiplier="4"/>
185 pcg 1.27 <type name="score1000" type="I32" multiplier="1000"/>
186 pcg 1.9
187     <p>A score value (used for displaying the score at the end of a game)
188 pcg 1.15 are multiplied by four for a change (the 0.25 resolution is not
189     used). In game structures it is encoded by dividing by two, though, so
190 pcg 1.27 watch out! And in some others, it's encoded by multiplying by 1000...
191     yuck!</p>
192 pcg 1.9
193 pcg 1.7 <type name="time" type="U32" multiplier="1000"/>
194 pcg 1.1
195 pcg 1.9 <p>Time values are multiplied by 1000, giving them millisecond
196     accuracy.</p>
197    
198 pcg 1.16 <type name="timestamp" type="U64" multiplier="1000"/>
199    
200     <p>64 bit timeval, milliseconds since posix epoch, e.g. <code>my
201     ($year, $month, $day) = (gmtime $date * 0.001)[5,4,3];</code></p>
202    
203 pcg 1.17 <type name="password" type="U64"/>
204    
205     <p>Password is a number calculated as follows (VERY insecure, basically
206     plaintext!): <code>password = 0; for char in characters do password ←
207     password * 1055 + ascii_code (char)</code></p>
208    
209 pcg 1.2 <h2>Constants, enumeration and set types used in the protocol.</h2>
210 pcg 1.1
211     <p>Baaah... not yet.</p>
212    
213 pcg 1.3 <h2>Structs used in send &amp; receive messages</h2>
214 pcg 1.1
215 pcg 1.3 <struct name="user" class="KGS::User">
216 pcg 1.9
217 pcg 1.18 <p>Everywhere a user + flags is required, even used in some places
218 pcg 1.9 where only a username is required. I see no general rule on when a
219 pcg 1.18 complete user and when a partial user is required.</p>
220 pcg 1.9
221 pcg 1.3 <member name="name" type="username"/>
222     <member name="flags" type="U32" default="1"/>
223     </struct>
224 pcg 1.1
225 pcg 1.6 <struct name="rules" class="KGS::Rules">
226 pcg 1.9
227 pcg 1.18 <p>This structure is used for challanges as well as in the special
228     TREE "subprotocol". It tightly encodes the game parameters.</p>
229 pcg 1.9
230 pcg 1.6 <member name="ruleset" type="U8"/>
231     <member name="size" type="U8"/>
232     <member name="handicap" type="U8"/>
233     <member name="komi" type="komi16"/>
234     <member name="timesys" type="U8"/>
235     <member name="time" type="U32"/>
236     <member name="interval" type="U32"/>
237     byo-yomi time / canadian time
238     <member name="count" type="U16"/>
239     periods / moves
240     </struct>
241    
242 pcg 1.3 <h2>Structs used in send messages</h2>
243 pcg 1.1
244 pcg 1.18 <h2>Send messages</h2>
245    
246 pcg 1.28 <message type="0000" name="login" dir="send">
247 pcg 1.9
248 pcg 1.18 <p>Sent to login, usually the first message sent. The password needs to be set when the
249 pcg 1.9 guest flag is true.
250 pcg 1.18 Possible replies: <ref reply="login"/>. Followed by: <ref reply="timewarning_default"/> <ref reply="chal_defaults"/>
251     </p>
252 pcg 1.9
253 pcg 1.3 <member name="ver_major" type="U32" default="2"/>
254 pcg 1.23 <member name="ver_minor" type="U32" default="5"/>
255     <member name="ver_micro" type="U32" default="1"/>
256 pcg 1.3 <member name="name" type="username"/>
257 pcg 1.17 <member name="password" type="password" default="0"/>
258 pcg 1.3 <member name="guest" type="flag" default="1"/>
259     <member name="_unknown3" type="U16" default="0"/>
260     <member name="locale" type="locale" default='"en_US"'/>
261     <member name="clientver" type="DATA" default='"1.4.1_01:Swing app:Sun Microsystems Inc."'/>
262 pcg 1.4 The "default" is the java vm version, not exactly he client version. However,
263 pcg 1.18 you should always send a text like "Jonathan's C client bersion 0.6" or somesuch,
264 pcg 1.4 so the server can, if necessary, block broken clients or client versions.
265 pcg 1.1 </message>
266    
267 pcg 1.28 <message type="0007" name="req_userinfo" dir="send">
268 pcg 1.18 <p>Request info about a certain user. Possible reply: <ref reply="userinfo"/></p>
269 pcg 1.17 <member name="name" type="username"/>
270     </message>
271    
272 pcg 1.28 <message type="0007" name="update_userinfo" dir="send">
273 pcg 1.18 <p>Update user info. Message structure is very similar
274     to <ref ref="userinfo"/>.</p>
275 pcg 1.17 <member name="setpass" type="flag"/>
276     Should the password be updated?
277     <member name="password" type="password" default="0"/>
278     <member name="realname" type="realname"/>
279     <member name="email" type="email"/>
280     <member name="info" type="userinfo"/>
281     <member name="homepage" type="url"/>
282     <member name="_unused" type="U64" default="0"/>
283     <member name="_unused" type="U64" default="0"/>
284     </message>
285    
286 pcg 1.28 <message type="0014" name="req_stats" dir="send">
287 pcg 1.18 <p>Request server statistics. Replied with <ref reply="stats"/></p>
288 pcg 1.19 </message>
289    
290 pcg 1.28 <message type="001d" name="ping" dir="send">
291 pcg 1.19 <p>Wild guess, I send it in <ref ref="idle_warn"/>.</p>
292 pcg 1.1 </message>
293    
294 pcg 1.28 <message type="001e" name="req_usergraph" dir="send">
295 pcg 1.18 <p>Request user graph data, replied with <ref reply="usergraph"/>.</p>
296 pcg 1.17 <member name="name" type="username"/>
297     </message>
298    
299 pcg 1.28 <message type="001f" name="fetch_memos" dir="send">
300 pcg 1.18 <p>Unclear. Fetch all outstanding memos? Replied with <ref reply="memo"/></p>
301 pcg 1.17 </message>
302    
303 pcg 1.28 <message type="0021" name="req_pic" dir="send">
304 pcg 1.18 <p>Request a user picture from the server. Results in a <ref reply="userpic"/>
305     or a timeout.</p>
306 pcg 1.3 <member name="name" type="username"/>
307 pcg 1.1 </message>
308    
309 pcg 1.28 <message type="0021" name="upload_pic" dir="send">
310 pcg 1.1 Same code as pic_req, but with an additional data section that
311 pcg 1.4 must contain a JPEG image that is &lt;=7KB. It must have 141×200 pixels.
312 pcg 1.3 <member name="name" type="username"/>
313 pcg 1.1 <member name="data" type="DATA"/>
314     </message>
315    
316 pcg 1.28 <message type="0100" name="gnotice" dir="send">
317 pcg 1.18 <p>Send a global message. Maybe. Never tried, for obvious reasons :/. Results
318     in a <ref reply="gnotice"/> sent to all users.</p>
319 pcg 1.1 <member name="notice" type="STRING"/>
320     </message>
321    
322 pcg 1.28 <message type="0318" name="list_rooms" dir="send">
323 pcg 1.18 <p>List the rooms in a specific group/category. Results in a <ref reply="upd_rooms"/> message.</p>
324 pcg 1.3 <member name="group" type="U8"/>
325 pcg 1.1 </message>
326    
327 pcg 1.28 <message type="031a" name="new_room" dir="send">
328 pcg 1.1 Create a new room. Not verified.
329 pcg 1.3 <member name="name" type="username"/>
330     <member name="i1" type="U32" default="0"/>
331     <member name="b1" type="U8" default="0"/>
332     <member name="b2" type="U8" default="255"/>
333     <member name="b3" type="U8" default="255"/>
334     <member name="group" type="U8" default="1"/>
335 pcg 1.1 <member name="name" type="STRING"/>
336     <member name="description" type="STRING"/>
337 pcg 1.3 <member name="flags" type="U8"/>
338 pcg 1.1 0x10 .. private room etc.. see code
339     </message>
340    
341 pcg 1.28 <message type="0413" name="req_game_record" dir="send">
342 pcg 1.18 <p>Requests part of the users game record to be sent. Results in a <ref reply="game_record"/> or maybe a timeout.</p>
343 pcg 1.16 <member name="name" type="username"/>
344     <member name="timestamp" type="timestamp"/>
345     If zero, start at the newest games, else only send games
346     before the given timestap.
347     </message>
348    
349 pcg 1.28 <message type="4300" name="join_room" dir="send">
350 pcg 1.18 <p>Joins the given room. <ref reply="join_room"/> messages for yourself
351 pcg 1.9 and all users in that room, as well as the initial gamelist, are
352 pcg 1.18 send if the room exists. If not, timeout...</p>
353 pcg 1.3 <member name="channel" type="U16"/>
354 pcg 1.1 <member name="user" type="user"/>
355     </message>
356    
357 pcg 1.28 <message type="4301" name="msg_room" dir="send">
358 pcg 1.9 Send a message to the room.
359 pcg 1.3 <member name="channel" type="U16"/>
360     <member name="name" type="username"/>
361 pcg 1.9 Must be the login-name of the user.
362 pcg 1.1 <member name="message" type="STRING"/>
363     </message>
364    
365 pcg 1.28 <message type="4302" name="part_room" dir="send">
366 pcg 1.9 Remove yourself (or maybe others as admin) from a room.
367 pcg 1.3 <member name="channel" type="U16"/>
368     <member name="name" type="username"/>
369 pcg 1.1 </message>
370    
371 pcg 1.28 <message type="4305" name="new_game" dir="send">
372 pcg 1.17 Unclear. Start a new game.
373 pcg 1.3 <member name="channel" type="U16"/>
374     <member name="id" type="U16"/>
375     <member name="gametype" type="U32"/>
376 pcg 1.1 <member name="rules" type="rules"/>
377     <member name="notes" type="STRING"/>
378     </message>
379    
380 pcg 1.28 <message type="430b" name="req_games" dir="send">
381 pcg 1.9 Request to update room game list (send this once per minute to get
382     updated). Results in upd_games messages.
383 pcg 1.3 <member name="channel" type="U16"/>
384 pcg 1.1 </message>
385    
386 pcg 1.28 <message type="4319" name="req_desc" dir="send">
387 pcg 1.1 Request room description.
388 pcg 1.3 <member name="channel" type="U16"/>
389 pcg 1.1 </message>
390    
391 pcg 1.28 <message type="4400" name="send_chal" dir="send">
392 pcg 1.9 Unclear.
393 pcg 1.3 <member name="channel" type="U16"/>
394     <member name="black" type="username"/>
395     <member name="white" type="username"/>
396 pcg 1.1 More following... TREE or challenge.
397     </message>
398    
399 pcg 1.28 <message type="4403" name="join_game" dir="send">
400 pcg 1.9 Join a game. See join_room.
401 pcg 1.5 <member name="channel" type="U16"/>
402 pcg 1.1 <member name="user" type="user"/>
403     </message>
404    
405 pcg 1.28 <message type="4404" name="part_game" dir="send">
406 pcg 1.9 Leave (or kick as admin?) a certain user from a game.
407 pcg 1.3 <member name="channel" type="U16"/>
408     <member name="name" type="username"/>
409 pcg 1.1 </message>
410    
411 pcg 1.28 <message type="4406" name="upd_tree" dir="send">
412     Upload a partial game tree to the server. This is used to send moves
413     and even in-game comments to the server. For the comments, the
414     server prepends the username and rank.
415    
416 pcg 1.3 <member name="channel" type="U16"/>
417 pcg 1.1 <member name="tree" type="TREE"/>
418     </message>
419    
420 pcg 1.28 <message type="4408" name="get_tree" dir="send">
421 pcg 1.9 Request the game tree starting at a given node. This is used
422     when the server only sends a partial tree (with end code "more").
423 pcg 1.3 <member name="channel" type="U16"/>
424     <member name="node" type="U32"/>
425 pcg 1.1 </message>
426    
427 pcg 1.28 <message type="440c" name="claim_win" dir="send">
428 pcg 1.9 Unclear.
429 pcg 1.3 <member name="channel" type="U16"/>
430     <member name="_byte" type="U8 "/>
431 pcg 1.1 Player colour maybe? Unclear.
432     </message>
433    
434 pcg 1.28 <message type="440d" name="add_time" dir="send">
435 pcg 1.9 Not checked.
436    
437 pcg 1.3 <member name="channel" type="U16"/>
438     <member name="time" type="U32"/>
439     <member name="player" type="U8"/>
440 pcg 1.1 </message>
441    
442 pcg 1.28 <message type="440f" name="grant_undo" dir="send">
443 pcg 1.9 Can be send after a req_undo message was received to grant the undo.
444 pcg 1.3 <member name="channel" type="U16"/>
445 pcg 1.1 </message>
446    
447 pcg 1.28 <message type="4410" name="resign_game" dir="send">
448 pcg 1.9 Resign the game.
449 pcg 1.3 <member name="channel" type="U16"/>
450     <member name="player" type="U8"/>
451 pcg 1.1 </message>
452    
453 pcg 1.28 <message type="441a" name="set_teacher" dir="send">
454 pcg 1.9 Change the teacher to somebody else (or possibly yourself == take it).
455 pcg 1.3 <member name="channel" type="U16"/>
456     <member name="name" type="username"/>
457 pcg 1.1 </message>
458    
459 pcg 1.28 <message type="4422" name="add_user" dir="send">
460 pcg 1.9 Unclear. Maybe allow users to talk? No idea, really.
461    
462 pcg 1.3 <member name="channel" type="U16"/>
463     <member name="othername" type="username"/>
464     <member name="name" type="username"/>; # gives user access to the game (to what? ;)
465 pcg 1.1 </message>
466    
467 pcg 1.28 <message type="4423" name="set_privacy" dir="send">
468 pcg 1.9 Probably sets the "quiet" flag. Not checked.
469 pcg 1.3 <member name="channel" type="U16"/>
470     <member name="private" type="U8"/>
471 pcg 1.1 </message>
472    
473 pcg 1.28 <message type="4429" name="reject_chal" dir="send">
474 pcg 1.9 Reject a challenge from a given user. Not checked.
475    
476 pcg 1.3 <member name="channel" type="U16"/>
477     <member name="name" type="username"/>
478 pcg 1.1 </message>
479    
480 pcg 1.28 <message type="4433" name="req_result" dir="send">
481 pcg 1.9 I forgot.
482    
483 pcg 1.3 <member name="channel" type="U16"/>
484 pcg 1.1 </message>
485    
486 pcg 1.3 <h2>Structs mainly used in receive messages</h2>
487 pcg 1.1
488 pcg 1.3 <struct name="challenge_defaults">
489 pcg 1.9 Send soon after log-in to set the defaults for game challenges.
490 pcg 1.3 <member name="gametype" type="U32"/>
491     <member name="size" type="U32"/>
492     <member name="timesys" type="U32"/>
493     <member name="time" type="U32"/>
494     <member name="byo_time" type="U32"/>
495     <member name="byo_periods" type="U32"/>
496     <member name="can_time" type="U32"/>
497     <member name="can_stones" type="U32"/>
498     </struct>
499    
500     <struct name="challenge" class="KGS::Challenge">
501 pcg 1.9 A challenge.
502    
503 pcg 1.1 <member name="user1" type="user"/>
504     <member name="user2" type="user"/>
505 pcg 1.3 <member name="gametype" type="U32"/>
506 pcg 1.1 <member name="rules" type="rules"/>
507     Maybe the rules" are in TREE format. I forgot.
508 pcg 1.3 </struct>
509 pcg 1.1
510 pcg 1.3 <struct name="game" class="KGS::Game">
511 pcg 1.9 Basic information about a game. Used in rooms for the gamelist and
512     in games to detect when a game is saved, changed type (e.g. R => D)
513     etc.
514    
515 pcg 1.3 <member name="channel" type="U16"/>
516 pcg 1.26 <member name="type" type="U8"/>
517 pcg 1.1 <member name="user1" type="user"/>
518     White
519     <member name="user2" type="user"/>
520     Black
521     <member name="user3" type="user"/>
522     Owner
523 pcg 1.26 <member name="size" type="U8"/>
524     <member name="handicap" type="I8"/>
525 pcg 1.1 &lt; 0 not fully setup
526 pcg 1.26 <member name="komi" type="komi16"/>
527 pcg 1.15 <member name="moves" type="I16"/>
528 pcg 1.14 This field reflects either the movenum or the score, sorry, not even guards help, as
529 pcg 1.15 the flags to determine that are _after_ the field. Arg. Divide by two to get the actual
530 pcg 1.27 score (NOT score16!) (arg²).
531 pcg 1.3 <member name="flags" type="U16"/>
532     <member name="observers" type="U32"/>
533     <member name="saved" type="flag"/>
534     <member name="notes" type="STRING" guard-member="handicap" guard-cond="&lt; 0"/>
535     </struct>
536    
537     <struct name="room_obs">
538 pcg 1.9 Obsolete.
539    
540 pcg 1.3 <member name="name" type="roomname"/>
541     <member name="channel" type="U16"/>
542     <member name="flags" type="U32"/>
543 pcg 1.4 <member name="users" type="U32"/>
544 pcg 1.3 </struct>
545    
546     <struct name="room" class="KGS::Room">
547     <member name="channel" type="U16"/>
548     <member name="flags" type="U8"/>
549     <member name="group" type="U8"/>
550     <member name="users" type="U16"/>
551     <member name="games" type="U16"/>
552 pcg 1.4 <member name="name" type="STRING"/>
553 pcg 1.3 </struct>
554 pcg 1.1
555 pcg 1.12 <struct name="scorevalues" class="KGS::Score">
556 pcg 1.13 <member name="score" type="score32"/>
557 pcg 1.3 <member name="territory" type="U32"/>
558     <member name="captures" type="U32"/>
559     <member name="i3" type="U32"/>
560     <member name="f2" type="U32"/>
561 pcg 1.20 <member name="komi" type="komi324"/>
562 pcg 1.4 <member name="i4" type="U32"/>
563 pcg 1.3 Apparently the i3, f2, i4 are zero.
564     </struct>
565 pcg 1.1
566 pcg 1.16 <struct name="game_record" class="KGS::GameRecord">
567 pcg 1.18 <p>A single game record entry, as seen in <ref ref="userinfo"/>.</p>
568 pcg 1.16
569     <member name="timestamp" type="timestamp"/>
570     Time this game was played.
571     <member name="flags" type="U8"/>
572     High four bits are handicap, low four bits are gametype (encoded strangely? unclear).
573     <member name="user1" type="user"/>
574     White, flags contain low 8 bits of revision (bits 16-23).
575     <member name="user2" type="user"/>
576     Black, flags contain high 8 bits of revision (bits 16-23).
577     <member name="user3" type="user"/>
578     Owner (or empty)
579     <member name="komi" type="komi16"/>
580     <member name="score" type="score16"/>
581     <member name="status" type="U8"/>
582     0x80 inprogress
583     </struct>
584    
585 pcg 1.1 <h2>Receive messages</h2>
586    
587 pcg 1.28 <message type="0001" name="login" dir="recv">
588 pcg 1.3 <member name="result" type="CONSTANT" default='"login ok"'/>
589 pcg 1.1 <member name="success" type="CONSTANT" default="1"/>
590     </message>
591    
592 pcg 1.28 <message type="0002" name="login" dir="recv">
593 pcg 1.3 <member name="result" type="CONSTANT" default='"guest login ok"'/>
594 pcg 1.1 <member name="success" type="CONSTANT" default="1"/>
595     </message>
596    
597 pcg 1.28 <message type="0003" name="login" dir="recv">
598 pcg 1.3 <member name="result" type="CONSTANT" default='"login error 3"'/>
599 pcg 1.1 ** maybe more following? **
600     </message>
601    
602 pcg 1.28 <message type="0004" name="login" dir="recv">
603 pcg 1.3 <member name="result" type="CONSTANT" default='"wrong password"'/>
604 pcg 1.1 ** maybe more following? **
605     </message>
606    
607 pcg 1.28 <message type="0005" name="login" dir="recv">
608 pcg 1.3 <member name="result" type="CONSTANT" default='"user unknown"'/>
609 pcg 1.1 ** maybe more following? **
610     </message>
611    
612 pcg 1.28 <message type="0006" name="login" dir="recv">
613 pcg 1.3 <member name="result" type="CONSTANT" default='"user exists"'/>
614 pcg 1.1 ** maybe more following? **
615     </message>
616    
617 pcg 1.28 <message type="0008" name="userinfo" dir="recv">
618 pcg 1.17 User info.
619 pcg 1.16 <member name="user" type="user"/>
620 pcg 1.17 <member name="_unused" type="U64"/>
621 pcg 1.16 <member name="realname" type="realname"/>
622     <member name="email" type="email"/>
623     <member name="info" type="userinfo"/>
624     <member name="homepage" type="url"/>
625     <member name="regdate" type="timestamp"/>
626     When the user registered (0 == never registered).
627     <member name="lastlogin" type="timestamp"/>
628     When the user logged in for the last time.
629     <!-- maybe more? -->
630     </message>
631    
632 pcg 1.28 <message type="0018" name="login" dir="recv">
633 pcg 1.3 <member name="result" type="CONSTANT" default='"login error 18"'/>
634 pcg 1.1 ** maybe more following? **
635     </message>
636    
637 pcg 1.28 <message type="0022" name="login" dir="recv">
638 pcg 1.22 I was blocked sooo many times for developing this client that it was
639     easy to figure out. The KGS admins sure need no extra nazi training
640     :(
641     <member name="reason" type="STRING"/>
642 pcg 1.3 <member name="result" type="CONSTANT" default='"user or ip blocked"'/>
643 pcg 1.1 </message>
644    
645 pcg 1.28 <message type="0013" name="msg_chat" dir="recv">
646 pcg 1.3 <member name="user1" type="username"/>
647     <member name="user2" type="username"/>
648 pcg 1.1 <member name="message" type="STRING"/>
649     </message>
650    
651 pcg 1.28 <message type="0015" name="stats" dir="recv">
652 pcg 1.3 <member name="ver_major" type="U16"/>
653     <member name="ver_minor" type="U16"/>
654     <member name="ver_micro" type="U16"/>
655 pcg 1.16 <member name="boot_time" type="timestamp"/>
656 pcg 1.3 <member name="users_cur" type="U32"/>
657     <member name="users_max" type="U32"/>
658     <member name="users_lim" type="U32"/>
659     <member name="accts_cur" type="U32"/>
660     <member name="accts_max" type="U32"/>
661     <member name="unknown1" type="U32"/>
662     <member name="work_max" type="U32"/>
663     <member name="rooms_cur" type="U32"/>
664     <member name="rooms_max" type="U32"/>
665     <member name="rooms_lim" type="U32"/>
666     <member name="games_cur" type="U32"/>
667     <member name="games_max" type="U32"/>
668     <member name="games_lim" type="U32"/>
669     <member name="results_cur" type="U32"/>
670     <member name="results_max" type="U32"/>
671     <member name="unknown2" type="U32"/>
672     <member name="params_cur" type="U32"/>
673     <member name="params_max" type="U32"/>
674     <member name="bytes_in" type="U64"/>
675     <member name="packets_in" type="U64"/>
676     <member name="bytes_out" type="U64"/>
677 pcg 1.4 <member name="packets_out" type="U64"/>
678 pcg 1.1 </message>
679    
680 pcg 1.28 <message type="0016" name="idle_warn" dir="recv">
681 pcg 1.1 idle warning, autologout soon (10 minutes...)
682     </message>
683    
684 pcg 1.28 <message type="001b" name="timewarning_default" dir="recv">
685 pcg 1.1 WILD guess
686 pcg 1.3 <member name="channel" type="U16"/>
687     <member name="time" type="U16"/>
688 pcg 1.1 </message>
689    
690 pcg 1.28 <message type="001c" name="idle_err" dir="recv">
691 pcg 1.1 autologout
692     </message>
693    
694 pcg 1.28 <message type="001d" name="ping" dir="recv">
695 pcg 1.16 Sent by the server regularly, but not answering them
696     isn't valid. Strange form of keepalive?
697 pcg 1.1 </message>
698    
699 pcg 1.28 <message type="001e" name="usergraph" dir="recv">
700 pcg 1.17 User graph data.
701     <member name="data" type="I16" array="yes"/>
702     If empty, no graph is available. The unit seems to
703     be centi-kyu, with 1 dan == 0, 2 dan == 100, 1 kyu == -100.
704     There is probably one entry per day, the newest one last.
705     </message>
706    
707 pcg 1.28 <message type="001f" name="memo" dir="recv">
708 pcg 1.17 Unclear. "Leave Message"?
709     6 strings following.
710     <member name="s1" type="STRING"/>
711     <member name="s2" type="STRING"/>
712     <member name="s3" type="STRING"/>
713     <member name="s4" type="STRING"/>
714     <member name="s5" type="STRING"/>
715     <member name="s6" type="STRING"/>
716     </message>
717    
718 pcg 1.28 <message type="0021" name="userpic" dir="recv">
719 pcg 1.3 <member name="name" type="username"/>
720 pcg 1.1 Reply to pic_req, contains an image in jpeg format.
721     <member name="data" type="DATA"/>
722     </message>
723    
724 pcg 1.28 <message type="0100" name="gnotice" dir="recv">
725 pcg 1.1 global notice, sent to everybody
726     <member name="notice" type="STRING"/>
727     </message>
728    
729 pcg 1.28 <message type="0202" name="upd_user" dir="recv">
730 pcg 1.17 # maybe soe notify? Totally unclear.
731 pcg 1.16 # loc 0" type="chat(?) loc 1 => gameinfo?, loc 2 => game result (more data)
732     <member name="location" type="U32"/>
733     <member name="user" type="user"/>
734     <member name="lotsofinfo" type="DATA" guard-member="location" guard-cond="== 2"/>
735     </message>
736 pcg 1.1
737 pcg 1.28 <message type="0310" name="priv_room" dir="recv">
738 pcg 1.1 "permission denied" when joining a room
739     <member name="name" type="STRING"/>
740     </message>
741    
742 pcg 1.28 <message type="0318" name="upd_rooms" dir="recv">
743 pcg 1.1 <member name="rooms" type="room" array="yes"/>
744     </message>
745    
746 pcg 1.28 <message type="0411" name="chal_defaults" dir="recv">
747 pcg 1.16 <member name="channel" type="U16"/>
748     <member name="defaults" type="challenge_defaults"/>
749     </message>
750    
751 pcg 1.28 <message type="0412" name="rej_game" dir="send">
752 pcg 1.17 Unable to create challenge. The channel might be optional.
753     <member name="channel" type="U16"/>
754     </message>
755    
756 pcg 1.28 <message type="0414" name="game_record" dir="recv">
757 pcg 1.16 The users game record.
758     <member name="name" type="username"/>
759     <member name="more" type="flag"/>
760     Wether more games are available (must be requested manually)
761     <member name="games" type="game_record" array="yes"/>
762     </message>
763    
764 pcg 1.28 <message type="041c" name="upd_game2" dir="recv">
765 pcg 1.17 Unclear.
766 pcg 1.3 <member name="channel_junk" type="U16"/>
767 pcg 1.1 <member name="game" type="game"/>
768     </message>
769    
770     <h3>Room messages</h3>
771    
772     <p>Not all room messages are for rooms only, and rooms need to parse
773     not only these messages. Orthogonality, what for?</p>
774    
775 pcg 1.28 <message type="4300" name="join_room" dir="recv">
776 pcg 1.3 <member name="channel" type="U16"/>
777 pcg 1.1 <member name="users" type="user" array="yes"/>
778     </message>
779    
780 pcg 1.28 <message type="4301" name="msg_room" dir="recv">
781 pcg 1.3 <member name="channel" type="U16"/>
782     <member name="name" type="username"/>
783 pcg 1.1 <member name="message" type="STRING"/>
784     </message>
785    
786 pcg 1.28 <message type="4302" name="part_room" dir="recv">
787 pcg 1.3 <member name="channel" type="U16"/>
788 pcg 1.1 <member name="user" type="user"/>
789     </message>
790    
791 pcg 1.28 <message type="4303" name="del_room" dir="recv">
792 pcg 1.3 <member name="channel" type="U16"/>
793 pcg 1.1 </message>
794    
795 pcg 1.28 <message type="4304" name="upd_games" dir="recv">
796 pcg 1.3 <member name="channel" type="U16"/>
797 pcg 1.1 <member name="games" type="game" array="yes"/>
798     </message>
799    
800 pcg 1.28 <message type="4319" name="desc_room" dir="recv">
801 pcg 1.3 <member name="channel" type="U16"/>
802     <member name="owner" type="username"/>
803 pcg 1.1 <member name="description" type="STRING"/>
804     </message>
805 pcg 1.28
806 pcg 1.1 <h3>Game messages</h3>
807    
808 pcg 1.28 <message type="4400" name="upd_chal" dir="recv">
809 pcg 1.1 Unclear.
810 pcg 1.3 <member name="channel" type="U16"/>
811 pcg 1.1 <member name="challenge" type="challenge"/>
812     </message>
813    
814 pcg 1.28 <message type="4401" name="upd_game" dir="recv">
815 pcg 1.3 <member name="channel" type="U16"/>
816 pcg 1.1 <member name="game" type="game"/>
817     </message>
818    
819 pcg 1.28 <message type="4402" name="del_game" dir="recv">
820 pcg 1.3 <member name="channel" type="U16"/>
821 pcg 1.1 </message>
822    
823 pcg 1.28 <message type="4403" name="upd_observers" dir="recv">
824 pcg 1.3 <member name="channel" type="U16"/>
825 pcg 1.1 <member name="users" type="user" array="yes"/>
826     </message>
827    
828 pcg 1.28 <message type="4404" name="del_observer" dir="recv">
829 pcg 1.3 <member name="channel" type="U16"/>
830     <member name="name" type="username"/>
831 pcg 1.1 </message>
832    
833 pcg 1.28 <message type="4405" name="set_tree" dir="recv">
834 pcg 1.3 <member name="channel" type="U16"/>
835 pcg 1.1 <member name="tree" type="TREE"/>
836     </message>
837    
838 pcg 1.28 <message type="4406" name="upd_tree" dir="recv">
839 pcg 1.3 <member name="channel" type="U16"/>
840 pcg 1.1 <member name="tree" type="TREE"/>
841     </message>
842    
843 pcg 1.28 <message type="4409" name="superko" dir="recv">
844 pcg 1.1 Superko-warning.
845 pcg 1.3 <member name="channel" type="U16"/>
846 pcg 1.1 </message>
847    
848 pcg 1.28 <message type="440b" name="final_result" dir="recv">
849 pcg 1.3 <member name="channel" type="U16"/>
850 pcg 1.12 <member name="blackscore" type="scorevalues"/>
851     <member name="whitescore" type="scorevalues"/>
852 pcg 1.1 </message>
853    
854 pcg 1.28 <message type="440e" name="req_undo" dir="recv">
855 pcg 1.3 <member name="channel" type="U16"/>
856 pcg 1.1
857     </message>
858    
859 pcg 1.28 <message type="4410" name="resign_game" dir="recv">
860 pcg 1.3 <member name="channel" type="U16"/>
861     <member name="player" type="U8"/>
862 pcg 1.1 </message>
863    
864 pcg 1.28 <message type="441a" name="set_teacher" dir="recv">
865 pcg 1.3 <member name="channel" type="U16"/>
866     <member name="name" type="username"/>
867 pcg 1.1 </message>
868    
869 pcg 1.28 <message type="441d" name="owner_left" dir="recv">
870 pcg 1.1 Unclear.
871 pcg 1.3 <member name="channel" type="U16"/>
872 pcg 1.1 </message>
873    
874 pcg 1.28 <message type="441e" name="teacher_left" dir="recv">
875 pcg 1.1 Unclear.
876 pcg 1.3 <member name="channel" type="U16"/>
877 pcg 1.1 </message>
878    
879 pcg 1.28 <message type="4422" name="unknown4422" dir="recv">
880 pcg 1.1 change teacher? something to do with editing?
881 pcg 1.3 <member name="channel" type="U16"/>
882     <member name="name1" type="username"/>
883     <member name="name2" type="username"/>
884 pcg 1.27 </message>
885    
886 pcg 1.28 <message type="4428" name="add_tree" dir="recv">
887 pcg 1.27 <p>See <ref ref="set_tree"/>. In addition, flags the tree as being
888     uploaded completely.</p>
889     <member name="channel" type="U16"/>
890     <member name="tree" type="TREE"/>
891 pcg 1.1 </message>
892    
893 pcg 1.28 <message type="4433" name="req_result" dir="recv">
894 pcg 1.1 Unclear.
895 pcg 1.3 <member name="channel" type="U16"/>
896 pcg 1.1 # # recv_result(?)
897     </message>
898    
899 pcg 1.28 <message type="4434" name="unknown4434" dir="recv">
900 pcg 1.3 <member name="channel" type="U16"/>
901     <member name="b1" type="U8"/>
902 pcg 1.1 ?? !demonstration game??
903     </message>
904    
905     </body>
906     </html>
907