GNU Go implements a Go Text Protocol which could potentially serve as a replacement for the GMP. Here is a brief description. Other material can be found in the GNU Go Texinfo documentation. To: computer-go@lists.uoregon.edu Cc: gnugo@gnu.org Subject: Re: computer-go: Computer Go Tournament Program In-Reply-To: Your message of "Sun, 01 Jul 2001 14:34:13 PDT." <200107012134.OAA30810@match.Stanford.EDU> Date: Mon, 02 Jul 2001 17:48:28 +0200 From: Gunnar Farneback Daniel Bump wrote: > Bob Myers wrote: > > > Could you please point us to the best quick reference for the Go Text > > Protocol? Thanks. > > The protocol is under development. So far it has been mainly developed > by Gunnar Farneback for use with GNU Go. Its uses include (1) our > regression test suite and (2) communication with gnugoclient. Other > uses seem possible, such as a replacement for GMP and perhaps as a > client-server protocol. Such uses would undoubtedly require extending > the protocol. > > The documentation is in the GNU Go 2.7.244 Texinfo documentation. > But I just looked at what's there and it's rather brief. The main characteristics of the protocol are as follows: * The protocol is asymmetric and involves two parties, which we may call A and B. A is typically some kind of arbiter or relay and B is a go engine. All communication is initiated by A in form of commands, to which B respond. Potential setups include: 1. Regression testing. A (regression script) -- B (engine) A sets up a board position and asks B to e.g. generate a move or find an attack on a specific string. 2. Human vs program. A (GUI) -- B (engine) The GUI relays moves between the human and the engine and asks the engine to generate moves. Optionally the GUI may also use GTP to ask the engine which moves are legal or give a score when the game is finished. 3. Program vs program with arbiter. B1 (engine 1) -- A (arbiter) -- B2 (engine 2) A relays moves between the two engines and alternately asks the engines to generate moves. This involves two different GTP channels, the first between A and B1, and the second between A and B2. There is no direct communication between B1 and B2. The arbiter dictates board size, komi, rules, etc. 4. Program vs program without arbiter. The same as above except that B1 includes the arbiter functionality and the first GTP link is shortcut. 5. Connection between go server and program. Go server -- A (relay) -- B (engine) A talks with a go server using whatever protocol is needed and listens for match requests. When one arrives it accepts it, starts the go engine and issues GTP commands to set up board size, komi, etc. and if a game is restarted it also sets up the position. Then it relays moves between the server and the engine and asks the engine to generate new moves when it is in turn. Setups 1 and 5 are in active and regular use with GNU Go. A program implementing setup 3 is also distributed with GNU Go (the file interface/twogtp). * All communication is done in plain text. Although the protocol is foremost intended for machine-machine communication, some compromises have been made to also make it easy for humans to parse it. This includes consistently using standard coordinates on the form A1--T19 to designate board vertices, rather than e.g. two numbers for higher generality and somewhat simpler machine parsing or two letters (like SGF) for higher compactness. The benefits of this is that it becomes easy to debug protocol implementations, it is easy to write regression tests, and the protocol is practically useful for interactive examination of the workings of the engine. * The protocol has a well specified basic structure which is easy to parse and practical to use. More specifically all commands have the form [id] command_name [arguments] The command is exactly one line long, i.e. it ends as soon as a newline appears. It is not possible to give multiple commands on the same line. Before the command name an optional identity number can be specified. If present it must be an integer between 0 and 2^31-1. The id numbers may come in any order or be reused. The rest of the line after the command name is assumed to be arguments for the command. Empty lines are ignored, as is everything following a hash sign up to the end of the line. If the command is successful, the response takes the form =[id] result Here '=' indicates success and id is the identity number given in the command, or the empty string if the id was omitted. This is followed by the result, which is a text string ending with *two* consecutive newlines. If the command fails for some reason, the response takes the form ?[id] error_message Here '?' indicates failure, id is as before, and error_message gives an explanation of the failure. This string also ends with two consecutive newlines. To give an example of how this may look in practice, below is the complete GTP communication for a short 9x9 game played on NNGS, which was resumed at move 19. Lines starting with "> " designate commands given by the connecting program and those with "< " the responses from the engine. > 1 boardsize 9 > 2 komi 0.5 > 3 name < =1 < < =2 < < =3 GNU Go < > 4 version < =4 2.7.243 < > 5 black f5 > 6 white f3 > 7 black d5 > 8 white c3 > 9 black b5 > 10 white h3 > 11 black h5 > 12 white e3 > 13 black c4 > 14 white b3 > 15 black d3 > 16 white d2 > 17 black d4 > 18 white g4 < =5 < < =6 < < =7 < < =8 < < =9 < < =10 < < =11 < < =12 < < =13 < < =14 < < =15 < < =16 < < =17 < < =18 < > 19 black g5 > 20 genmove_white < =19 < < =20 H4 < > 21 black j4 > 22 genmove_white < =21 < < =22 B4 < > 23 black a4 > 24 genmove_white < =23 < < =24 J3 < > 25 black j5 > 26 genmove_white < =25 < < =26 A3 < > 27 black a5 > 28 genmove_white < =27 < < =28 E4 < > 29 black e5 > 30 genmove_white < =29 < < =30 F4 < > 31 black e2 > 32 genmove_white < =31 < < =32 C2 < > 33 black f2 > 34 genmove_white < =33 < < =34 G2 < > 35 black pass > 36 genmove_white < =35 < < =36 PASS < > 37 final_score < =37 B+18.5 < > 38 final_status_list dead < =38 E2 F2 < > 39 final_status_list seki < =39 < > 40 quit < =40 < The score and status commands are used for automatic removal of dead stones, but this can be turned off if the program is not trusted to decide this itself. The name and version commands are only needed for inclusion in the sgf file produced by the program connecting to NNGS. For reference, this is how the sgf file for this game looks: (;GM[1]FF[4] SZ[9]HA[0]KM[0.5] PW[GnuGo (GNU Go 2.7.243)]WR[15k*] PB[gunnar]BR[3k] PC[NNGS]DT[2001-07-02]AP[gnugoclient:1.9] RE[B+18.5] ;B[fe];W[fg];B[de];W[cg];B[be];W[hg];B[he];W[eg];B[cf];W[bg];B[dg] ;W[dh];B[df];W[gf];B[ge];W[hf];B[if];W[bf];B[af];W[ig];B[ie];W[ag] ;B[ae];W[ef];B[ee];W[ff];B[eh];W[ch];B[fh];W[gh];B[];W[] C[final_score: B+18.5 E2 removed]) * A publicly available reference implementation is provided through the GNU Go sources, which can be downloaded from http://www.gnu.org/software/gnugo/devel.html The commands are implemented in the file interface/play_gtp.c and documentation of how they work and what they return is provided in the comments above the functions. Supporting code is available in interface/gtp.c and interface/gtp.h. Documentation is available in doc/gtp.texi. The use of GTP for regression testing is documented in doc/regression.texi and the actual regression files reside in the regression directory. The current set of implemented commands is a mix of generally useful ones and highly GNU Go specific ones. A standardization of the protocol would of course only include the former, with the latter as private extensions. Implementations of this protocol in programming languages with good string support should be absolutely trivial. Programs written in C may benefit from reusing the code in interface/gtp.c and interface/gtp.h. In order to make this possible also for programs which are distributed in ways not compatible with the GNU GPL (which GNU Go is distributed under) we plan to dual license those two files with some very nonrestrictive license in addition to the GPL. The details of this have not yet been worked out though. Final comments: Some of the commands used in the examples above are not included in the current GNU Go development release but may be expected in version 2.7.245. The program for connecting to NNGS is known as gnugoclient and a new version using GTP to communicate with the engine is about to be released within a few days.