ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/kgsueme/doc/protocol.xml
Revision: 1.64
Committed: Sun May 30 06:40:18 2004 UTC (22 years, 4 months ago) by pcg
Content type: text/xml
Branch: MAIN
Changes since 1.63: +5 -7 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 pcg 1.37 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
6 pcg 1.1 <!--
7     Copyright (C) 2003 Marc Lehmannn &lt;pcg@goof.com&gt;
8    
9     You can redistribute and/or modify this document under the terms of
10     the GNU General Public License as published by the Free Software
11     Foundation; either version 2 of the License, or (at your option) any
12     later version.
13    
14     This document is distributed in the hope that it will be useful,
15     but WITHOUT ANY WARRANTY; without even the implied warranty of
16     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17     General Public License for more details.
18    
19     You should have received a copy of the GNU General Public License
20     along with this program; if not, write to the Free Software
21     Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
22     -->
23     </head>
24     <body>
25    
26 pcg 1.64 <h1>$Revision: 1.63 $</h1>
27 pcg 1.10
28 pcg 1.1 <h1>KGS Protocol Description</h1>
29    
30     <p>This XML document describes the KGS protocol. It is also used
31     to automatically generate the perl parser for all the messages and
32     structures in the protocol. Adapting it to other languages should be
33 pcg 1.33 almost trivial.</p>
34 pcg 1.10
35 pcg 1.37 <p><b>Please note that wms has told me that he will change the
36     protocol in response to my efforts. No problems with changing the
37     protocol for good, but he does this just to make it more difficult
38     to reverse-engineer it, since his changes are neither required, nor
39     useful (they just make the protocol less robust, without adding added
40     value). He doesn't even care that this locks out some users who cannot
41     upgrade (cgoban2 isn't available for their platform anymore). It hurts
42     to see such a waste of time and efforts that could have been used to
43     fix bugs or improve the client...</b></p>
44 pcg 1.1
45 pcg 1.4 <p>If you feel you need to update the visual appearance of this
46 pcg 1.11 document, feel free to look <tt>doc/doc2html.xsl</tt> and improve
47 pcg 1.4 it.</p>
48    
49 pcg 1.8 <p>The current version of this document can always be found at
50     <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
51     the HTML version of it can be found
52     <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>.
53 pcg 1.32 (update: sourceforge is weeks behind on their anonymous cvs servers so the above might be out-of-date. sorry.)</p>
54 pcg 1.23
55 pcg 1.1 <h2>Structure and conventions of this document and the protocol</h2>
56    
57 pcg 1.32 <p>"ORIGIN: CLIENT" means messages send from the client to the server,
58     while "ORIGIN: SERVER" means messages send by the server to the
59     client.</p>
60 pcg 1.1
61 pcg 1.4 <p>Everything on the wire is in little-endian format (what a shame).</p>
62 pcg 1.1
63 pcg 1.4 <p>Primitive types are mostly integers (signed
64     "<code>I</code>&lt;bits&gt;", unsigned "<code>U</code>&lt;bits&gt;"),
65 pcg 1.48 ascii strings ("<code>username</code>"), zero- or non-terminated
66     UCS2-Strings ("<code>ZSTRING</code>" or "<code>STRING</code>"). Yes,
67     I know java is supposed to do UTF-16, but no implementation seems to
68     care...</p>
69 pcg 1.1
70 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>
71 pcg 1.1
72     <h2>Stream and message structure.</h2>
73    
74 pcg 1.4 <p>After connecting to the server, a handshake byte is sent. It's
75     the major version number of the protocol the client expects to
76     receive. Version 3 and 4 are mostly the same, except that Version 4
77     clients expect server messages to be compressed, version 3 clients
78     not.</p>
79    
80     <p>The server sends back his protocol number, which is always 3 in
81     the current protocol. Most of the protocol variation is determined by
82     the server using the client version that is used in the initial login
83     message, not the initial handshake byte.</p>
84 pcg 1.1
85     <p>After the initial handshake, the client sends uncompressed
86     messages, while the server sends back a zlib-compressed
87     stream (<a href="http://rfc1950.x42.com/">rfc1950</a> and <a
88     href="http://rfc1950.x42.com/">rfc1951</a>).</p>
89    
90     <p>All messages have the same header:</p>
91    
92 pcg 1.28 <struct name="message_header">
93 pcg 1.3 <member name="_unknown" type="U16"/>
94     <member name="length" type="U16"/>
95 pcg 1.23
96 pcg 1.18 <p>The length is the length of the full message including the header.</p>
97 pcg 1.23
98 pcg 1.24 <p>Beginning with version 2.5.x, a number is xored into the low
99     byte of the length in <em>sent</em> packages only, as given by the
100     following recurrence: <code>rand[0] = 0; rand[i+1] = msg[i].length
101     + (rand[i] * 0x04c2af9b + 0xfffffffb); xorbyte = rand &gt;&gt;
102     24</code>, all in 32 bit unsigned iso-c arithmetic.</p>
103 pcg 1.23
104 pcg 1.3 <member name="type" type="U16"/>
105 pcg 1.18 <p>If the type is &gt;= 0x4000 this is a message for a specific channel. The channel
106     number is always the next U16.</p>
107 pcg 1.24
108     <p>Beginning with version 2.5.x, a number is <em>added</em> on <em>received</em>
109     messages only. The algorithm is as follows:
110    
111     <pre>
112     msglen &lt; 44: type = typefield
113     msglen &gt; 44: type = (typefield + rand[i]) % 0x10000
114     rand[0] = 0
115     rand[i+1] = username[type % length username] + rand[i] * (type - 0x6cdd)
116     where username is the user name of the logged-in user. coooool.
117     </pre>
118     </p>
119    
120 pcg 1.3 </struct>
121    
122     <h2>Primitive types used in the protocol.</h2>
123    
124 pcg 1.9 <p>Apart from the basic types, I need to define some extra types to
125     deal with fixed-point values (based on integer types) or fixed-length
126     strings (either 7-bit-ascii or more limited (<code>A</code>), or UCS-2
127     based (<code>S</code>)).</p>
128 pcg 1.3
129 pcg 1.23 <type name="username" type="A" length="10"/>
130 pcg 1.9
131     <p>The basic user or login name, used throughout the protocol
132     as a handle to the user.</p>
133    
134 pcg 1.3 <type name="roomname" type="S" length="25"/><!-- argh, how horribly broken -->
135 pcg 1.9
136     <p>Many strings in the protocol are fixed-width for no good reason
137 pcg 1.18 (maybe this is one reason for using compression in newer versions, as
138 pcg 1.9 the packets itself are wasting lots of space.</p>
139    
140 pcg 1.16 <type name="realname" type="S" length="50"/>
141     <type name="email" type="S" length="70"/>
142     <type name="userinfo" type="S" length="1000"/>
143     <type name="url" type="A" length="100"/>
144    
145     <p>Used in user_record.</p>
146    
147 pcg 1.3 <type name="locale" type="A" length="5"/>
148 pcg 1.9
149     <p>A kind of locale specifier. It seems the general format seems to be
150     lowercase language, underscore, uppercase location, e.g. en_US. More
151     fancy specifications don't fit.</p>
152    
153 pcg 1.3 <type name="flag" type="U8" multiplier="1"/>
154 pcg 1.9
155     <p>Just a simple boolean value. 0 means false, and 1 generally true,
156 pcg 1.40 but I suggest accepting != 0 as true.</p>
157 pcg 1.9
158 pcg 1.6 <type name="komi16" type="I16" multiplier="2"/>
159     <type name="komi32" type="I32" multiplier="2"/>
160 pcg 1.20 <type name="komi324" type="I32" multiplier="4"/>
161 pcg 1.9
162     <p>Komi values are multiplied by 2 to make them integer in the
163 pcg 1.20 protocol. Well, *most* of the time at least...</p>
164 pcg 1.9
165 pcg 1.3 <type name="result" type="I32" multiplier="2"/>
166 pcg 1.9
167 pcg 1.15 <p>The game result is also multiplied by two to give it higher
168     resolution. There are also special values for wins by time etc., either
169     in result or in the score* types, or both :)</p>
170 pcg 1.9
171 pcg 1.13 <type name="score16" type="I16" multiplier="4"/>
172     <type name="score32" type="I32" multiplier="4"/>
173 pcg 1.27 <type name="score1000" type="I32" multiplier="1000"/>
174 pcg 1.9
175     <p>A score value (used for displaying the score at the end of a game)
176 pcg 1.15 are multiplied by four for a change (the 0.25 resolution is not
177     used). In game structures it is encoded by dividing by two, though, so
178 pcg 1.27 watch out! And in some others, it's encoded by multiplying by 1000...
179     yuck!</p>
180 pcg 1.9
181 pcg 1.7 <type name="time" type="U32" multiplier="1000"/>
182 pcg 1.1
183 pcg 1.9 <p>Time values are multiplied by 1000, giving them millisecond
184     accuracy.</p>
185    
186 pcg 1.16 <type name="timestamp" type="U64" multiplier="1000"/>
187    
188     <p>64 bit timeval, milliseconds since posix epoch, e.g. <code>my
189     ($year, $month, $day) = (gmtime $date * 0.001)[5,4,3];</code></p>
190    
191 pcg 1.17 <type name="password" type="U64"/>
192    
193     <p>Password is a number calculated as follows (VERY insecure, basically
194     plaintext!): <code>password = 0; for char in characters do password ←
195     password * 1055 + ascii_code (char)</code></p>
196    
197 pcg 1.60 <type name="CLIENTID16" type="U16" multiplier="1"/>
198     <type name="CLIENTID8" type="U8" multiplier="1"/>
199 pcg 1.58
200     <p>An id chosen by the client, usually starting at one, to identify
201     some handshakes initiated by the client, such as new games or memos.</p>
202    
203 pcg 1.37 <h2>Enumeration and set types used in the protocol.</h2>
204 pcg 1.1
205 pcg 1.37 <enum name="GAMETYPE">
206     <member name="DEMONSTRATION" value="0"/>
207 pcg 1.54 <member name="EDITING" value="1"/>
208     <member name="TEACHING" value="2"/>
209     <member name="SIMUL" value="3"/>
210     <member name="FREE" value="4"/>
211     <member name="RATED" value="5"/>
212     <member name="PRIVATE" value="128"/>
213     <p>PRIVATE is ored onto DEMONSTRATION or TEACHING</p>
214 pcg 1.37 </enum>
215    
216     <set name="GAMEFLAG">
217     <member name="SCORED" value="1"/>
218     <member name="ADJOURNED" value="2"/>
219     <member name="UPLOADED" value="4"/>
220     </set>
221    
222 pcg 1.40 <set name="ROOMFLAG">
223     <member name="ADMIN" value="0x01"/>
224     <p>Admins only(?)</p>
225     <member name="DEFAULT" value="0x04"/>
226     <p>Seems to be set on the english room. Or maybe not.</p>
227     <member name="PRIVATE" value="0x10"/>
228     <p>This room is private.</p>
229     </set>
230    
231     <set name="GAMESTATUS">
232     <member name="INPLAY" value="0x80"/>
233     </set>
234    
235 pcg 1.37 <enum name="SCORE">
236     <p>Special score values, in addition to numerical scores. Some are also used with their
237     negative value.</p>
238    
239     <member name="TIMEOUT" value="16384 / 4"/>
240     Also used negatively to score for white instead of black.
241    
242     <member name="RESIGN" value="16385 / 4"/>
243     Also used negatively to score for white instead of black.
244    
245     <member name="FORFEIT" value=" 0 / 4"/>
246     Also used negatively to score for white instead of black.
247    
248     <member name="JIGO" value="16386 / 4"/>
249    
250     <member name="NO_RESULT" value="16386 / 4"/>
251     <member name="ADJOURNED" value="16387 / 4"/>
252     <member name="UNKNOWN" value="16389 / 4"/>
253     </enum>
254    
255     <enum name="RULESET">
256     <member name="JAPANESE" value="0"/>
257     <member name="CHINESE " value="1"/>
258     <member name="AGA" value="2"/>
259     <member name="NEW_ZEALAND" value="3"/>
260     </enum>
261    
262     <enum name="TIMESYS">
263     <member name="NONE" value="0"/>
264     <member name="ABSOLUTE" value="1"/>
265     <member name="BYO_YOMI" value="2"/>
266     <member name="CANADIAN" value="3"/>
267     </enum>
268    
269     <enum name="COLOUR">
270     <p>Convinience constants used in several places.</p>
271     <member name="BLACK" value="0"/>
272     <member name="WHITE" value="1"/>
273 pcg 1.63 <member name="NONE" value="2"/>
274     <p>Sometimes used to mark absence of marks, or no player or etc...</p>
275 pcg 1.37 </enum>
276 pcg 1.1
277 pcg 1.3 <h2>Structs used in send &amp; receive messages</h2>
278 pcg 1.1
279 pcg 1.3 <struct name="user" class="KGS::User">
280 pcg 1.9
281 pcg 1.40 <p>Almost everywhere a user + flags is required, even used in some places
282 pcg 1.9 where only a username is required. I see no general rule on when a
283 pcg 1.18 complete user and when a partial user is required.</p>
284 pcg 1.9
285 pcg 1.3 <member name="name" type="username"/>
286 pcg 1.37 <member name="flags" type="U32" value="1"/>
287 pcg 1.3 </struct>
288 pcg 1.1
289 pcg 1.6 <struct name="rules" class="KGS::Rules">
290 pcg 1.9
291 pcg 1.48 <p>This structure is used for challenges as well as in the special
292 pcg 1.18 TREE "subprotocol". It tightly encodes the game parameters.</p>
293 pcg 1.9
294 pcg 1.6 <member name="ruleset" type="U8"/>
295     <member name="size" type="U8"/>
296     <member name="handicap" type="U8"/>
297     <member name="komi" type="komi16"/>
298     <member name="timesys" type="U8"/>
299     <member name="time" type="U32"/>
300     <member name="interval" type="U32"/>
301     byo-yomi time / canadian time
302     <member name="count" type="U16"/>
303     periods / moves
304     </struct>
305    
306 pcg 1.32 <h2>Structs used in messages from the client</h2>
307 pcg 1.1
308 pcg 1.32 <h2>Client-generated messages</h2>
309 pcg 1.18
310 pcg 1.31 <message type="0000" name="login" src="client">
311 pcg 1.9
312 pcg 1.18 <p>Sent to login, usually the first message sent. The password needs to be set when the
313 pcg 1.9 guest flag is true.
314 pcg 1.18 Possible replies: <ref reply="login"/>. Followed by: <ref reply="timewarning_default"/> <ref reply="chal_defaults"/>
315     </p>
316 pcg 1.9
317 pcg 1.37 <member name="ver_major" type="U32" value="2"/>
318 pcg 1.53 <member name="ver_minor" type="U32" value="6"/>
319 pcg 1.55 <member name="ver_micro" type="U32" value="1"/>
320 pcg 1.37 <member name="name" type="username"/>
321     <member name="password" type="password" value="0"/>
322     <member name="guest" type="flag" value="1"/>
323     <member name="_unknown3" type="U16" value="0"/>
324     <member name="locale" type="locale" value='"en_US"'/>
325 pcg 1.49 <member name="clientver" type="DATA" value='"1.4.2_03:Swing app:Sun Microsystems Inc."'/>
326 pcg 1.4 The "default" is the java vm version, not exactly he client version. However,
327 pcg 1.49 you should always send a text like "Jonathan's C client version 0.6" or somesuch,
328 pcg 1.4 so the server can, if necessary, block broken clients or client versions.
329 pcg 1.1 </message>
330    
331 pcg 1.31 <message type="0007" name="req_userinfo" src="client">
332 pcg 1.18 <p>Request info about a certain user. Possible reply: <ref reply="userinfo"/></p>
333 pcg 1.38 <member name="name" type="username"/>
334     </message>
335    
336 pcg 1.31 <message type="0007" name="update_userinfo" src="client">
337 pcg 1.18 <p>Update user info. Message structure is very similar
338     to <ref ref="userinfo"/>.</p>
339 pcg 1.17 <member name="setpass" type="flag"/>
340     Should the password be updated?
341 pcg 1.37 <member name="password" type="password" value="0"/>
342 pcg 1.17 <member name="realname" type="realname"/>
343     <member name="email" type="email"/>
344     <member name="info" type="userinfo"/>
345     <member name="homepage" type="url"/>
346 pcg 1.37 <member name="_unused" type="U64" value="0"/>
347     <member name="_unused" type="U64" value="0"/>
348 pcg 1.17 </message>
349    
350 pcg 1.36 <message type="0013" name="msg_chat" src="client">
351     <p>This message is sent to initiate or continue a private chat with
352     a user. You'll always receive a copy of what you have sent back
353     from the server (as usual).</p>
354    
355     <member name="name" type="username"/>
356     Name of sender ("yourself").
357     <member name="name2" type="username"/>
358     Name of recipient.
359     <member name="message" type="STRING"/>
360     The message.
361     </message>
362    
363 pcg 1.31 <message type="0014" name="req_stats" src="client">
364 pcg 1.18 <p>Request server statistics. Replied with <ref reply="stats"/></p>
365 pcg 1.19 </message>
366    
367 pcg 1.31 <message type="0016" name="idle_reset" src="client">
368 pcg 1.29 <p>Send in response to <ref reply="idle_warn"/> to keep the server from disconnecting.</p>
369     </message>
370    
371 pcg 1.31 <message type="001d" name="ping" src="client">
372 pcg 1.60 <p>No idea. Not used anymore?</p>
373 pcg 1.1 </message>
374    
375 pcg 1.31 <message type="001e" name="req_usergraph" src="client">
376 pcg 1.18 <p>Request user graph data, replied with <ref reply="usergraph"/>.</p>
377 pcg 1.17 <member name="name" type="username"/>
378     </message>
379    
380 pcg 1.31 <message type="0021" name="req_pic" src="client">
381 pcg 1.18 <p>Request a user picture from the server. Results in a <ref reply="userpic"/>
382     or a timeout.</p>
383 pcg 1.3 <member name="name" type="username"/>
384 pcg 1.1 </message>
385    
386 pcg 1.31 <message type="0021" name="upload_pic" src="client">
387 pcg 1.1 Same code as pic_req, but with an additional data section that
388 pcg 1.4 must contain a JPEG image that is &lt;=7KB. It must have 141×200 pixels.
389 pcg 1.3 <member name="name" type="username"/>
390 pcg 1.1 <member name="data" type="DATA"/>
391 pcg 1.29 </message>
392    
393 pcg 1.31 <message type="0023" name="send_memo" src="client">
394 pcg 1.29 <member name="name" type="username"/>
395 pcg 1.60 <member name="cid" type="CLIENTID16"/>
396 pcg 1.58 <p>A boolean, probably. Always true for me.</p>
397 pcg 1.29 <member name="msg" type="STRING"/>
398 pcg 1.1 </message>
399    
400 pcg 1.58 <message type="0024" name="delete_memos" src="client">
401     <p>Unconditionally deletes all memos.</p>
402     </message>
403    
404 pcg 1.31 <message type="0100" name="gnotice" src="client">
405 pcg 1.18 <p>Send a global message. Maybe. Never tried, for obvious reasons :/. Results
406     in a <ref reply="gnotice"/> sent to all users.</p>
407 pcg 1.1 <member name="notice" type="STRING"/>
408     </message>
409    
410 pcg 1.33 <message type="0200" name="notify_add" src="client">
411    
412     <p>Probably setting a notifier on a username, to get informed about
413 pcg 1.36 changes using <ref reply="notify_upd"/> messages. sending your own
414     username gives you a disconnect, so don't do that at home, kids!</p>
415 pcg 1.33
416     <member name="name" type="username"/>
417     </message>
418    
419     <message type="0201" name="notify_del" src="client">
420    
421     <p>Probably remove the notifier again.</p>
422    
423     <member name="name" type="username"/>
424     </message>
425    
426 pcg 1.31 <message type="0318" name="list_rooms" src="client">
427 pcg 1.18 <p>List the rooms in a specific group/category. Results in a <ref reply="upd_rooms"/> message.</p>
428 pcg 1.3 <member name="group" type="U8"/>
429 pcg 1.1 </message>
430    
431 pcg 1.31 <message type="031a" name="new_room" src="client">
432 pcg 1.1 Create a new room. Not verified.
433 pcg 1.3 <member name="name" type="username"/>
434 pcg 1.37 <member name="i1" type="U32" value="0"/>
435     <member name="b1" type="U8" value="0"/>
436     <member name="b2" type="U8" value="255"/>
437     <member name="b3" type="U8" value="255"/>
438     <member name="group" type="U8" value="1"/>
439 pcg 1.48 <member name="name" type="ZSTRING"/>
440     <member name="description" type="ZSTRING"/>
441 pcg 1.3 <member name="flags" type="U8"/>
442 pcg 1.40 See ROOMFLAGs
443 pcg 1.1 </message>
444    
445 pcg 1.47 <message type="031b" name="req_upd_rooms" src="client">
446     <p>Request a rooms update message for the given room.</p>
447 pcg 1.46 <member name="channel" type="U16"/>
448     </message>
449    
450 pcg 1.31 <message type="0413" name="req_game_record" src="client">
451 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>
452 pcg 1.16 <member name="name" type="username"/>
453     <member name="timestamp" type="timestamp"/>
454     If zero, start at the newest games, else only send games
455     before the given timestap.
456     </message>
457    
458 pcg 1.31 <message type="4300" name="join_room" src="client">
459 pcg 1.18 <p>Joins the given room. <ref reply="join_room"/> messages for yourself
460 pcg 1.9 and all users in that room, as well as the initial gamelist, are
461 pcg 1.18 send if the room exists. If not, timeout...</p>
462 pcg 1.3 <member name="channel" type="U16"/>
463 pcg 1.1 <member name="user" type="user"/>
464     </message>
465    
466 pcg 1.31 <message type="4301" name="msg_room" src="client">
467 pcg 1.9 Send a message to the room.
468 pcg 1.3 <member name="channel" type="U16"/>
469     <member name="name" type="username"/>
470 pcg 1.9 Must be the login-name of the user.
471 pcg 1.1 <member name="message" type="STRING"/>
472     </message>
473    
474 pcg 1.31 <message type="4302" name="part_room" src="client">
475 pcg 1.9 Remove yourself (or maybe others as admin) from a room.
476 pcg 1.3 <member name="channel" type="U16"/>
477     <member name="name" type="username"/>
478 pcg 1.1 </message>
479    
480 pcg 1.31 <message type="4305" name="new_game" src="client">
481 pcg 1.59 <p>Create a new game.</p>
482 pcg 1.41
483 pcg 1.3 <member name="channel" type="U16"/>
484 pcg 1.41 <p>The room where to start the new game</p>
485 pcg 1.60 <member name="cid" type="CLIENTID16"/>
486     <member name="gametype" type="U8"/>
487 pcg 1.54 <p>
488     GAMETYPE_UPLOAD probably not allowed. GAMETYPE_PRIVATE
489     only allowd together with GAMETYPE_TEACHING, GAMETYPE_DEMONSTRATION.
490     </p>
491     <member name="flags" type="U8"/>
492 pcg 1.46 <p>
493 pcg 1.54 0x2 == global open game list
494 pcg 1.46 </p>
495 pcg 1.1 <member name="rules" type="rules"/>
496 pcg 1.41 <p>When cloning a game, the rules are set up like this:
497     count => 65535, ruleset => 0, time => 4294967295, timesys => 0, interval => 4294967295.
498     Cloning itself seems to be implemented solely in the client (somewhat sane, for a change).
499     </p>
500 pcg 1.1 <member name="notes" type="STRING"/>
501 pcg 1.39 </message>
502    
503     <message type="430a" name="load_game" src="client">
504     Load an existing game into a room(?)
505     There is no indication that a new game is there except
506     for a upd_observers message with your name in it. Which means
507     you have to watch upd_observers messages that are not for any
508     currently open game and open one. Ugh.
509     <member name="channel" type="U16"/>
510     The room to load the game into.
511     <member name="timestamp" type="timestamp"/>
512     From the game record.
513     <member name="user" type="username"/>
514     <member name="flags" type="U8"/>
515     0 == public, 2 == private
516 pcg 1.1 </message>
517    
518 pcg 1.31 <message type="430b" name="req_games" src="client">
519 pcg 1.9 Request to update room game list (send this once per minute to get
520     updated). Results in upd_games messages.
521 pcg 1.3 <member name="channel" type="U16"/>
522 pcg 1.1 </message>
523    
524 pcg 1.31 <message type="4319" name="req_desc" src="client">
525 pcg 1.1 Request room description.
526 pcg 1.3 <member name="channel" type="U16"/>
527 pcg 1.1 </message>
528    
529 pcg 1.59 <message type="4400" name="challenge" src="client">
530     <p>Used to send challenges to existing games.</p>
531 pcg 1.3 <member name="channel" type="U16"/>
532 pcg 1.60 <member name="black" type="user"/>
533     <member name="white" type="user"/>
534     <member name="gametype" type="U8"/>
535     <member name="cid" type="CLIENTID8"/>
536     <p>Possibly an id. No idea. Better echo this from the challenge request.</p>
537     <member name="rules" type="rules"/>
538 pcg 1.1 </message>
539    
540 pcg 1.31 <message type="4403" name="join_game" src="client">
541 pcg 1.9 Join a game. See join_room.
542 pcg 1.5 <member name="channel" type="U16"/>
543 pcg 1.1 <member name="user" type="user"/>
544     </message>
545    
546 pcg 1.31 <message type="4404" name="part_game" src="client">
547 pcg 1.9 Leave (or kick as admin?) a certain user from a game.
548 pcg 1.3 <member name="channel" type="U16"/>
549     <member name="name" type="username"/>
550 pcg 1.1 </message>
551    
552 pcg 1.35 <message type="4405" name="set_tree" src="client">
553     Possibly upload an initial game to an empty room. Not tested.
554    
555     <member name="channel" type="U16"/>
556     <member name="tree" type="TREE"/>
557     </message>
558    
559 pcg 1.31 <message type="4406" name="upd_tree" src="client">
560 pcg 1.60 <p>Upload a partial game tree to the server. This is used to send moves
561 pcg 1.28 and even in-game comments to the server. For the comments, the
562 pcg 1.60 server prepends the username and rank.</p>
563 pcg 1.3 <member name="channel" type="U16"/>
564 pcg 1.1 <member name="tree" type="TREE"/>
565     </message>
566    
567 pcg 1.60 <message type="4407" name="mark_dead" src="client">
568     <p>Marks stones ad dead (or alive?) by the client. Details unclear</p>
569     <member name="channel" type="U16"/>
570     <member name="x" type="U8"/>
571     <member name="y" type="U8"/>
572     <member name="dead" type="flag"/>
573     <p>Possibly true means mark dead and false unmark, but that's just a wild guess.</p>
574     </message>
575    
576 pcg 1.63 <message type="440a" name="game_done" src="client">
577     <p>Sent by the client to mark the game as done.</p>
578 pcg 1.3 <member name="channel" type="U16"/>
579 pcg 1.63 <member name="id" type="U32"/>
580     <p>Probably some ID field to make sure that the client responds to the correct done click.</p>
581 pcg 1.1 </message>
582    
583 pcg 1.31 <message type="440c" name="claim_win" src="client">
584 pcg 1.62 <p>Used by the client to claim a win.</p>
585 pcg 1.3 <member name="channel" type="U16"/>
586 pcg 1.62 <member name="player" type="U8 "/>
587 pcg 1.1 </message>
588    
589 pcg 1.31 <message type="440d" name="add_time" src="client">
590 pcg 1.9 Not checked.
591    
592 pcg 1.3 <member name="channel" type="U16"/>
593     <member name="time" type="U32"/>
594     <member name="player" type="U8"/>
595 pcg 1.1 </message>
596    
597 pcg 1.59 <message type="440e" name="req_undo" src="client">
598     <member name="channel" type="U16"/>
599     </message>
600    
601 pcg 1.31 <message type="440f" name="grant_undo" src="client">
602 pcg 1.9 Can be send after a req_undo message was received to grant the undo.
603 pcg 1.3 <member name="channel" type="U16"/>
604 pcg 1.1 </message>
605    
606 pcg 1.31 <message type="4410" name="resign_game" src="client">
607 pcg 1.9 Resign the game.
608 pcg 1.3 <member name="channel" type="U16"/>
609     <member name="player" type="U8"/>
610 pcg 1.1 </message>
611    
612 pcg 1.31 <message type="441a" name="set_teacher" src="client">
613 pcg 1.50 <p>Change the teacher to somebody else (or possibly yourself == take it). If the
614     name is empty, the game will continue normally.</p>
615 pcg 1.3 <member name="channel" type="U16"/>
616     <member name="name" type="username"/>
617 pcg 1.1 </message>
618    
619 pcg 1.40 <message type="4422" name="allow_user" src="client">
620 pcg 1.50 <p>Unclear. Maybe allow users to talk? No idea, really.</p>
621 pcg 1.9
622 pcg 1.3 <member name="channel" type="U16"/>
623     <member name="othername" type="username"/>
624     <member name="name" type="username"/>; # gives user access to the game (to what? ;)
625 pcg 1.1 </message>
626    
627 pcg 1.31 <message type="4423" name="set_privacy" src="client">
628 pcg 1.9 Probably sets the "quiet" flag. Not checked.
629 pcg 1.3 <member name="channel" type="U16"/>
630 pcg 1.58 <member name="private" type="flag"/>
631 pcg 1.1 </message>
632    
633 pcg 1.61 <message type="4427" name="game_move" src="client">
634 pcg 1.60 <p>Only during playing, moves.</p>
635     <member name="channel" type="U16"/>
636     <member name="x" type="U8"/>
637     <member name="y" type="U8"/>
638     </message>
639    
640 pcg 1.31 <message type="4429" name="reject_challenge" src="client">
641 pcg 1.9 Reject a challenge from a given user. Not checked.
642    
643 pcg 1.3 <member name="channel" type="U16"/>
644     <member name="name" type="username"/>
645 pcg 1.60 <member name="gametype" type="U8"/>
646     <member name="cid" type="CLIENTID8"/>
647     <p>Possibly an id. No idea. Better echo this from the challenge request.</p>
648     <member name="rules" type="rules"/>
649 pcg 1.1 </message>
650    
651 pcg 1.46 <message type="442e" name="save_game" src="client">
652     <p>Is send when a game is closed and should be saved on the gamerecord.</p>
653    
654     <member name="channel" type="U16"/>
655     </message>
656    
657 pcg 1.31 <message type="4433" name="req_result" src="client">
658 pcg 1.9 I forgot.
659    
660 pcg 1.3 <member name="channel" type="U16"/>
661 pcg 1.35 </message>
662    
663 pcg 1.48 <message type="4434" name="set_quiet" src="client">
664     <p>Sets (or clears) the quiet flag on a game.</p>
665     <member name="channel" type="U16"/>
666 pcg 1.58 <member name="quiet" type="flag"/>
667 pcg 1.48 </message>
668    
669 pcg 1.35 <message type="4436" name="msg_game" src="client">
670     <member name="channel" type="U16"/>
671     <member name="message" type="STRING"/>
672 pcg 1.1 </message>
673    
674 pcg 1.37 <message type="ffff" name="quit" src="client">
675     <p>Sent by the client just before it logs out.</p>
676     </message>
677    
678 pcg 1.32 <h2>Structs mainly used in messages send by the server</h2>
679 pcg 1.1
680 pcg 1.3 <struct name="challenge_defaults">
681 pcg 1.9 Send soon after log-in to set the defaults for game challenges.
682 pcg 1.60 <member name="gametype" type="U8"/>
683 pcg 1.59 <member name="ruleset" type="U8"/>
684     <p>The ruleset member is a pure guess, please verify. it could also be after size for example.</p>
685 pcg 1.3 <member name="size" type="U32"/>
686     <member name="timesys" type="U32"/>
687     <member name="time" type="U32"/>
688     <member name="byo_time" type="U32"/>
689     <member name="byo_periods" type="U32"/>
690     <member name="can_time" type="U32"/>
691     <member name="can_stones" type="U32"/>
692 pcg 1.58 <member name="notes" type="STRING"/>
693 pcg 1.3 </struct>
694    
695     <struct name="game" class="KGS::Game">
696 pcg 1.9 Basic information about a game. Used in rooms for the gamelist and
697     in games to detect when a game is saved, changed type (e.g. R => D)
698     etc.
699    
700 pcg 1.3 <member name="channel" type="U16"/>
701 pcg 1.26 <member name="type" type="U8"/>
702 pcg 1.60 <member name="black" type="user"/>
703 pcg 1.1 White
704 pcg 1.60 <member name="white" type="user"/>
705 pcg 1.1 Black
706 pcg 1.60 <member name="owner" type="user"/>
707 pcg 1.1 Owner
708 pcg 1.26 <member name="size" type="U8"/>
709     <member name="handicap" type="I8"/>
710 pcg 1.1 &lt; 0 not fully setup
711 pcg 1.26 <member name="komi" type="komi16"/>
712 pcg 1.15 <member name="moves" type="I16"/>
713 pcg 1.14 This field reflects either the movenum or the score, sorry, not even guards help, as
714 pcg 1.15 the flags to determine that are _after_ the field. Arg. Divide by two to get the actual
715 pcg 1.27 score (NOT score16!) (arg²).
716 pcg 1.3 <member name="flags" type="U16"/>
717     <member name="observers" type="U32"/>
718     <member name="saved" type="flag"/>
719     <member name="notes" type="STRING" guard-member="handicap" guard-cond="&lt; 0"/>
720     </struct>
721    
722     <struct name="room_obs">
723 pcg 1.9 Obsolete.
724    
725 pcg 1.3 <member name="name" type="roomname"/>
726     <member name="channel" type="U16"/>
727     <member name="flags" type="U32"/>
728 pcg 1.4 <member name="users" type="U32"/>
729 pcg 1.3 </struct>
730    
731     <struct name="room" class="KGS::Room">
732     <member name="channel" type="U16"/>
733     <member name="flags" type="U8"/>
734     <member name="group" type="U8"/>
735     <member name="users" type="U16"/>
736     <member name="games" type="U16"/>
737 pcg 1.4 <member name="name" type="STRING"/>
738 pcg 1.3 </struct>
739 pcg 1.1
740 pcg 1.12 <struct name="scorevalues" class="KGS::Score">
741 pcg 1.13 <member name="score" type="score32"/>
742 pcg 1.3 <member name="territory" type="U32"/>
743     <member name="captures" type="U32"/>
744     <member name="i3" type="U32"/>
745     <member name="f2" type="U32"/>
746 pcg 1.20 <member name="komi" type="komi324"/>
747 pcg 1.4 <member name="i4" type="U32"/>
748 pcg 1.3 Apparently the i3, f2, i4 are zero.
749     </struct>
750 pcg 1.1
751 pcg 1.16 <struct name="game_record" class="KGS::GameRecord">
752 pcg 1.18 <p>A single game record entry, as seen in <ref ref="userinfo"/>.</p>
753 pcg 1.16
754     <member name="timestamp" type="timestamp"/>
755     Time this game was played.
756 pcg 1.42 <member name="flags1" type="U8"/>
757     <p>0:3 == handicap, 4:7 == gametype:0:4</p>
758 pcg 1.60 <member name="black" type="user"/>
759 pcg 1.16 White, flags contain low 8 bits of revision (bits 16-23).
760 pcg 1.60 <member name="white" type="user"/>
761 pcg 1.16 Black, flags contain high 8 bits of revision (bits 16-23).
762 pcg 1.60 <member name="owner" type="user"/>
763 pcg 1.34
764     <p><p>Owner (or empty)</p>
765    
766 pcg 1.60 <p>The bits 16-24 of black.flags and white.flags give the high and
767 pcg 1.34 low bits of a revision number in case there are multiple similar
768     games.</p></p>
769    
770 pcg 1.42 <member name="flags2" type="U16"/>
771     <p>0:11 == komi / 2, 12:14 == high 3 bits of gametype, 15: == sign bit</p>
772 pcg 1.16 <member name="score" type="score16"/>
773 pcg 1.42 <member name="flags3" type="U8"/>
774 pcg 1.34
775 pcg 1.42 <p>0:5 == boardsize; 6: == no idea; 7: == inplay?</p>
776 pcg 1.34
777 pcg 1.16 </struct>
778    
779 pcg 1.32 <h2>Server-generated messages</h2>
780 pcg 1.1
781 pcg 1.31 <message type="0001" name="login" src="server">
782 pcg 1.40 <member name="message" type="CONSTANT" value='login successful'/>
783 pcg 1.37 <member name="success" type="CONSTANT" value="1"/>
784 pcg 1.1 </message>
785    
786 pcg 1.31 <message type="0002" name="login" src="server">
787 pcg 1.40 <member name="message" type="CONSTANT" value='login successful: client version is outdated.'/>
788 pcg 1.37 <member name="success" type="CONSTANT" value="1"/>
789 pcg 1.1 </message>
790    
791 pcg 1.31 <message type="0003" name="login" src="server">
792 pcg 1.40 <member name="message" type="CONSTANT" value='login failed: client version out of date'/>
793 pcg 1.1 ** maybe more following? **
794     </message>
795    
796 pcg 1.31 <message type="0004" name="login" src="server">
797 pcg 1.40 <member name="message" type="CONSTANT" value='login failed: wrong password'/>
798 pcg 1.1 ** maybe more following? **
799     </message>
800    
801 pcg 1.31 <message type="0005" name="login" src="server">
802 pcg 1.40 <member name="message" type="CONSTANT" value='login failed: specified user does not exist'/>
803 pcg 1.1 </message>
804    
805 pcg 1.31 <message type="0006" name="login" src="server">
806 pcg 1.56 <member name="message" type="CONSTANT" value='login failed: user of same name logged in'/>
807 pcg 1.1 </message>
808    
809 pcg 1.31 <message type="0008" name="userinfo" src="server">
810 pcg 1.17 User info.
811 pcg 1.33 <member name="_unused0" type="flag"/>
812 pcg 1.16 <member name="user" type="user"/>
813 pcg 1.33 <member name="_unused1" type="U64"/>
814 pcg 1.16 <member name="realname" type="realname"/>
815     <member name="email" type="email"/>
816     <member name="info" type="userinfo"/>
817     <member name="homepage" type="url"/>
818     <member name="regdate" type="timestamp"/>
819     When the user registered (0 == never registered).
820     <member name="lastlogin" type="timestamp"/>
821     When the user logged in for the last time.
822     <!-- maybe more? -->
823     </message>
824    
825 pcg 1.40 <message type="0009" name="upd_userinfo_result" src="server">
826     <member name="name" type="username"/>
827     <member name="message" type="CONSTANT" value='Thanks for registering.'/>
828     </message>
829    
830     <message type="000a" name="upd_userinfo_result" src="server">
831     <member name="name" type="username"/>
832     <member name="message" type="CONSTANT" value='The user &quot;%s&quot; has been successfully updated.'/>
833     </message>
834    
835     <message type="000b" name="upd_userinfo_result" src="server">
836     <member name="name" type="username"/>
837     <member name="message" type="CONSTANT" value='There is no user &quot;%s&quot;. Update failed.'/>
838     </message>
839    
840     <message type="0012" name="userinfo_failed" src="server">
841     <p>Sent when no userinfo for the requested user could be found(?)</p>
842     <member name="name" type="username"/>
843     </message>
844    
845 pcg 1.31 <message type="0013" name="msg_chat" src="server">
846 pcg 1.34 <member name="name" type="username"/>
847 pcg 1.36 Name of sender (either yourself (echo) or other)
848 pcg 1.34 <member name="name2" type="username"/>
849 pcg 1.36 Name of recipient.
850 pcg 1.1 <member name="message" type="STRING"/>
851     </message>
852    
853 pcg 1.31 <message type="0015" name="stats" src="server">
854 pcg 1.3 <member name="ver_major" type="U16"/>
855     <member name="ver_minor" type="U16"/>
856     <member name="ver_micro" type="U16"/>
857 pcg 1.16 <member name="boot_time" type="timestamp"/>
858 pcg 1.3 <member name="users_cur" type="U32"/>
859     <member name="users_max" type="U32"/>
860     <member name="users_lim" type="U32"/>
861     <member name="accts_cur" type="U32"/>
862     <member name="accts_max" type="U32"/>
863     <member name="unknown1" type="U32"/>
864     <member name="work_max" type="U32"/>
865     <member name="rooms_cur" type="U32"/>
866     <member name="rooms_max" type="U32"/>
867     <member name="rooms_lim" type="U32"/>
868     <member name="games_cur" type="U32"/>
869     <member name="games_max" type="U32"/>
870     <member name="games_lim" type="U32"/>
871     <member name="results_cur" type="U32"/>
872     <member name="results_max" type="U32"/>
873     <member name="unknown2" type="U32"/>
874     <member name="params_cur" type="U32"/>
875     <member name="params_max" type="U32"/>
876     <member name="bytes_in" type="U64"/>
877     <member name="packets_in" type="U64"/>
878     <member name="bytes_out" type="U64"/>
879 pcg 1.4 <member name="packets_out" type="U64"/>
880 pcg 1.1 </message>
881    
882 pcg 1.31 <message type="0016" name="idle_warn" src="server">
883 pcg 1.60 <p>idle warning, autologout soon (10 minutes...). Responding with <ref ref="ping"/> usually helps.</p>
884 pcg 1.1 </message>
885    
886 pcg 1.34 <message type="0018" name="login" src="server">
887 pcg 1.40 <member name="message" type="CONSTANT" value='logged out: another client logged in with your username'/>
888     </message>
889    
890     <message type="001c" name="login" src="server">
891     <member name="message" type="CONSTANT" value='logged out: idle for too long'/>
892     </message>
893    
894     <message type="0020" name="error" src="server">
895     <member name="message" type="CONSTANT" value='Sorry, you have too many unfinished games. You cannot turn on your rank. Please finish some of your games, then try again.'/>
896 pcg 1.34 </message>
897    
898     <message type="0022" name="login" src="server">
899     I was blocked sooo many times for developing this client that it was
900     easy to figure out. The KGS admins sure need no extra nazi training
901     :(
902     <member name="reason" type="STRING"/>
903 pcg 1.40 <member name="result" type="CONSTANT" value='user or ip blocked'/>
904 pcg 1.34 </message>
905    
906 pcg 1.31 <message type="001b" name="timewarning_default" src="server">
907 pcg 1.1 WILD guess
908 pcg 1.3 <member name="channel" type="U16"/>
909     <member name="time" type="U16"/>
910 pcg 1.1 </message>
911    
912 pcg 1.31 <message type="001c" name="idle_err" src="server">
913 pcg 1.1 autologout
914     </message>
915    
916 pcg 1.31 <message type="001d" name="ping" src="server">
917 pcg 1.16 Sent by the server regularly, but not answering them
918     isn't valid. Strange form of keepalive?
919 pcg 1.1 </message>
920    
921 pcg 1.31 <message type="001e" name="usergraph" src="server">
922 pcg 1.17 User graph data.
923 pcg 1.33 <member name="name" type="username"/>
924 pcg 1.17 <member name="data" type="I16" array="yes"/>
925     If empty, no graph is available. The unit seems to
926     be centi-kyu, with 1 dan == 0, 2 dan == 100, 1 kyu == -100.
927     There is probably one entry per day, the newest one last.
928     </message>
929    
930 pcg 1.31 <message type="0021" name="userpic" src="server">
931 pcg 1.3 <member name="name" type="username"/>
932 pcg 1.1 Reply to pic_req, contains an image in jpeg format.
933     <member name="data" type="DATA"/>
934     </message>
935    
936 pcg 1.58 <message type="0025" name="memo_error" src="server">
937     <p>Account unknown.</p>
938     <member name="name" type="username"/>
939 pcg 1.60 <member name="cid" type="CLIENTID16"/>
940 pcg 1.58 <member name="message" type="CONSTANT" value='memo send failed: account already exists'/>
941     <member name="subtype" type="CONSTANT" value='25'/>
942     </message>
943    
944     <message type="0026" name="memo_error" src="server">
945     <p>Just a guess.</p>
946     <member name="name" type="username"/>
947 pcg 1.60 <member name="cid" type="CLIENTID16"/>
948 pcg 1.58 <member name="message" type="CONSTANT" value='memo send failed: error 26'/>
949     <member name="subtype" type="CONSTANT" value='26'/>
950     </message>
951    
952     <message type="0027" name="memo_error" src="server">
953     <p>User is currently online, please use chat.</p>
954     <member name="name" type="username"/>
955 pcg 1.60 <member name="cid" type="CLIENTID16"/>
956 pcg 1.58 <member name="message" type="CONSTANT" value='memo send failed: user is online, use chat'/>
957     <member name="subtype" type="CONSTANT" value='27'/>
958     </message>
959    
960     <message type="0028" name="memo_error" src="server">
961     <p>Just a guess.</p>
962     <member name="name" type="username"/>
963 pcg 1.60 <member name="cid" type="CLIENTID16"/>
964 pcg 1.58 <member name="message" type="CONSTANT" value='memo send failed: error 28'/>
965     <member name="subtype" type="CONSTANT" value='28'/>
966     </message>
967    
968     <message type="0029" name="memo" src="server">
969     <member name="name" type="username"/>
970     <member name="time" type="timestamp"/>
971     <member name="message" type="ZSTRING"/>
972     </message>
973    
974     <message type="002a" name="memo_sent" src="server">
975     <p>The memo was sent successfully</p>
976     <member name="name" type="username"/>
977 pcg 1.60 <member name="cid" type="CLIENTID16"/>
978 pcg 1.58 </message>
979    
980 pcg 1.31 <message type="0100" name="gnotice" src="server">
981 pcg 1.1 global notice, sent to everybody
982     <member name="notice" type="STRING"/>
983     </message>
984    
985 pcg 1.33 <message type="0202" name="notify_event" src="server">
986 pcg 1.17 # maybe soe notify? Totally unclear.
987 pcg 1.37 # loc 0" type="userinfo, flags etc. loc 1 => gameinfo?, loc 2 => game result (more data)
988 pcg 1.33 <member name="event" type="U32"/>
989 pcg 1.16 <member name="user" type="user"/>
990 pcg 1.34 <member name="gamerecord" type="game_record" guard-member="event" guard-cond="== 2"/>
991 pcg 1.33 <p>Game result record?</p>
992    
993 pcg 1.16 </message>
994 pcg 1.1
995 pcg 1.58 <message type="030c" name="unknown_030c" src="server">
996     <p>Not the slightest... No payload, either.</p>
997     </message>
998    
999 pcg 1.31 <message type="0310" name="priv_room" src="server">
1000 pcg 1.1 "permission denied" when joining a room
1001     <member name="name" type="STRING"/>
1002     </message>
1003    
1004 pcg 1.31 <message type="0318" name="upd_rooms" src="server">
1005 pcg 1.1 <member name="rooms" type="room" array="yes"/>
1006     </message>
1007    
1008 pcg 1.31 <message type="0411" name="chal_defaults" src="server">
1009 pcg 1.16 <member name="channel" type="U16"/>
1010     <member name="defaults" type="challenge_defaults"/>
1011     </message>
1012    
1013 pcg 1.61 <message type="0412" name="already_playing" src="server">
1014     Unable to create new game.
1015 pcg 1.40 <member name="message" type="CONSTANT" value='Sorry, you are already playing in one game, so you can&apos;t start playing in another.'/>
1016 pcg 1.61 <member name="cid" type="CLIENTID16"/>
1017     <p>The cid of the new_game etc. request.</p>
1018 pcg 1.17 </message>
1019    
1020 pcg 1.31 <message type="0414" name="game_record" src="server">
1021 pcg 1.16 The users game record.
1022     <member name="name" type="username"/>
1023     <member name="more" type="flag"/>
1024     Wether more games are available (must be requested manually)
1025     <member name="games" type="game_record" array="yes"/>
1026     </message>
1027    
1028 pcg 1.40 <message type="0417" name="error" src="server">
1029     <member name="message" type="CONSTANT" value='Sorry, your opponent is currently not logged in, so you can&apos;t resume this game.'/>
1030     </message>
1031    
1032     <message type="0418" name="error" src="server">
1033     <member name="message" type="CONSTANT" value='Sorry, your opponent is already playing in a game, so you cannot continue this one.'/>
1034     </message>
1035    
1036     <message type="0419" name="error" src="server">
1037     <member name="message" type="CONSTANT" value='Sorry, the server is out of boards! Please wait a few minutes and try to start a game again.'/>
1038     </message>
1039    
1040 pcg 1.31 <message type="041c" name="upd_game2" src="server">
1041 pcg 1.17 Unclear.
1042 pcg 1.3 <member name="channel_junk" type="U16"/>
1043 pcg 1.1 <member name="game" type="game"/>
1044     </message>
1045    
1046 pcg 1.40 <message type="041f" name="error" src="server">
1047     <member name="message" type="CONSTANT" value='Sorry, the game you tried to load was not correctly saved...probably caused by the server crashing. It cannot be recovered.'/>
1048     </message>
1049    
1050     <message type="0420" name="error" src="server">
1051     <member name="message" type="CONSTANT" value='Sorry, user &quot;%s&quot; has left the game you are starting before you could challenge them. You will have to play against somebody else.'/>
1052     </message>
1053    
1054     <message type="0421" name="error" src="server">
1055     <member name="message" type="CONSTANT" value='Sorry, this game is a private lesson. You will not be allowed to observe it.'/>
1056     </message>
1057    
1058 pcg 1.44 <!-- added recently -->
1059 pcg 1.46 <message type="043a" name="add_global_challenge" src="server">
1060     <p>
1061     Adds or updates a global challenge (open game list).
1062     </p>
1063 pcg 1.44 <member name="channel" type="U16"/>
1064 pcg 1.46 <p>
1065     The room this game is associated with.
1066     </p>
1067 pcg 1.44 <member name="game" type="game"/>
1068 pcg 1.59 <p>The game. The "moves" member contains a small number. Probably garbage.</p>
1069 pcg 1.44 </message>
1070    
1071 pcg 1.1 <h3>Room messages</h3>
1072    
1073     <p>Not all room messages are for rooms only, and rooms need to parse
1074     not only these messages. Orthogonality, what for?</p>
1075    
1076 pcg 1.31 <message type="4300" name="join_room" src="server">
1077 pcg 1.3 <member name="channel" type="U16"/>
1078 pcg 1.1 <member name="users" type="user" array="yes"/>
1079     </message>
1080    
1081 pcg 1.31 <message type="4301" name="msg_room" src="server">
1082 pcg 1.3 <member name="channel" type="U16"/>
1083     <member name="name" type="username"/>
1084 pcg 1.1 <member name="message" type="STRING"/>
1085     </message>
1086    
1087 pcg 1.31 <message type="4302" name="part_room" src="server">
1088 pcg 1.3 <member name="channel" type="U16"/>
1089 pcg 1.1 <member name="user" type="user"/>
1090     </message>
1091    
1092 pcg 1.31 <message type="4303" name="del_room" src="server">
1093 pcg 1.3 <member name="channel" type="U16"/>
1094 pcg 1.1 </message>
1095    
1096 pcg 1.31 <message type="4304" name="upd_games" src="server">
1097 pcg 1.3 <member name="channel" type="U16"/>
1098 pcg 1.1 <member name="games" type="game" array="yes"/>
1099     </message>
1100    
1101 pcg 1.31 <message type="4319" name="desc_room" src="server">
1102 pcg 1.3 <member name="channel" type="U16"/>
1103     <member name="owner" type="username"/>
1104 pcg 1.1 <member name="description" type="STRING"/>
1105     </message>
1106 pcg 1.28
1107 pcg 1.1 <h3>Game messages</h3>
1108    
1109 pcg 1.59 <message type="4400" name="challenge" src="server">
1110 pcg 1.1 Unclear.
1111 pcg 1.3 <member name="channel" type="U16"/>
1112 pcg 1.60 <member name="black" type="user"/>
1113     <member name="white" type="user"/>
1114     <member name="gametype" type="U8"/>
1115     <member name="cid" type="CLIENTID8"/>
1116     <p>Possibly an id. No idea. Better echo this from the challenge request.</p>
1117     <member name="rules" type="rules"/>
1118     <member name="notes" type="STRING"/>
1119     <p>This field is optional</p>
1120 pcg 1.1 </message>
1121    
1122 pcg 1.31 <message type="4401" name="upd_game" src="server">
1123 pcg 1.3 <member name="channel" type="U16"/>
1124 pcg 1.1 <member name="game" type="game"/>
1125     </message>
1126    
1127 pcg 1.31 <message type="4402" name="del_game" src="server">
1128 pcg 1.3 <member name="channel" type="U16"/>
1129 pcg 1.1 </message>
1130    
1131 pcg 1.31 <message type="4403" name="upd_observers" src="server">
1132 pcg 1.3 <member name="channel" type="U16"/>
1133 pcg 1.1 <member name="users" type="user" array="yes"/>
1134     </message>
1135    
1136 pcg 1.31 <message type="4404" name="del_observer" src="server">
1137 pcg 1.3 <member name="channel" type="U16"/>
1138     <member name="name" type="username"/>
1139 pcg 1.1 </message>
1140    
1141 pcg 1.31 <message type="4405" name="set_tree" src="server">
1142 pcg 1.3 <member name="channel" type="U16"/>
1143 pcg 1.1 <member name="tree" type="TREE"/>
1144     </message>
1145    
1146 pcg 1.31 <message type="4406" name="upd_tree" src="server">
1147 pcg 1.3 <member name="channel" type="U16"/>
1148 pcg 1.1 <member name="tree" type="TREE"/>
1149     </message>
1150    
1151 pcg 1.31 <message type="4409" name="superko" src="server">
1152 pcg 1.1 Superko-warning.
1153 pcg 1.3 <member name="channel" type="U16"/>
1154 pcg 1.1 </message>
1155    
1156 pcg 1.63 <message type="440a" name="game_done" src="server">
1157     <p>Send by the server when one of the players sends a done.</p>
1158     <member name="channel" type="U16"/>
1159     <member name="id" type="U32"/>
1160     <p>Probably some ID field to make sure that the client responds to the correct done click.</p>
1161     <p>The high bit has some function I don't know. It must be cleared when replying.</p>
1162     <member name="black" type="flag"/>
1163     <member name="white" type="flag"/>
1164     </message>
1165    
1166 pcg 1.31 <message type="440b" name="final_result" src="server">
1167 pcg 1.3 <member name="channel" type="U16"/>
1168 pcg 1.12 <member name="blackscore" type="scorevalues"/>
1169     <member name="whitescore" type="scorevalues"/>
1170 pcg 1.1 </message>
1171    
1172 pcg 1.61 <message type="440c" name="out_of_time" src="server">
1173 pcg 1.62 <p>Sent when the user is out of time and moves, or when the opponent
1174     requests <ref reply="userinfo"/>.</p>
1175 pcg 1.61 <member name="channel" type="U16"/>
1176     <member name="player" type="U8"/>
1177     </message>
1178    
1179 pcg 1.31 <message type="440e" name="req_undo" src="server">
1180 pcg 1.3 <member name="channel" type="U16"/>
1181 pcg 1.1 </message>
1182    
1183 pcg 1.31 <message type="4410" name="resign_game" src="server">
1184 pcg 1.3 <member name="channel" type="U16"/>
1185     <member name="player" type="U8"/>
1186 pcg 1.1 </message>
1187    
1188 pcg 1.40 <message type="4415" name="game_error" src="server">
1189     <member name="channel" type="U16"/>
1190     <member name="message" type="CONSTANT" value='Sorry, this is a lecture game. Only authorized players are allowed to make comments.'/>
1191     </message>
1192    
1193 pcg 1.31 <message type="441a" name="set_teacher" src="server">
1194 pcg 1.3 <member name="channel" type="U16"/>
1195     <member name="name" type="username"/>
1196 pcg 1.1 </message>
1197    
1198 pcg 1.31 <message type="441d" name="owner_left" src="server">
1199 pcg 1.3 <member name="channel" type="U16"/>
1200 pcg 1.40 <member name="message" type="CONSTANT" value='Sorry, the owner of this game has left. Nobody will be allowed to edit it until the owner returns.'/>
1201 pcg 1.1 </message>
1202    
1203 pcg 1.31 <message type="441e" name="teacher_left" src="server">
1204 pcg 1.1 Unclear.
1205 pcg 1.3 <member name="channel" type="U16"/>
1206 pcg 1.1 </message>
1207    
1208 pcg 1.40 <message type="4422" name="allow_user_result" src="server">
1209     <member name="message" type="CONSTANT" value='User &quot;%s&quot; will now be allowed full access to your game.'/>
1210     <member name="channel" type="U16"/>
1211     </message>
1212    
1213     <message type="4424" name="allow_user_result" src="server">
1214     <member name="message" type="CONSTANT" value='Sorry, user &quot;%s&quot; is a guest and cannot be allowed full access to your game.'/>
1215     <member name="channel" type="U16"/>
1216     </message>
1217    
1218     <message type="4425" name="allow_user_result" src="server">
1219     <member name="message" type="CONSTANT" value='Sorry, user &quot;%s&quot; does not seem to exist and cannot be allowed into your game.'/>
1220 pcg 1.3 <member name="channel" type="U16"/>
1221 pcg 1.27 </message>
1222    
1223 pcg 1.31 <message type="4428" name="add_tree" src="server">
1224 pcg 1.27 <p>See <ref ref="set_tree"/>. In addition, flags the tree as being
1225     uploaded completely.</p>
1226     <member name="channel" type="U16"/>
1227     <member name="tree" type="TREE"/>
1228 pcg 1.40 </message>
1229    
1230     <message type="4429" name="reject_challenge" src="server">
1231     Reject a challenge by a given user. Not checked.
1232 pcg 1.60 <!-- should become a record type somehow... -->
1233 pcg 1.40
1234     <member name="channel" type="U16"/>
1235     <member name="name" type="username"/>
1236 pcg 1.60 <member name="gametype" type="U8"/>
1237     <member name="cid" type="CLIENTID8"/>
1238     <p>Possibly an id. No idea. Better echo this from the challenge request.</p>
1239     <member name="rules" type="rules"/>
1240 pcg 1.41 </message>
1241    
1242 pcg 1.63 <message type="442b" name="set_comments" src="server">
1243     <p>Sent at end of games to set the comments not seen previously.</p>
1244     <member name="channel" type="U16"/>
1245     <member name="node" type="U32"/>
1246     <member name="comments" type="STRING"/>
1247     </message>
1248    
1249     <message type="442c" name="add_comments" src="server">
1250     <p>Sent at end of games to add all game commentary.</p>
1251     <member name="channel" type="U16"/>
1252     <member name="node" type="U32"/>
1253     <member name="comments" type="STRING"/>
1254     </message>
1255    
1256 pcg 1.46 <message type="442f" name="new_game" src="server">
1257 pcg 1.41 <p>Notifies the client that a new game has been created. This
1258 pcg 1.46 message is sent long *after* upd_games and upd_observers etc.
1259     have been received. *sigh*</p>
1260 pcg 1.41
1261     <member name="channel" type="U16"/>
1262 pcg 1.46 <p>The newly created game.</p>
1263 pcg 1.60 <member name="cid" type="CLIENTID16"/>
1264 pcg 1.46 <p>The ID sent to the server in new_game.</p>
1265 pcg 1.1 </message>
1266    
1267 pcg 1.31 <message type="4433" name="req_result" src="server">
1268 pcg 1.1 Unclear.
1269 pcg 1.3 <member name="channel" type="U16"/>
1270 pcg 1.1 # # recv_result(?)
1271     </message>
1272    
1273 pcg 1.48 <message type="4434" name="set_quiet" src="server">
1274     <p>Sets (or clears) the quiet flag on a game.</p>
1275 pcg 1.3 <member name="channel" type="U16"/>
1276 pcg 1.58 <member name="quiet" type="flag"/>
1277 pcg 1.1 </message>
1278    
1279 pcg 1.57 <message type="4437" name="set_gametime" src="server">
1280     <p>Sent when joining a game. Gives the remaining time +
1281     periods/moves for the players, to correctly initialize the clocks.</p>
1282 pcg 1.51 <member name="channel" type="U16"/>
1283 pcg 1.64 <member name="black_time" type="time"/>
1284     <member name="black_moves" type="U16"/>
1285     <member name="white_time" type="time"/>
1286     <member name="white_moves" type="U16"/>
1287 pcg 1.51 </message>
1288    
1289 pcg 1.46 <message type="443b" name="del_global_challenge" src="server">
1290     <p>
1291     Remove a game from the global challenge list (open game list).
1292     </p>
1293 pcg 1.43 <member name="channel" type="U16"/>
1294 pcg 1.46 <p>The game id to remove.</p>
1295 pcg 1.44 <member name="game" type="U16"/>
1296 pcg 1.46 <p>Probably the same. I suggest to use this id for no good reason.</p>
1297 pcg 1.43 </message>
1298 pcg 1.1 </body>
1299     </html>
1300