| 1 | |
| 2 | @menu |
| 3 | * The Go Text Protocol:: The Go Text Protocol |
| 4 | * Running in GTP mode:: Running GNU Go in GTP mode |
| 5 | * GTP applications:: GTP applications |
| 6 | * The Metamachine:: The Metamachine |
| 7 | * Adding new GTP commands:: Adding new GTP commands |
| 8 | * GTP command reference:: Details on every GTP command |
| 9 | @end menu |
| 10 | |
| 11 | @node The Go Text Protocol |
| 12 | @section The Go Text Protocol |
| 13 | |
| 14 | GNU Go 3.0 introduced a new interface, the Go Text Protocol, abbreviated |
| 15 | GTP. The intention was to make an interface that is better suited for |
| 16 | machine-machine communication than the ascii interface and simpler, more |
| 17 | powerful, and more flexible than the Go Modem Protocol. |
| 18 | |
| 19 | There are two versions of the protocol. Version 1 was used with GNU Go |
| 20 | 3.0 and 3.2. GNU Go 3.4 and later versions use protocol version 2. The |
| 21 | specification of GTP version 2 is available at |
| 22 | @url{http://www.lysator.liu.se/~gunnar/gtp/}. GNU Go 3.4 is the |
| 23 | reference implementation for GTP version 2, but all but the most common |
| 24 | commands are to be regarded as private extensions of the protocol. |
| 25 | |
| 26 | The GTP has a variety of applications. For GNU Go the first use was in |
| 27 | regression testing (@pxref{Regression}), followed by communication with |
| 28 | the NNGS go server and for automated test games against itself and other |
| 29 | programs. Now there are also many graphical user interfaces available |
| 30 | supporting GTP, as well as bridges to other Go servers than NNGS. |
| 31 | |
| 32 | @node Running in GTP mode |
| 33 | @section Running GNU Go in GTP mode |
| 34 | |
| 35 | To start GNU Go in GTP mode, simply invoke it with the option |
| 36 | @option{--mode gtp}. You will not get a prompt or any other output to |
| 37 | start with but GNU Go is silently waiting for GTP commands. |
| 38 | |
| 39 | A sample GTP session may look as follows: |
| 40 | |
| 41 | @example |
| 42 | virihaure 462% ./gnugo --mode gtp |
| 43 | 1 boardsize 7 |
| 44 | =1 |
| 45 | |
| 46 | 2 clear_board |
| 47 | =2 |
| 48 | |
| 49 | 3 play black D5 |
| 50 | =3 |
| 51 | |
| 52 | 4 genmove white |
| 53 | =4 C3 |
| 54 | |
| 55 | 5 play black C3 |
| 56 | ?5 illegal move |
| 57 | |
| 58 | 6 play black E3 |
| 59 | =6 |
| 60 | |
| 61 | 7 showboard |
| 62 | =7 |
| 63 | A B C D E F G |
| 64 | 7 . . . . . . . 7 |
| 65 | 6 . . . . . . . 6 |
| 66 | 5 . . + X + . . 5 |
| 67 | 4 . . . + . . . 4 |
| 68 | 3 . . O . X . . 3 |
| 69 | 2 . . . . . . . 2 WHITE (O) has captured 0 stones |
| 70 | 1 . . . . . . . 1 BLACK (X) has captured 0 stones |
| 71 | A B C D E F G |
| 72 | |
| 73 | 8 quit |
| 74 | =8 |
| 75 | |
| 76 | @end example |
| 77 | |
| 78 | Commands are given on a single line, starting by an optional identity |
| 79 | number, followed by the command name and its arguments. |
| 80 | |
| 81 | If the command is successful, the response starts by an equals sign |
| 82 | (@samp{=}), followed by the identity number of the command (if any) and |
| 83 | then the result. In this example all results were empty strings except |
| 84 | for command 4 where the answer was the white move at C3, and command 7 |
| 85 | where the result was a diagram of the current board position. The |
| 86 | response ends by two consecutive newlines. |
| 87 | |
| 88 | Failing commands are signified by a question mark (@samp{?}) instead of |
| 89 | an equals sign, as in the response to command 5. |
| 90 | |
| 91 | The detailed specification of the protocol can be found at |
| 92 | @url{http://www.lysator.liu.se/~gunnar/gtp/}. The available commands in |
| 93 | GNU Go may always be listed using the command @command{list_commands}. |
| 94 | They are also documented in @xref{GTP command reference}. |
| 95 | |
| 96 | |
| 97 | @node GTP applications |
| 98 | @section GTP applications |
| 99 | |
| 100 | GTP is an asymmetric protocol involving two parties which we call |
| 101 | controller and engine. The controller sends all commands and the engine |
| 102 | only responds to these commands. GNU Go implements the engine end of the |
| 103 | protocol. |
| 104 | |
| 105 | With the source code of GNU Go is also distributed a number of |
| 106 | applications implementing the controller end. Among the most interesting of |
| 107 | these are: |
| 108 | |
| 109 | @itemize |
| 110 | @item @file{regression/regress.awk} |
| 111 | @quotation |
| 112 | Script to run regressions. The script sends GTP commands to set up and |
| 113 | evaluate positions to the engine and then analyzes the responses from |
| 114 | the engine. More information about GTP based regression testing can be |
| 115 | found in the regression chapter (@pxref{Regression}). |
| 116 | @end quotation |
| 117 | @item @file{regression/regress.pl} |
| 118 | @quotation |
| 119 | Perl script to run regressions, giving output which together with the |
| 120 | CGI script @file{regression/regress.plx} generates HTML views of the |
| 121 | regressions. |
| 122 | @end quotation |
| 123 | @item @file{regression/regress.pike} |
| 124 | @quotation |
| 125 | Pike script to run regressions. More feature-rich and powerful than |
| 126 | @file{regress.awk}. |
| 127 | @end quotation |
| 128 | @item @file{regression/view.pike} |
| 129 | @quotation |
| 130 | Pike script to examine a single regression testcase through a graphical |
| 131 | board. This gives an easy way to inspect many of the GNU Go internals. |
| 132 | @end quotation |
| 133 | @item @file{interface/gtp_examples/twogtp} |
| 134 | @quotation |
| 135 | Perl script to play two engines against each other. The script |
| 136 | essentially sets up both engines with desired boardsize, handicap, and |
| 137 | komi, then relays moves back and forth between the engines. |
| 138 | @end quotation |
| 139 | @item @file{interface/gtp_examples/twogtp-a} |
| 140 | @quotation |
| 141 | An alternative Perl implementation of twogtp. |
| 142 | @end quotation |
| 143 | @item @file{interface/gtp_examples/twogtp.py} |
| 144 | @quotation |
| 145 | Implementation of twogtp in Python. Has more features than the Perl |
| 146 | variants. |
| 147 | @end quotation |
| 148 | @item @file{interface/gtp_examples/twogtp.pike} |
| 149 | @quotation |
| 150 | Implementation of twogtp in Pike. Has even more features than the Python |
| 151 | variant. |
| 152 | @end quotation |
| 153 | @item @file{interface/gtp_examples/2ptkgo.pl} |
| 154 | @quotation |
| 155 | Variation of twogtp which includes a graphical board. |
| 156 | @end quotation |
| 157 | @end itemize |
| 158 | |
| 159 | More GTP applications, including bridges to go servers and graphical |
| 160 | user interfaces, are listed at |
| 161 | @url{http://www.lysator.liu.se/~gunnar/gtp/}. |
| 162 | |
| 163 | @node The Metamachine |
| 164 | @section The Metamachine |
| 165 | |
| 166 | An interesting application of the GTP is the concept of |
| 167 | using GNU Go as an ``Oracle'' that can be consulted by another |
| 168 | process. This could be another computer program that asks GNU Go |
| 169 | to generate future board positions, then evaluate them. |
| 170 | |
| 171 | David Doshay at the University of California at Santa Cruz has done |
| 172 | interesting experiments with a parallel engine, known as SlugGo, that is based |
| 173 | on GNU Go. These are described in |
| 174 | @url{http://lists.gnu.org/archive/html/gnugo-devel/2004-08/msg00060.html}. |
| 175 | |
| 176 | The ``Metamachine'' experiment is a more modest approach using the GTP to |
| 177 | communicate with a GNU Go process that is used as an oracle. The following |
| 178 | scheme is used. |
| 179 | |
| 180 | @itemize @bullet |
| 181 | @item The GNU Go ``oracle'' is asked to generate its top moves using |
| 182 | the GTP @code{top_moves} commands. |
| 183 | @item Both moves are tried and @code{estimate_score} is called |
| 184 | from the resulting board position. |
| 185 | @item The higher scoring position is selected as the engine's move. |
| 186 | @end itemize |
| 187 | |
| 188 | This scheme does not produce a stronger engine, but it is |
| 189 | suggestive, and the SlugGo experiment seems to show that a |
| 190 | more elaborate scheme along the same lines could produce |
| 191 | a stronger engine. |
| 192 | |
| 193 | Two implementations are distributed with GNU Go. Both make use of |
| 194 | @command{fork} and @command{pipe} system calls, so they require a Unix-like |
| 195 | environment. The Metamachine has been tested under GNU/Linux. |
| 196 | |
| 197 | @strong{Important:} If the Metamachine terminates normally, the GNU Go |
| 198 | process will be killed. However there is a danger that |
| 199 | something will go wrong. When you are finished running the |
| 200 | Metamachine, it is a good idea to run @command{ps -A|grep gnugo} |
| 201 | or @command{ps -aux|grep gnugo} to make sure there are no |
| 202 | unterminated processes. (If there are, just kill them.) |
| 203 | |
| 204 | @subsection The Standalone Metamachine |
| 205 | |
| 206 | In @file{interface/gtp_examples/metamachine.c} is a standalone |
| 207 | implementation of the Metamachine. Compile it with |
| 208 | @command{cc -o metamachine metamachine.c} and run it. It forks |
| 209 | a @code{gnugo} process with which it communicates through the |
| 210 | GTP, to use as an oracle. |
| 211 | |
| 212 | The following scheme is followed: |
| 213 | |
| 214 | @example |
| 215 | stdin pipe a |
| 216 | GTP client ----> Metamachine -----> GNU Go |
| 217 | <---- <----- |
| 218 | stdout pipe b |
| 219 | @end example |
| 220 | |
| 221 | Most commands issued by the client are passed along |
| 222 | verbatim to GNU Go by the Metamachine. The exception |
| 223 | is gg_genmove, which is intercepted then processed differently, |
| 224 | as described above. The client is unaware of this, and only |
| 225 | knows that it issued a gg_genmove command and received a reply. |
| 226 | Thus to the the Metamachine appears as an ordinary GTP engine. |
| 227 | |
| 228 | Usage: no arguments gives normal GTP behavior. |
| 229 | @command{metamachine --debug} sends diagnostics to stderr. |
| 230 | |
| 231 | @subsection GNU Go as a Metamachine |
| 232 | |
| 233 | Alternatively, you may compile GNU Go with the configure option |
| 234 | @option{--enable-metamachine}. This causes the file |
| 235 | @code{oracle.c} to be compiled, which contains the Metamachine |
| 236 | code. This has no effect on the engine unless you run GNU |
| 237 | Go with the runtime option @option{--metamachine}. Thus |
| 238 | you must use both the configure and the runtime option |
| 239 | to get the Metamachine. |
| 240 | |
| 241 | This method is better than the standalone program since |
| 242 | you have access to GNU Go's facilities. For example, you |
| 243 | can run the Metamachine with CGoban or in Ascii mode this |
| 244 | way. |
| 245 | |
| 246 | You can get traces by adding the command line |
| 247 | @option{-d0x1000000}. In debugging the Metamachine, a danger is |
| 248 | that any small oversight in designing the program can cause the |
| 249 | forked process and the controller to hang, each one waiting for |
| 250 | a response from the other. If this seems to happen it is useful |
| 251 | to know that you can attach @code{gdb} to a running process and |
| 252 | find out what it is doing. |
| 253 | |
| 254 | @node Adding new GTP commands |
| 255 | @section Adding new GTP commands |
| 256 | |
| 257 | The implementation of GTP in GNU Go is distributed over three files, |
| 258 | @file{interface/gtp.h}, @file{interface/gtp.c}, and |
| 259 | @file{interface/play_gtp.c}. The first two implement a small library of |
| 260 | helper functions which can be used also by other programs. In the |
| 261 | interest of promoting the GTP they are licensed with minimal |
| 262 | restrictions (@pxref{GTP License}). The actual GTP commands are |
| 263 | implemented in @file{play_gtp.c}, which has knowledge about the engine |
| 264 | internals. |
| 265 | |
| 266 | To see how a simple but fairly typical command is implemented we look at |
| 267 | @code{gtp_countlib()} (a GNU Go private extension command): |
| 268 | |
| 269 | @example |
| 270 | static int |
| 271 | gtp_countlib(char *s) |
| 272 | @{ |
| 273 | int i, j; |
| 274 | if (!gtp_decode_coord(s, &i, &j)) |
| 275 | return gtp_failure("invalid coordinate"); |
| 276 | |
| 277 | if (BOARD(i, j) == EMPTY) |
| 278 | return gtp_failure("vertex must not be empty"); |
| 279 | |
| 280 | return gtp_success("%d", countlib(POS(i, j))); |
| 281 | @} |
| 282 | @end example |
| 283 | |
| 284 | The arguments to the command are passed in the string @code{s}. In this |
| 285 | case we expect a vertex as argument and thus try to read it with |
| 286 | @code{gtp_decode_coord()} from @file{gtp.c}. |
| 287 | |
| 288 | A correctly formatted response should start with either @samp{=} or |
| 289 | @samp{?}, followed by the identity number (if one was sent), the actual |
| 290 | result, and finally two consecutive newlines. It is important to get |
| 291 | this formatting correct since the controller in the other end relies on |
| 292 | it. Naturally the result itself cannot contain two consecutive newlines |
| 293 | but it may be split over several lines by single newlines. |
| 294 | |
| 295 | The easiest way to generate a correctly formatted response is with one |
| 296 | of the functions @code{gtp_failure()} and @code{gtp_success()}, assuming |
| 297 | that their formatted output does not end with a newline. |
| 298 | |
| 299 | Sometimes the output is too complex for use with gtp_success, e.g. if |
| 300 | we want to print vertices, which gtp_success() does not |
| 301 | support. Then we have to fall back to the construction in e.g. |
| 302 | @code{gtp_genmove()}: |
| 303 | |
| 304 | @example |
| 305 | static int |
| 306 | gtp_genmove(char *s) |
| 307 | @{ |
| 308 | [...] |
| 309 | gtp_start_response(GTP_SUCCESS); |
| 310 | gtp_print_vertex(i, j); |
| 311 | return gtp_finish_response(); |
| 312 | @} |
| 313 | @end example |
| 314 | |
| 315 | Here @code{gtp_start_response()} writes the equal sign and the identity |
| 316 | number while @code{gtp_finish_response()} adds the final two newlines. |
| 317 | The next example is from @code{gtp_list_commands()}: |
| 318 | |
| 319 | @example |
| 320 | static int |
| 321 | gtp_list_commands(char *s) |
| 322 | @{ |
| 323 | int k; |
| 324 | UNUSED(s); |
| 325 | |
| 326 | gtp_start_response(GTP_SUCCESS); |
| 327 | |
| 328 | for (k = 0; commands[k].name != NULL; k++) |
| 329 | gtp_printf("%s\n", commands[k].name); |
| 330 | |
| 331 | gtp_printf("\n"); |
| 332 | return GTP_OK; |
| 333 | @} |
| 334 | @end example |
| 335 | |
| 336 | As we have said, the response should be finished with two newlines. |
| 337 | Here we have to finish up the response ourselves since we already have |
| 338 | one newline in place from the last command printed in the loop. |
| 339 | |
| 340 | In order to add a new GTP command to GNU Go, the following pieces of |
| 341 | code need to be inserted in @file{play_gtp.c}: |
| 342 | @enumerate |
| 343 | @item A function declaration using the @code{DECLARE} macro in the list |
| 344 | starting at line 68. |
| 345 | @item An entry in the @code{commands[]} array starting at line 200. |
| 346 | @item An implementation of the function handling the command. |
| 347 | @end enumerate |
| 348 | |
| 349 | Useful helper functions in @file{gtp.c}/@file{gtp.h} are: |
| 350 | @itemize |
| 351 | @item @code{gtp_printf()} for basic formatted printing. |
| 352 | @item @code{gtp_mprintf()} for printing with special format codes for |
| 353 | vertices and colors. |
| 354 | @item @code{gtp_success()} and @code{gtp_failure()} for simple responses. |
| 355 | @item @code{gtp_start_response()} and @code{gtp_end_response()} for more |
| 356 | complex responses. |
| 357 | @item @code{gtp_print_vertex()} and @code{gtp_print_vertices()} for |
| 358 | printing one or multiple vertices. |
| 359 | @item @code{gtp_decode_color()} to read in a color from the command arguments. |
| 360 | @item @code{gtp_decode_coord()} to read in a vertex from the command arguments. |
| 361 | @item @code{gtp_decode_move()} to read in a move, i.e. color plus |
| 362 | vertex, from the command arguments. |
| 363 | @end itemize |
| 364 | |
| 365 | |
| 366 | @node GTP command reference |
| 367 | @section GTP command reference |
| 368 | @cindex GTP command reference |
| 369 | |
| 370 | This section lists the GTP commands implemented in GNU Go along with |
| 371 | some information about each command. Each entry in the list has the |
| 372 | following fields: |
| 373 | |
| 374 | @itemize @bullet |
| 375 | @item Function: What this command does. |
| 376 | @item Arguments: What other information, if any, this command requires. |
| 377 | Typical values include @dfn{none} or @dfn{vertex} or @dfn{integer} (there |
| 378 | are others). |
| 379 | @item Fails: Circumstances which cause this command to fail. |
| 380 | @item Returns: What is displayed after the @dfn{=} and before the two |
| 381 | newlines. Typical values include @dfn{nothing} or @dfn{a move coordinate} |
| 382 | or some status string (there are others). |
| 383 | @item Status: How this command relates to the standard GTP version 2 |
| 384 | commands. If nothing else is specified it is a GNU Go private extension. |
| 385 | @end itemize |
| 386 | |
| 387 | Without further ado, here is the big list (in no particular order). |
| 388 | |
| 389 | Note: if new commands are added by editing @file{interface/play_gtp.c} this |
| 390 | list could become incomplete. You may rebuild this list in |
| 391 | @file{doc/gtp-commands.texi} with the command @command{make gtp-commands} |
| 392 | in the @file{doc/} directory. This may require GNU sed. |
| 393 | |
| 394 | @itemize @bullet |
| 395 | @include gtp-commands.texi |
| 396 | @end itemize |