<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head><!-- Created on May, 18 2002 by texi2html 1.65 --><!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
-->
<title>GNU Go Documentation: GTP</title><meta name="description" content="GNU Go Documentation: GTP">
<meta name="keywords" content="GNU Go Documentation: GTP">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.65"></head>
<body lang="en" bgcolor="#ffffff" text="#000000" link="#0000ff" vlink="#800080" alink="#ff0000">
<a name="SEC207"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_20.html#SEC206"> < </a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC208"> > </a>]</td>
<td valign="middle" align="left"> � </td><td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_20.html#SEC206"> << </a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo.html#SEC_Top"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_22.html#SEC212"> >> </a>]</td>
<td valign="middle" align="left"> � </td><td valign="middle" align="left"> � </td><td valign="middle" align="left"> � </td><td valign="middle" align="left"> � </td><td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo.html#SEC_Top">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_toc.html#SEC_Contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_24.html#SEC224">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_abt.html#SEC_About"> ? </a>]</td>
</tr></tbody></table>
<h1> 20. The Go Text Protocol </h1>
<!--docid::SEC207::-->
<p>
</p><blockquote><table border="0" cellspacing="0">
<tbody><tr><td align="left" valign="top"><a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC208">20.1 The GNU Go Text Protocol</a></td><td>��</td><td align="left" valign="top">The Go Text Protocol</td></tr>
<tr><td align="left" valign="top"><a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC209">20.2 Protocol applications</a></td><td>��</td><td align="left" valign="top"></td></tr>
<tr><td align="left" valign="top"><a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC210">20.3 Protocol conventions</a></td><td>��</td><td align="left" valign="top"></td></tr>
<tr><td align="left" valign="top"><a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC211">20.4 Regression testing with GTP</a></td><td>��</td><td align="left" valign="top"></td></tr>
</tbody></table></blockquote>
<p>
<a name="The Go Text Protocol"></a>
</p><hr size="6">
<a name="SEC208"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC207"> < </a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC209"> > </a>]</td>
<td valign="middle" align="left"> � </td><td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC207"> << </a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC207"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_22.html#SEC212"> >> </a>]</td>
<td valign="middle" align="left"> � </td><td valign="middle" align="left"> � </td><td valign="middle" align="left"> � </td><td valign="middle" align="left"> � </td><td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo.html#SEC_Top">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_toc.html#SEC_Contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_24.html#SEC224">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_abt.html#SEC_About"> ? </a>]</td>
</tr></tbody></table>
<h2> 20.1 The GNU Go Text Protocol </h2>
<!--docid::SEC208::-->
<p>
GNU Go 3.0 introduces a new interface, the Go Text Protocol
(GTP). The intention is to make an interface that is better suited
for machine-machine communication than the ascii interface and
simpler, more powerful, and more flexible than the Go Modem
Protocol.
</p><p>
The GTP has two principal current applications: it is used
in the test suite (see section <a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_22.html#SEC212">21. Regression testing</a>) and it is used to
communicate with <code>gnugoclient</code>, which is not part
of the GNU Go distribution, but has been used to run GNU
Go on NNGS. Other potential uses might be any of the current
uses of the GMP, for which the GTP might serve as a replacement.
This would likely entail extension and standardization of
the protocol.
</p><p>
A sample GTP session may look as follows:
</p><p>
<table><tbody><tr><td>�</td><td class="example"><pre> hannah 2289% ./interface/gnugo --quiet --mode gtp
1 loadsgf regression/games/incident156.sgf 249
=1
2 countlib C3
=2 4
3 findlib C3
=3 C4 B3 D3 B2
5 attack C3
=5 0
owl_attack C3
= 1 B4
3 owl_defend C3
=3 1 B5
owl_attack A2
? vertex must not be empty
quit
=
</pre></td></tr></tbody></table></p><p>
By specifying `<samp>--mode gtp</samp>' GNU Go starts in the GTP
interface. No prompt is used, just start giving commands. The
commands have the common syntax
</p><p>
<table><tbody><tr><td>�</td><td class="example"><pre>[id] command_name [arguments]
</pre></td></tr></tbody></table></p><p>
The command is exactly one line long, i.e. it ends as soon as a
newline appears. It's 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.
</p><p>
If the command is successful, the response is of the form
</p><p>
<table><tbody><tr><td>�</td><td class="example"><pre>=[id] result
</pre></td></tr></tbody></table></p><p>
Here `<samp>=</samp>' indicates success and <code>id</code> 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.
</p><p>
If the command fails for some reason, the response takes the form
</p><p>
<table><tbody><tr><td>�</td><td class="example"><pre>?[id] error_message
</pre></td></tr></tbody></table></p><p>
Here `<samp>?</samp>' indicates failure, <code>id</code> is as before, and
<code>error_message</code> gives an explanation for the failure. This
string also ends with two consecutive newlines.
</p><p>
The available commands may always be listed using the single command
<code>help</code>. Currently this gives the list below.
</p><p>
<table><tbody><tr><td>�</td><td class="example"><pre>attack
black
boardsize
color
combination_attack
countlib
debug_influence
debug_move_influence
decrease_depths
defend
dragon_data
dragon_status
dump_stack
echo
eval_eye
final_score
findlib
fixed_handicap
genmove_black
genmove_white
get_life_node_counter
get_owl_node_counter
get_reading_node_counter
get_trymove_counter
gg_genmove
help
increase_depths
influence
is_legal
komi
level
loadsgf
move_influence
name
new_score
owl_attack
owl_defend
popgo
prisoners
quit
report_uncertainty
reset_life_node_counter
reset_owl_node_counter
reset_reading_node_counter
reset_trymove_counter
same_dragon
showboard
trymove
tune_move_ordering
version
white
worm_cutstone
worm_data
</pre></td></tr></tbody></table></p><p>
For exact specification of their arguments and results we refer to the
comments of the functions in `<tt>interface/play_gtp.c</tt>'.
</p><p>
<a name="Protocol applications"></a>
</p><hr size="6">
<a name="SEC209"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC208"> < </a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC210"> > </a>]</td>
<td valign="middle" align="left"> � </td><td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC207"> << </a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC207"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_22.html#SEC212"> >> </a>]</td>
<td valign="middle" align="left"> � </td><td valign="middle" align="left"> � </td><td valign="middle" align="left"> � </td><td valign="middle" align="left"> � </td><td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo.html#SEC_Top">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_toc.html#SEC_Contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_24.html#SEC224">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_abt.html#SEC_About"> ? </a>]</td>
</tr></tbody></table>
<h2> 20.2 Protocol applications </h2>
<!--docid::SEC209::-->
<p>
The protocol is asymmetric and involves two parties, which we may
call `<samp>A</samp>' and `<samp>B</samp>'. `<samp>A</samp>' is typically some kind of arbiter or
relay and `<samp>B</samp>' is a go engine. All communication is initiated by `<samp>A</samp>'
in form of commands, to which `<samp>B</samp>' responds.
</p><p>
Potential setups include:
</p><p>
</p><ol>
<li>Regression testing.
<table><tbody><tr><td>�</td><td class="display"><pre style="font-family: serif;">A (regression script) -- B (engine).
</pre></td></tr></tbody></table><blockquote>
A sets up a board position and asks B to e.g. generate a move or
find an attack on a specific string.
</blockquote>
</li><li>Human vs program.
<table><tbody><tr><td>�</td><td class="display"><pre style="font-family: serif;">A (GUI) -- B (engine)
</pre></td></tr></tbody></table><blockquote>
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.
</blockquote>
</li><li>Program vs program with arbiter.
<table><tbody><tr><td>�</td><td class="display"><pre style="font-family: serif;">B1 (engine 1) -- A (arbiter) -- B2 (engine 2)
</pre></td></tr></tbody></table><blockquote>
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.
</blockquote>
</li><li>Program vs program without arbiter.
<blockquote>
The same as above except that B1 includes the arbiter
functionality and the first GTP link is shortcut.
</blockquote>
</li><li>Connection between go server and program.
<table><tbody><tr><td>�</td><td class="display"><pre style="font-family: serif;">Go server -- A (relay) -- B (engine)
</pre></td></tr></tbody></table><blockquote>
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.
</blockquote>
</li></ol>
<p>
Setups 1 and 5 are in active and regular use with GNU Go. Programs
implementing setup 3 are also distributed with GNU Go (the files
`<tt>interface/gtp_examples/twogtp</tt>' and
`<tt>interface/gtp_examples/2ptkgo.pl</tt>').
</p><p>
<a name="Protocol conventions"></a>
</p><hr size="6">
<a name="SEC210"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC209"> < </a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC211"> > </a>]</td>
<td valign="middle" align="left"> � </td><td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC207"> << </a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC207"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_22.html#SEC212"> >> </a>]</td>
<td valign="middle" align="left"> � </td><td valign="middle" align="left"> � </td><td valign="middle" align="left"> � </td><td valign="middle" align="left"> � </td><td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo.html#SEC_Top">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_toc.html#SEC_Contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_24.html#SEC224">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_abt.html#SEC_About"> ? </a>]</td>
</tr></tbody></table>
<h2> 20.3 Protocol conventions </h2>
<!--docid::SEC210::-->
<p>
The GTP is currently unfinished and unstandardized. It is hoped that it
will grow to fill the needs currently served by the GMP and perhaps
other functions. As it is yet unstandardized, this section gives some
general remarks which we hope will constrain its development. We also
discuss how the GTP is implemented in GNU Go, for the benefit of anyone
wishing to add new commands. Notice that the current set of GTP commands
is a mix of generally useful ones and highly GNU Go specific ones. Only
the former should be part of a standardized protocol while the latter
should be private extensions.
</p><p>
The purpose of the protocol is machine-machine communication. It may be
tempting to modify the protocol so that it becomes more comfortable for
the human user, for example with an automatic showboard after every
move. <strong>This is absolutely not the purpose of the protocol!</strong>
Use the ascii interface instead if you're inclined to make such a
change.
</p><p>
Newlines are implemented differently on different operating
systems. On Unix, a newline is just a line feed LF (ascii \012).
On DOS/Windows it is CRLF (\013\012). Thus whether GNU Go
sends a carriage return with the line feed depends on which
platform it is compiled for. The arbiter should silently
discard carriage returns.
</p><p>
Applications using GTP should never have to guess about the basic
structure of the responses, defined above. The basic construction for
coding a GTP command can be found in <code>gtp_countlib()</code>:
</p><p>
<table><tbody><tr><td>�</td><td class="example"><pre>static int
gtp_countlib(char *s, int id)
{
int i, j;
if (!gtp_decode_coord(s, &i, &j))
return gtp_failure(id, "invalid coordinate");
if (p[i][j] == EMPTY)
return gtp_failure(id, "vertex must not be empty");
return gtp_success(id, "%d", countlib(POS(i, j)));
}
</pre></td></tr></tbody></table></p><p>
The functions <code>gtp_failure()</code> and <code>gtp_success()</code>
automatically ensures the specified response format, assuming the
strings they are printing do not end with a newline.
</p><p>
Sometimes the output is too complex for use with gtp_success, e.g. if
we want to print vertices, which gtp_success() doesn't
support. Then we have to fall back to the construction in e.g.
<code>gtp_genmove_white()</code>:
</p><p>
<table><tbody><tr><td>�</td><td class="example"><pre>static int
gtp_genmove_white(char *s, int id)
{
int i, j;
UNUSED(s);
if (genmove(&i, &j, WHITE) >= 0)
play_move(POS(i, j), WHITE);
gtp_printid(id, GTP_SUCCESS);
gtp_print_vertex(i, j);
return gtp_finish_response();
}
</pre></td></tr></tbody></table></p><p>
Here <code>gtp_printid()</code> writes the equal sign and the request id while
<code>gtp_finish_response()</code> adds the final two newlines. The next example
is from <code>gtp_influence()</code>:
</p><p>
<table><tbody><tr><td>�</td><td class="example"><pre> gtp_printid(id, GTP_SUCCESS);
get_initial_influence(color, 1, white_influence,
black_influence, influence_regions);
print_influence(white_influence, black_influence, influence_regions);
/* We already have one newline, thus can't use gtp_finish_response(). */
gtp_printf("\n");
return GTP_OK;
</pre></td></tr></tbody></table></p><p>
As we have said, the response should be finished with two newlines.
Here we have to finish up the response ourselves since we already have
one newline in place.
</p><p>
One problem that can be expected to be common is that an engine
happens to finish its response with three (or more) rather than
two consecutive newlines. This is an error by the engine that
the controller can easily detect and ignore. Thus a well
behaved engine should not send stray newlines, but should they
appear the controller should ignore them. The opposite problem
of an engine failing to properly finish its response with two
newlines will result in deadlock. Don't do this mistake!
</p><p>
Although it doesn't suffice in more complex cases, gtp_success() is by
far the most convenient construction when it does. For example,
the function <code>gtp_report_uncertainty</code> takes a single argument
which is expected to be "on" or "off", after which it sets the
value of <code>report_uncertainty</code>, a variable which affects
the form of future GTP responses, reports success, and exits. The
function is coded thus:
</p><p>
<table><tbody><tr><td>�</td><td class="example"><pre>static int
gtp_report_uncertainty(char *s, int id)
{
if (!strncmp(s, "on", 2)) {
report_uncertainty = 1;
return gtp_success(id, "");
}
if (!strncmp(s, "off", 3)) {
report_uncertainty = 0;
return gtp_success(id, "");
}
return gtp_failure(id, "invalid argument");
}
</pre></td></tr></tbody></table></p><p>
<a name="Regression with GTP"></a>
</p><hr size="6">
<a name="SEC211"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC210"> < </a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_22.html#SEC212"> > </a>]</td>
<td valign="middle" align="left"> � </td><td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC207"> << </a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC207"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_22.html#SEC212"> >> </a>]</td>
<td valign="middle" align="left"> � </td><td valign="middle" align="left"> � </td><td valign="middle" align="left"> � </td><td valign="middle" align="left"> � </td><td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo.html#SEC_Top">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_toc.html#SEC_Contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_24.html#SEC224">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_abt.html#SEC_About"> ? </a>]</td>
</tr></tbody></table>
<h2> 20.4 Regression testing with GTP </h2>
<!--docid::SEC211::-->
<p>
GNU Go uses GTP for regression testing. These tests are implemented as
files with GTP commands, which are fed to GNU Go simply by redirecting
stdin to read from a file. The output is filtered so that equal signs
and responses from commands without id numbers are removed. These
results are then compared with expected results encoded in GTP comments
in the file, using matching with regular expressions. More information
can be found in the regression chapter (see section <a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_22.html#SEC212">21. Regression testing</a>).
</p><p>
<a name="Regression"></a>
</p><hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_21.html#SEC207"> << </a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_22.html#SEC212"> >> </a>]</td>
<td valign="middle" align="left"> � </td><td valign="middle" align="left"> � </td><td valign="middle" align="left"> � </td><td valign="middle" align="left"> � </td><td valign="middle" align="left"> � </td><td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo.html#SEC_Top">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_toc.html#SEC_Contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_24.html#SEC224">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://www.uni-bonn.de/%7Euzsxtn/gnugo_abt.html#SEC_About"> ? </a>]</td>
</tr></tbody></table>
<br>
<font size="-1">
This document was generated
on <i>May, 18 2002</i>
using <a href="http://www.mathematik.uni-kl.de/%7Eobachman/Texi2html"><i>texi2html</i></a>
</font>
</body></html>