[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

19. The Go Text Protocol

19.1 The GNU Go Text Protocol  The Go Text Protocol
19.2 Protocol applications  
19.3 Protocol conventions  
19.4 Regression testing with GTP  
19.5 GTP command reference  Details on every GTP command


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

19.1 The GNU Go Text Protocol

GNU Go 3.0 introduced 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.

There are two versions of the protocol. Version 1 was used with GNU Go 3.0 and 3.2. GNU Go 3.4 uses version 2. The specification is available at http:http://www.lysator.liu.se/~gunnar/gtp/.

The GTP has two principal current applications: it is used in the test suite (see section 20. Regression testing) and it is used to communicate with gnugoclient, 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.

A sample GTP session may look as follows:

 
  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
  = 

By specifying `--mode gtp' GNU Go starts in the GTP interface. No prompt is used, just start giving commands. The commands have the common syntax

 
[id] command_name [arguments]

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.

If the command is successful, the response is of 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 for the failure. This string also ends with two consecutive newlines.

The available commands may always be listed using the single command help. Currently this gives the list below.

 
aa_confirm_safety
all_legal
analyze_eyegraph
attack
attack_either
black
block_off
break_in
boardsize
captures
clear_board
clear_cache
color
combination_attack
connect
countlib
cputime
decrease_depths
defend
defend_both
disconnect
dragon_data
dragon_status
dragon_stones
dump_stack
echo
echo_err
estimate_score
accuratelib
accurate_approxlib
experimental_score
eval_eye
final_score
final_status
final_status_list
findlib
finish_sgftrace
fixed_handicap
get_handicap
get_random_seed
set_random_seed
genmove
genmove_black
genmove_white
get_connection_node_counter
get_life_node_counter
get_owl_node_counter
get_reading_node_counter
get_trymove_counter
gg_genmove
gg-undo
help
increase_depths
influence
is_legal
known_command
komi
get_komi
ladder_attack
level
set_search_diamond
reset_search_mask
limit_search
set_search_limit
draw_search_area
limit_search
list_commands
list_stones
loadsgf
name
new_score
analyze_semeai
analyze_semeai_after_move
tactical_analyze_semeai
owl_attack
owl_connection_defends
owl_defend
owl_does_attack
owl_does_defend
owl_substantial
owl_threaten_attack
owl_threaten_defense
play
popgo
printsgf
orientation
place_free_handicap
protocol_version
query_boardsize
query_orientation
quit
restricted_genmove
reg_genmove
report_uncertainty
reset_connection_node_counter
reset_life_node_counter
reset_owl_node_counter
reset_reading_node_counter
reset_trymove_counter
same_dragon
set_free_handicap
showboard
is_surrounded
does_surround
surround_map
start_sgftrace
test_eyeshape
time_left
time_settings
top_moves
top_moves_black
top_moves_white
trymove
tryko
tune_move_ordering
undo
version
white
worm_cutstone
worm_data
worm_stones

For exact specification of their arguments and results, See section 19.5 GTP command reference.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

19.2 Protocol applications

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' responds.

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. Programs implementing setup 3 are also distributed with GNU Go (the files `interface/gtp_examples/twogtp' and `interface/gtp_examples/2ptkgo.pl').


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

19.3 Protocol conventions

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.

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. This is absolutely not the purpose of the protocol! Use the ascii interface instead if you're inclined to make such a change.

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.

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 gtp_countlib():

 
static int
gtp_countlib(char *s)
{
  int i, j;
  if (!gtp_decode_coord(s, &i, &j))
    return gtp_failure("invalid coordinate");

  if (p[i][j] == EMPTY)
    return gtp_failure("vertex must not be empty");

  return gtp_success("%d", countlib(POS(i, j)));
}

The functions gtp_failure() and gtp_success() automatically ensures the specified response format, assuming the strings they are printing do not end with a newline.

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. gtp_genmove_white():

 
static int
gtp_genmove_white(char *s)
{
  int i, j;
  UNUSED(s);
  if (genmove(&i, &j, WHITE) >= 0)
    play_move(POS(i, j), WHITE);

  gtp_start_response(GTP_SUCCESS);
  gtp_print_vertex(i, j);
  return gtp_finish_response();
}

Here gtp_start_response() writes the equal sign and the request id while gtp_finish_response() adds the final two newlines. The next example is from gtp_influence():

 
  gtp_start_response(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;

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.

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!

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 gtp_report_uncertainty takes a single argument which is expected to be "on" or "off", after which it sets the value of report_uncertainty, a variable which affects the form of future GTP responses, reports success, and exits. The function is coded thus:

 
static int
gtp_report_uncertainty(char *s)
{
  if (!strncmp(s, "on", 2)) {
    report_uncertainty = 1;
    return gtp_success("");
  }
  if (!strncmp(s, "off", 3)) {
    report_uncertainty = 0;
    return gtp_success("");
  }
  return gtp_failure("invalid argument");
}


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

19.4 Regression testing with GTP

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 20. Regression testing).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

19.5 GTP command reference

This section lists the GTP command set along with some information about each command. Each entry in the list has the following fields:

For suggestions on how to make effective use of the GTP command set, See section 19.2 Protocol applications. Some of these commands are standard commands in the protocol, others are GNU Go private commands.

Without further ado, here is the big list (in no particular order):


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by root on February, 29 2004 using texi2html