GTP

Hex GTP (or simply GTP) is a text-based interface for interacting with Hex software. A typical use is to separate front-end software, which provides graphical display of game boards, from back-end software, which implements a Hex strategy engine. The use of a standardized protocol in principle permits any strategy engine, such as Six, MoHex, or Wolve, to be plugged into any graphical front-end, such as HexGui.

Moreover, GTP can also be used by humans to interact with a strategy engine directly, i.e., without the use of a graphical front-end.

History

Hex GTP is based on the Go Text Protocol (GTP), which was originally developed for Go as part of the GNU Go software.

Software supporting GTP

Frontends

• HexGui
• Todo: add more

Backends

• Six
• MoHex
• Wolve
• Todo: add more

Protocol specification

The protocol follows a client-server model. It uses textual commands and responses expressed in the ASCII character set. Commands are sent by the client to the server, and responses are sent by the server to the client. When the server is a local process, it reads commands on its standard input stream, sends machine readable responses on its standard output stream, and may also send optional diagonstic and progress information on its standard error stream.

Command format

Commands consist of a single line of text, and are terminated by a newline character. Each command consists of an optional identity number, a keyword, and zero or more arguments, all separated by whitespace.

Response format

Responses consist of one or more lines of text, and terminated by two consecutive newline characters. A successful response starts with the character '=', followed immediately by the optional identity number of the command the response refers to, whitespace, and the rest of the response (whose format depends on the command in question). A failure response starts with the character '?', followed immediately by the optional identity number of the command the response refers to, whitespace, and an error message.

Command arguments

Several of the commands take one or more arguments. Some common argument types are:

Argument	Possible values
n	An integer.
player	'black' or 'white'.
move	A cell such as 'a7' or 'c4', or one of the special moves 'resign' or 'swap-pieces'.

Command reference

There are a large number of commands, and the command 'list_commands' lists all of them. Some commands are server specific. The following lists some of the common commands:

Board handling

Command	Meaning
boardsize n	Set the board size to n × n and clear the board.
clear_board	Clear the current board.
showboard	Display the current board in a format that is both human readable and machine readable.
final_score	Determine the winner of a completed game. One player must have a solid chain connecting their two edges. The response is 'B+' for a black win, 'W+' for a white win, or 'cannot score' if there is no solid chain. Since most Hex games result in one player resigning before a solid chain is formed, the 'final_score' command is of limited use in practice.

Making moves

Command	Meaning
play player move	Play the given move for the given player.
genmove player	Automatically generate a good move for the given player and play it.
reg_genmove player	Automatically generate a good move for the given player and show it, but do not play it.
undo	Undo the most recent move.
all_legal_moves	Show the list of all legal moves for the current position.

Interacting with the server

Command	Meaning
name	Show the name of the server program.
version	Show the version of the server program.
protocol_version	Show the version of the GTP protocol that the server program understands.
list_commands	Show a list of all commands known to the server program.
known_command cmd	Return 'true' if cmd is a known command, and 'false' otherwise.
quit	Close the connection to the server.

Example session

boardsize 7 7
= 

showboard
= 

 dcf37c659c5632f9
 a  b  c  d  e  f  g  
1\.  .  .  .  .  .  .\1
 2\.  .  .  .  .  .  .\2
  3\.  .  .  .  .  .  .\3
   4\.  .  .  .  .  .  .\4
    5\.  .  .  .  .  .  .\5
     6\.  .  .  .  .  .  .\6
      7\.  .  .  .  .  .  .\7
         a  b  c  d  e  f  g  

play black c3
= 

showboard
= 

 63d78dc21cfe93dc
 a  b  c  d  e  f  g  
1\.  .  .  .  .  .  .\1
 2\.  .  .  .  .  .  .\2
  3\.  .  B  .  .  .  .\3
   4\.  .  .  .  .  .  .\4
    5\.  .  .  .  .  .  .\5
     6\.  .  .  .  .  .  .\6
      7\.  .  .  .  .  .  .\7
         a  b  c  d  e  f  g  

play white d5
= 

showboard
= 

 7edf0d0dfa16e804
 a  b  c  d  e  f  g  
1\.  .  .  .  .  .  .\1
 2\.  .  .  .  .  .  .\2
  3\.  .  B  .  .  .  .\3
   4\.  .  .  .  .  .  .\4
    5\.  .  .  W  .  .  .\5
     6\.  .  .  .  .  .  .\6
      7\.  .  .  .  .  .  .\7
         a  b  c  d  e  f  g  

genmove black
= b6

showboard
= 

 b3d2f7b4917a6c30
 a  b  c  d  e  f  g  
1\.  .  .  .  .  .  .\1
 2\.  .  .  .  .  .  .\2
  3\.  .  B  .  .  .  .\3
   4\.  .  .  .  .  .  .\4
    5\.  .  .  W  .  .  .\5
     6\.  B  .  .  .  .  .\6
      7\.  .  .  .  .  .  .\7
         a  b  c  d  e  f  g  

undo
= 

showboard
= 

 7edf0d0dfa16e804
 a  b  c  d  e  f  g  
1\.  .  .  .  .  .  .\1
 2\.  .  .  .  .  .  .\2
  3\.  .  B  .  .  .  .\3
   4\.  .  .  .  .  .  .\4
    5\.  .  .  W  .  .  .\5
     6\.  .  .  .  .  .  .\6
      7\.  .  .  .  .  .  .\7
         a  b  c  d  e  f  g  

quit
=