# Pentobi GTP Interface

Author: Markus Enzenberger

This document describes the text-based interface to the engine of the Blokus program Pentobi. The interface is an adaption of the Go Text Protocol (GTP) and allows controller programs to use the engine in an automated way without the GUI. The most recent version of this document can be found in the source code distribution of Pentobi in the folder pentobi/doc/gtp.

## Go Text Protocol

The Go Text Protocol is a simple text-based protocol. The engine reads single-line commands from its standard input stream and writes multi-line responses to its standard output stream. The first character of a response is a status character: `=` for success, `?` for failure, followed by the actual response. The response ends with two consecutive newline characters. See the GTP specification for details.

## Controllers

To use the engine from a controller program, the controller typically creates a child process by running `pentobi-gtp` and then sends commands and receives responses through the input/output streams of the child process. How this is done, depends on the platform (programming language and/or operating system). In Java, for example, a child process can be created with `java.lang.Runtime.exec()`.

Note that the input/output streams of child processes are often fully buffered. You should explicitly flush the output stream after sending a command. Another caveat is that `pentobi-gtp` writes debugging information to its standard error stream. On some platforms the standard error stream of the child process is automatically connected to the standard error stream of its parent process. If not (this happens for example in Java), the controller needs to read everything from the standard error stream of the child process. This can be done for example by running a separate thread in the parent process that has a simple read loop, which writes everything that it reads to its own standard error stream or discards it. Otherwise the child process will block as soon as the buffer for its standard error stream is full. Alternatively, you can disable debugging output of `pentobi-gtp` with the command line option `--quiet`, but it is generally better to assume that a GTP engine writes text to standard error.

An example for a controller written in C++ for Linux is included in Pentobi since version 9.0 in `src/twogtp`. The controller starts two GTP engines and plays a number of Blokus games between them. Older versions of Pentobi included a Python script with a similar functionality in `tools/twogtp/twogtp.py`.

## Building

Since the GTP engine is a developer tool, building it is not enabled by default. To enable it, run `cmake` with the option `-DPENTOBI_BUILD_GTP=ON`. After building, there will be an executable in the build directory named `src/pentobi_gtp/pentobi-gtp`. The GTP engine requires only standard C++ and has no dependency on other libraries like Qt, which is needed for the GUI version of Pentobi. If you only want to build the GTP engine, you can disable building the GUI with `-DPENTOBI_BUILD_GUI=OFF`.

## Options

The following command-line options are supported by `pentobi-gtp`:

--book file
  Specify a file name for the opening book. Opening books are blksgf files containing trees, in which moves that Pentobi should select are marked as good moves with the corresponding SGF property (see the files in `src/books`). If no opening book is specified and opening books are not disabled, `pentobi-gtp` will automatically search for an opening book for the current game variant in the directory of the executable using the same file name conventions as in `src/books`. If no such file is found it will print an error message to standard error and disable the use of opening books.
--config,-c file
  Load a file with GTP commands and execute them before starting the main loop, which reads commands from standard input. This can be used for configuration files that contain GTP commands for setting parameters of the engine (see below).
--color
  Use ANSI escape sequences to colorize the text output of boards (for example in the response to the `showboard` command or with the --showboard command line option).
--cputime
  Use CPU time instead of wall time for time measurement. Currently, there is no way to make Pentobi play with time limits, the levels are defined by the number of simulations in the MCTS search, so this affects only the debugging output, which prints the time used after each search.
--game,-g variant
  Specify the game variant used at start-up. Valid arguments are classic, classic_2, duo, trigon, trigon_2, trigon_3, junior or the abbreviations c, c2, d, t, t2, t3, j. By default, the initial game variant is classic. The game variant can also be changed at run-time with a GTP command. If only a single game variant is used, it is slightly faster and saves memory if the engine is started in the right variant compared to having it start with classic and then changing it.
--help,-h
  Print a list of the command-line options and exit.
--level,-l n
  Set the level of playing strength to n. Valid values are 1 to 9.
--memory n
  Allocate n bytes of memory for the search trees. If not specified, Pentobi will currently allocate half of the physical memory available on the system but not more than 1.3 GB. Increasing the memory may slightly increase the playing strength at higher levels. If only lower levels are used, the amount of memory can be reduced. If Pentobi runs out of memory (typically in early game positions in game variant Duo), it will prune the search tree and print debugging messages about the pruning to standard error. The memory can be reduced if pruning does not happen more than a few times during a move generation.
--seed,-r n
  Use n as the seed for the random generator. Specifying a random seed will make the move generation deterministic as long as the search is single-threaded.
--showboard
  Automatically write a text representation of the current position to standard error after each command that alters the position.
--nobook
  Disable the use of opening books.
--noresign
  Disable resignation. If resignation is desabled, the `genmove` command will never respond with `resign`. Resignation can speed up the playing of test games if only the win/loss information is wanted.
--quiet,-q
  Do not print any debugging messages, errors or warnings to standard error.
--threads n
  Use n threads during the search. Note that the default is 1, unlike in the GUI version of Pentobi, which sets the default according to the number of hardware threads (CPUs, cores or virtual cores) available on the current system. The reason is that, for example, using 2 threads makes the search twice as fast but may lose a bit of playing strength compared to the single-threaded search. Therefore, if the GTP engine is used to play many test games with twogtp.py (which supports playing games in parallel), it is better to play the games with single-threaded search in parallel than with multi-threaded search sequentially. Using a large number of threads (e.g. more than 4 on game variants with a small board or more than 8 on large boards) is untested and might reduce the playing strength significantly compared to the single-threaded search.
--version,-v
  Print the version of Pentobi and exit.

## Commands

### Standard Commands

The following GTP commands have the same or an equivalent meaning as specified by the GTP standard. Colors or players in arguments or responses are represented as in the property IDs of blksgf files (`B`, `W` if two players or colors; `1`, `2`, `3`, `4` if more than two). Moves in arguments or responses are represented as in the move property values of blksgf files. See the specification for Pentobi SGF files for details.

all_legal color
  List all legal moves for a color.
clear_board
  Clear the board and start a new game in the current game variant.
final_score
  Get the score of a final board position. In two-player game variants, the format of the response is as in the result property in the SGF standard for the game of Go (e.g. `B+2` if the first player wins with two points, or `0` for a draw). In game variants with more than two players, the response is a list of the points for each player (e.g. `64 69 70 40`). If the current position is not a final position, the response is undefined.
genmove color
  Generate and play a move for a given color in the current position. If the color has no more moves, the response is `pass`. If resignation is not disabled, the response is `resign` if the players is very likely to lose. Otherwise the response is the move.
known_command command
  The response is `true` if command is a GTP command supported by the engine, `false` otherwise.
list_commands
  List all supported GTP commands, one command per line.
loadsgf file [move_number]
  Load a board position from a blksgf file with name file. If move_number is specified, the board position will be set to the position in the main variation of the file before the move with the given number was played, otherwise to the last position in the main variation.
name
  Return the name of the GTP engine (`Pentobi`).
play color move
  Play a move for a given color in the current board position.
protocol_version
  Return the version of the GTP protocol used (currently `2`).
quit
  Exit the command loop and quit the engine.
reg_genmove color
  Like the `genmove` command, but only generates a move and does not play it on the board.
showboard
  Return a text representation of the current board position.
undo
  Undo the last move played.
version
  Return the version of Pentobi.

### Generally Useful Extension Commands

cputime
  Return the CPU time used by the engine since the start of the program.
cputime_diff
  Return the CPU time used by the engine since the last call of cputime_diff or start of the program if cputime_diff has nto been called yet.
g
  Shortcut for the `genmove` command with the color argument set to the current color to play.
get_place color
  Get the place of a given color in the list of scores in a final position (e.g. in game variant Classic, 1 is the place with the highest score, 4 the one with the lowest, if all players have a different score). If some colors have the same score, they share the same place and the string `shared` is appended to the place number.
get_value
  Get an estimated value of the board position from the view point of the color of the last generated move. The return value is a win/loss estimation between 0 (loss) and 1 (win) as produced by the last search performed by the engine. This command should only be used immediately after a `reg_genmove` or `genmove` command, otherwise the result is undefined. The value is not very meaningful at the lowest playing levels. Note that no searches are performed if the opening book is used for a move generation and there is currently no way to check if this was so. Therefore, the opening book should be disabled if the `get_value` command is used.
p move
  Shortcut for the `play` command with the color argument set to the current color to play.
param [key value]
  Set or query parameters specific to the Pentobi engine that can be changed at run-time. If no arguments are given, the response is a list of the current value with one key/value pair per line, otherwise the parameter with the given key will be set to the given value. Generally useful parameters are:

  > avoid_symmetric_draw 0|1
  >   In some game variants (Duo, Trigon_2), the second player can enforce a tie by answering each move by its symmetric counterpart if the first players misses the opportunity to break the symmetry in the center. Technically, exploiting this mistake by the first player is a good strategy for the second player because a draw is a good result considering the first-play advantage. However, playing symmetrically could be considered bad style, so this behavior is avoided (value `1`) by default.
  > fixed_simulations n
  >   Use exactly n MCTS simulations during a search. By default, the search engine uses levels, which determine how many MCTS simulations are run during a search, but as a function that increases with the move number (because the simulations become much faster at the end of the game). For some experiments, it can be desirable to use a fixed number of simulations for each move. If this number is specified, the playing level is ignored.
  > level n
  >   Set the playing level to n. See the command line option --level for possible values.
  > use_book 0|1
  >   Enable or disable the opening book.

  The other parameters are only interesting for developers.
param_base [key value]
  Set or query basic parameters that are not specific to the Pentobi engine. If no arguments are given, the response is a list of the current value with one key/value pair per line, otherwise the parameter with the given key will be set to the given value.

  > accept_illegal 0|1
  >   Accept move arguments to the `play` command that violate the rules of the game. If disabled, the `play` command will respond with an error, otherwise it will perform the moves.
  > resign 0|1
  >   Allow the engine to respond with `resign` to the `genmove` command.

set_game variant
  Set the current game variant and clear the board. The argument is the name of the game variant as in the game property value of blksgf files (e.g. `Blokus Duo`, see the specification for Pentobi SGF files for details).
set_random_seed n
  Set the seed of the random generator to n. See the documentation for the command-line option --seed.

### Extension Commands for Developers

The remaining commands are only interesting for developers. See Pentobi's source code for details.

## Example

The following GTP session queries the engine name and version, plays and generates a move in game variant Duo and shows the resulting board position. Commands are printed in bold, responses in normal text.

    $ ./pentobi-gtp --quiet
    name
    = Pentobi

    version
    = 7.1

    set_game Blokus Duo
    =

    play b e8,d9,e9,f9,e10
    =

    genmove w
    = i4,h5,i5,j5,i6

    showboard
    =
       A B C D E F G H I J K L M N
    14 . . . . . . . . . . . . . . 14  *Blue(X): 5
    13 . . . . . . . . . . . . . . 13  1 F L5 N P T5 U V5 W Y
    12 . . . . . . . . . . . . . . 12  Z5 I5 O T4 Z4 L4 I4 V3 I3 2
    11 . . . . . . . . . . . . . . 11
    10 . . . . X . . . . . . . . . 10  Green(O): 5
     9 . . . X X X . . . . . . . . 9   1 F L5 N P T5 U V5 W Y
     8 . . . . X . . . . . . . . . 8   Z5 I5 O T4 Z4 L4 I4 V3 I3 2
     7 . . . . . . . . . . . . . . 7
     6 . . . . . . . .>O . . . . . 6
     5 . . . . . . . O O O . . . . 5
     4 . . . . . . . . O . . . . . 4
     3 . . . . . . . . . . . . . . 3
     2 . . . . . . . . . . . . . . 2
     1 . . . . . . . . . . . . . . 1
       A B C D E F G H I J K L M N

    quit
    =