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