ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/kgsueme/doc/protocol.html
(Generate patch)

Comparing kgsueme/doc/protocol.html (file contents):
Revision 1.71 by root, Mon May 31 08:44:22 2004 UTC vs.
Revision 1.72 by root, Mon May 31 08:56:37 2004 UTC

1<html> 1<html>
2<head> 2<head>
3<title>KGS Protocol Description</title> 3<title>KGS Protocol Description</title>
4<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 4<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5<!-- 5<!--
6 Copyright (C) 2003 Marc Lehmannn &lt;pcg@goof.com&gt; 6 Copyright (C) 2003,2004 Marc Lehmannn &lt;pcg@goof.com&gt;
7 7
8 You can redistribute and/or modify this document under the terms of 8 You can redistribute and/or modify this document under the terms of
9 the GNU General Public License as published by the Free Software 9 the GNU General Public License as published by the Free Software
10 Foundation; either version 2 of the License, or (at your option) any 10 Foundation; either version 2 of the License, or (at your option) any
11 later version. 11 later version.
… …
20 Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 20 Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
21--> 21-->
22</head> 22</head>
23<body> 23<body>
24 24
25<h1>$Revision: 1.71 $</h1> 25<h1>$Revision: 1.72 $</h1>
26 26
27<h1>KGS Protocol Description</h1> 27<h1>KGS Protocol Description</h1>
28 28
29 <p>This XML document describes the KGS protocol. It is also used 29 <p>This XML document describes the KGS protocol. It is also used
30 to automatically generate the perl parser for all the messages and 30 to automatically generate the perl parser for all the messages and
31 structures in the protocol. Adapting it to other languages should be 31 structures in the protocol. Adapting it to other languages should be
32 almost trivial.</p> 32 almost trivial (and partly has been done).</p>
33 33
34 <p>If you feel you need to update the visual appearance of this 34 <p>If you feel you need to update the visual appearance of this
35 document, feel free to look at <tt>doc/doc2html.xsl</tt> and improve 35 document, feel free to look at <tt>doc/doc2html.xsl</tt> and improve
36 it.</p> 36 it.</p>
37 37
… …
92 <th width="4%">VALUE</th> 92 <th width="4%">VALUE</th>
93 <th>DESCRIPTION</th> 93 <th>DESCRIPTION</th>
94 <th width="10%">GUARD</th> 94 <th width="10%">GUARD</th>
95 </tr> 95 </tr>
96 <tr> 96 <tr>
97 <td>_unknown</td>
98 <td>U16</td>
99 <td> </td>
100 <td>
101
102  
103 </td>
104 <td>
105 <b></b>
106  
107 </td>
108 </tr>
109 <tr>
110 <td>length</td> 97 <td>length</td>
111 <td>U16</td> 98 <td>U16</td>
112 <td> </td> 99 <td> </td>
113 <td> 100 <td>
114 101
102 <p>The length is the length of the full message including the header.</p>
103
104 <p>Beginning with version 2.5.x, a number is xored into the low
105 byte of the length in <em>sent</em> packages only, as given by the
106 following recurrence: <code>rand[0] = 0; rand[i+1] = msg[i].length
107 + (rand[i] * 0x04c2af9b + 0xfffffffb); xorbyte = rand &gt;&gt;
108 24</code>, all in 32 bit unsigned iso-c arithmetic.</p>
109
115 110
116   111  
117 </td> 112 </td>
118 <td> 113 <td>
119 <b></b> 114 <b></b>
… …
123 <tr> 118 <tr>
124 <td>type</td> 119 <td>type</td>
125 <td>U16</td> 120 <td>U16</td>
126 <td> </td> 121 <td> </td>
127 <td> 122 <td>
123 <p>If the type is &gt;= 0x4000 this is a message for a specific channel. The channel
124 number is always the next U16.</p>
125
126 <p>Beginning with version 2.5.x, a number is <em>added</em> on <em>received</em>
127 messages only. The algorithm is as follows:
128
129 <pre>
130 msglen &lt; 44: type = typefield
131 msglen &gt; 44: type = (typefield + rand[i]) % 0x10000
132 rand[0] = 0
133 rand[i+1] = username[type % length username] + rand[i] * (type - 0x6cdd)
134 where username is the user name of the logged-in user. coooool.
135 </pre>
128 136 </p>
137
138
129   139  
130 </td> 140 </td>
131 <td> 141 <td>
132 <b></b> 142 <b></b>
133   143  
… …
333 <tr> 343 <tr>
334 <td>PRIVATE</td> 344 <td>PRIVATE</td>
335 <td></td> 345 <td></td>
336 <td>128 </td> 346 <td>128 </td>
337 <td> 347 <td>
338 348 <p>PRIVATE is ored onto DEMONSTRATION or TEACHING</p>
349
339   350  
340 </td> 351 </td>
341 <td> 352 <td>
342 <b></b> 353 <b></b>
343   354  
… …
411 <tr> 422 <tr>
412 <td>ADMIN</td> 423 <td>ADMIN</td>
413 <td></td> 424 <td></td>
414 <td>0x01 </td> 425 <td>0x01 </td>
415 <td> 426 <td>
427 <p>Admins only(?)</p>
416 428
417   429  
418 </td> 430 </td>
419 <td> 431 <td>
420 <b></b> 432 <b></b>
… …
424 <tr> 436 <tr>
425 <td>DEFAULT</td> 437 <td>DEFAULT</td>
426 <td></td> 438 <td></td>
427 <td>0x04 </td> 439 <td>0x04 </td>
428 <td> 440 <td>
441 <p>Seems to be set on the english room. Or maybe not.</p>
429 442
430   443  
431 </td> 444 </td>
432 <td> 445 <td>
433 <b></b> 446 <b></b>
… …
437 <tr> 450 <tr>
438 <td>PRIVATE</td> 451 <td>PRIVATE</td>
439 <td></td> 452 <td></td>
440 <td>0x10 </td> 453 <td>0x10 </td>
441 <td> 454 <td>
442 455 <p>This room is private.</p>
456
443   457  
444 </td> 458 </td>
445 <td> 459 <td>
446 <b></b> 460 <b></b>
447   461  
… …
759 <tr> 773 <tr>
760 <td>NONE</td> 774 <td>NONE</td>
761 <td></td> 775 <td></td>
762 <td>2 </td> 776 <td>2 </td>
763 <td> 777 <td>
764 778 <p>Sometimes used to mark absence of marks, or no player or etc...</p>
779
765   780  
766 </td> 781 </td>
767 <td> 782 <td>
768 <b></b> 783 <b></b>
769   784  
… …
1484 <tr> 1499 <tr>
1485 <td>cid</td> 1500 <td>cid</td>
1486 <td>CLIENTID16</td> 1501 <td>CLIENTID16</td>
1487 <td> </td> 1502 <td> </td>
1488 <td> 1503 <td>
1504 <p>A boolean, probably. Always true for me.</p>
1489 1505
1490   1506  
1491 </td> 1507 </td>
1492 <td> 1508 <td>
1493 <b></b> 1509 <b></b>
… …
2012 <tr> 2028 <tr>
2013 <td>channel</td> 2029 <td>channel</td>
2014 <td>U16</td> 2030 <td>U16</td>
2015 <td> </td> 2031 <td> </td>
2016 <td> 2032 <td>
2033 <p>The room where to start the new game</p>
2017 2034
2018   2035  
2019 </td> 2036 </td>
2020 <td> 2037 <td>
2021 <b></b> 2038 <b></b>
… …
2038 <tr> 2055 <tr>
2039 <td>gametype</td> 2056 <td>gametype</td>
2040 <td>U8</td> 2057 <td>U8</td>
2041 <td> </td> 2058 <td> </td>
2042 <td> 2059 <td>
2060 <p>
2061 GAMETYPE_UPLOAD probably not allowed. GAMETYPE_PRIVATE
2062 only allowd together with GAMETYPE_TEACHING, GAMETYPE_DEMONSTRATION.
2063 </p>
2043 2064
2044   2065  
2045 </td> 2066 </td>
2046 <td> 2067 <td>
2047 <b></b> 2068 <b></b>
… …
2051 <tr> 2072 <tr>
2052 <td>flags</td> 2073 <td>flags</td>
2053 <td>U8</td> 2074 <td>U8</td>
2054 <td> </td> 2075 <td> </td>
2055 <td> 2076 <td>
2077 <p>
2078 0x2 == global open game list
2079 </p>
2056 2080
2057   2081  
2058 </td> 2082 </td>
2059 <td> 2083 <td>
2060 <b></b> 2084 <b></b>
… …
2064 <tr> 2088 <tr>
2065 <td>rules</td> 2089 <td>rules</td>
2066 <td>rules</td> 2090 <td>rules</td>
2067 <td> </td> 2091 <td> </td>
2068 <td> 2092 <td>
2093 <p>When cloning a game, the rules are set up like this:
2094 count =&gt; 65535, ruleset =&gt; 0, time =&gt; 4294967295, timesys =&gt; 0, interval =&gt; 4294967295.
2095 Cloning itself seems to be implemented solely in the client (somewhat sane, for a change).
2096 </p>
2069 2097
2070   2098  
2071 </td> 2099 </td>
2072 <td> 2100 <td>
2073 <b></b> 2101 <b></b>
… …
2292 <tr> 2320 <tr>
2293 <td>cid</td> 2321 <td>cid</td>
2294 <td>CLIENTID8</td> 2322 <td>CLIENTID8</td>
2295 <td> </td> 2323 <td> </td>
2296 <td> 2324 <td>
2325 <p>Possibly an id. No idea. Better echo this from the challenge request.</p>
2297 2326
2298   2327  
2299 </td> 2328 </td>
2300 <td> 2329 <td>
2301 <b></b> 2330 <b></b>
… …
2544 <tr> 2573 <tr>
2545 <td>dead</td> 2574 <td>dead</td>
2546 <td>flag</td> 2575 <td>flag</td>
2547 <td> </td> 2576 <td> </td>
2548 <td> 2577 <td>
2549 2578 <p>Possibly true means mark dead and false unmark, but that's just a wild guess.</p>
2579
2550   2580  
2551 </td> 2581 </td>
2552 <td> 2582 <td>
2553 <b></b> 2583 <b></b>
2554   2584  
… …
2629 <tr> 2659 <tr>
2630 <td>id</td> 2660 <td>id</td>
2631 <td>U32</td> 2661 <td>U32</td>
2632 <td> </td> 2662 <td> </td>
2633 <td> 2663 <td>
2634 2664 <p>An id field (start at one please) to make sure that the client responds to the correct done click.</p>
2665
2635   2666  
2636 </td> 2667 </td>
2637 <td> 2668 <td>
2638 <b></b> 2669 <b></b>
2639   2670  
… …
3089 <tr> 3120 <tr>
3090 <td>cid</td> 3121 <td>cid</td>
3091 <td>CLIENTID8</td> 3122 <td>CLIENTID8</td>
3092 <td> </td> 3123 <td> </td>
3093 <td> 3124 <td>
3125 <p>Possibly an id. No idea. Better echo this from the challenge request.</p>
3094 3126
3095   3127  
3096 </td> 3128 </td>
3097 <td> 3129 <td>
3098 <b></b> 3130 <b></b>
… …
3345 <tr> 3377 <tr>
3346 <td>ruleset</td> 3378 <td>ruleset</td>
3347 <td>U8</td> 3379 <td>U8</td>
3348 <td> </td> 3380 <td> </td>
3349 <td> 3381 <td>
3382 <p>The ruleset member is a pure guess, please verify. it could also be after size for example.</p>
3350 3383
3351   3384  
3352 </td> 3385 </td>
3353 <td> 3386 <td>
3354 <b></b> 3387 <b></b>
… …
3950 <tr> 3983 <tr>
3951 <td>flags1</td> 3984 <td>flags1</td>
3952 <td>U8</td> 3985 <td>U8</td>
3953 <td> </td> 3986 <td> </td>
3954 <td> 3987 <td>
3988 <p>0:3 == handicap, 4:7 == gametype:0:4</p>
3955 3989
3956   3990  
3957 </td> 3991 </td>
3958 <td> 3992 <td>
3959 <b></b> 3993 <b></b>
… …
3992 <td>owner</td> 4026 <td>owner</td>
3993 <td>user</td> 4027 <td>user</td>
3994 <td> </td> 4028 <td> </td>
3995 <td> 4029 <td>
3996 4030
4031 <p>
4032 <p>Owner (or empty)</p>
4033
4034 <p>The bits 16-24 of black.flags and white.flags give the high and
4035 low bits of a revision number in case there are multiple similar
4036 games.</p>
4037 </p>
4038
3997 4039
3998   4040  
3999 </td> 4041 </td>
4000 <td> 4042 <td>
4001 <b></b> 4043 <b></b>
… …
4005 <tr> 4047 <tr>
4006 <td>flags2</td> 4048 <td>flags2</td>
4007 <td>U16</td> 4049 <td>U16</td>
4008 <td> </td> 4050 <td> </td>
4009 <td> 4051 <td>
4052 <p>0:11 == komi / 2, 12:14 == high 3 bits of gametype, 15: == sign bit</p>
4010 4053
4011   4054  
4012 </td> 4055 </td>
4013 <td> 4056 <td>
4014 <b></b> 4057 <b></b>
… …
4032 <td>flags3</td> 4075 <td>flags3</td>
4033 <td>U8</td> 4076 <td>U8</td>
4034 <td> </td> 4077 <td> </td>
4035 <td> 4078 <td>
4036 4079
4037 4080 <p>0:5 == boardsize; 6: == no idea; 7: == inplay?</p>
4081
4082
4038   4083  
4039 </td> 4084 </td>
4040 <td> 4085 <td>
4041 <b></b> 4086 <b></b>
4042   4087  
… …
4393 <td>lastlogin</td> 4438 <td>lastlogin</td>
4394 <td>timestamp</td> 4439 <td>timestamp</td>
4395 <td> </td> 4440 <td> </td>
4396 <td> 4441 <td>
4397 When the user logged in for the last time. 4442 When the user logged in for the last time.
4398 4443 <!-- maybe more? -->
4444
4399   4445  
4400 </td> 4446 </td>
4401 <td> 4447 <td>
4402 <b></b> 4448 <b></b>
4403   4449  
… …
5749 <tr> 5795 <tr>
5750 <td>gamerecord</td> 5796 <td>gamerecord</td>
5751 <td>game_record</td> 5797 <td>game_record</td>
5752 <td> </td> 5798 <td> </td>
5753 <td> 5799 <td>
5800 <p>Game result record?</p>
5754 5801
5802
5755   5803  
5756 </td> 5804 </td>
5757 <td> 5805 <td>
5758 <b>event</b> == 2 5806 <b>event</b> == 2
5759   5807  
… …
5913 <tr> 5961 <tr>
5914 <td>cid</td> 5962 <td>cid</td>
5915 <td>CLIENTID16</td> 5963 <td>CLIENTID16</td>
5916 <td> </td> 5964 <td> </td>
5917 <td> 5965 <td>
5918 5966 <p>The cid of the new_game etc. request.</p>
5967
5919   5968  
5920 </td> 5969 </td>
5921 <td> 5970 <td>
5922 <b></b> 5971 <b></b>
5923   5972  
… …
6215 <tr> 6264 <tr>
6216 <td>channel</td> 6265 <td>channel</td>
6217 <td>U16</td> 6266 <td>U16</td>
6218 <td> </td> 6267 <td> </td>
6219 <td> 6268 <td>
6269 <p>
6270 The room this game is associated with.
6271 </p>
6220 6272
6221   6273  
6222 </td> 6274 </td>
6223 <td> 6275 <td>
6224 <b></b> 6276 <b></b>
… …
6228 <tr> 6280 <tr>
6229 <td>game</td> 6281 <td>game</td>
6230 <td>game</td> 6282 <td>game</td>
6231 <td> </td> 6283 <td> </td>
6232 <td> 6284 <td>
6233 6285 <p>The game. The "moves" member contains a small number. Probably garbage.</p>
6286
6234   6287  
6235 </td> 6288 </td>
6236 <td> 6289 <td>
6237 <b></b> 6290 <b></b>
6238   6291  
… …
6579 <tr> 6632 <tr>
6580 <td>cid</td> 6633 <td>cid</td>
6581 <td>CLIENTID8</td> 6634 <td>CLIENTID8</td>
6582 <td> </td> 6635 <td> </td>
6583 <td> 6636 <td>
6637 <p>Possibly an id. No idea. Better echo this from the challenge request.</p>
6584 6638
6585   6639  
6586 </td> 6640 </td>
6587 <td> 6641 <td>
6588 <b></b> 6642 <b></b>
… …
6605 <tr> 6659 <tr>
6606 <td>notes</td> 6660 <td>notes</td>
6607 <td>STRING</td> 6661 <td>STRING</td>
6608 <td> </td> 6662 <td> </td>
6609 <td> 6663 <td>
6610 6664 <p>This field is optional</p>
6665
6611   6666  
6612 </td> 6667 </td>
6613 <td> 6668 <td>
6614 <b></b> 6669 <b></b>
6615   6670  
… …
6909 <tr> 6964 <tr>
6910 <td>id</td> 6965 <td>id</td>
6911 <td>U32</td> 6966 <td>U32</td>
6912 <td> </td> 6967 <td> </td>
6913 <td> 6968 <td>
6969 <p>An id field to make sure that the client responds to the correct done click.</p>
6970 <p>The high bit has the "please press done again" warning function, i.e. if set, opponent has changed board.</p>
6914 6971
6915   6972  
6916 </td> 6973 </td>
6917 <td> 6974 <td>
6918 <b></b> 6975 <b></b>
… …
7487 <tr> 7544 <tr>
7488 <td>cid</td> 7545 <td>cid</td>
7489 <td>CLIENTID8</td> 7546 <td>CLIENTID8</td>
7490 <td> </td> 7547 <td> </td>
7491 <td> 7548 <td>
7549 <p>Possibly an id. No idea. Better echo this from the challenge request.</p>
7492 7550
7493   7551  
7494 </td> 7552 </td>
7495 <td> 7553 <td>
7496 <b></b> 7554 <b></b>
… …
7684 <tr> 7742 <tr>
7685 <td>channel</td> 7743 <td>channel</td>
7686 <td>U16</td> 7744 <td>U16</td>
7687 <td> </td> 7745 <td> </td>
7688 <td> 7746 <td>
7747 <p>The newly created game.</p>
7689 7748
7690   7749  
7691 </td> 7750 </td>
7692 <td> 7751 <td>
7693 <b></b> 7752 <b></b>
… …
7697 <tr> 7756 <tr>
7698 <td>cid</td> 7757 <td>cid</td>
7699 <td>CLIENTID16</td> 7758 <td>CLIENTID16</td>
7700 <td> </td> 7759 <td> </td>
7701 <td> 7760 <td>
7702 7761 <p>The ID sent to the server in new_game.</p>
7762
7703   7763  
7704 </td> 7764 </td>
7705 <td> 7765 <td>
7706 <b></b> 7766 <b></b>
7707   7767  
… …
7882 <tr> 7942 <tr>
7883 <td>channel</td> 7943 <td>channel</td>
7884 <td>U16</td> 7944 <td>U16</td>
7885 <td> </td> 7945 <td> </td>
7886 <td> 7946 <td>
7947 <p>The game id to remove.</p>
7887 7948
7888   7949  
7889 </td> 7950 </td>
7890 <td> 7951 <td>
7891 <b></b> 7952 <b></b>
… …
7895 <tr> 7956 <tr>
7896 <td>game</td> 7957 <td>game</td>
7897 <td>U16</td> 7958 <td>U16</td>
7898 <td> </td> 7959 <td> </td>
7899 <td> 7960 <td>
7900 7961 <p>Probably the same. I suggest to use this id for no good reason.</p>
7962
7901   7963  
7902 </td> 7964 </td>
7903 <td> 7965 <td>
7904 <b></b> 7966 <b></b>
7905   7967  

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines