Difference between revisions of "GTP"

From HexWiki
Jump to: navigation, search
(Example session: Removed diagnostic (stderr) output from example session)
m (Protocol specification: Minor copy-editing)
Line 23: Line 23:
 
== Protocol specification ==
 
== 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.
+
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 from its standard input stream, writes machine readable responses to its standard output stream, and may also write optional diagonstic and progress information to its standard error stream.
  
 
=== Command format ===
 
=== Command format ===

Revision as of 02:39, 3 March 2020

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

Backends

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 from its standard input stream, writes machine readable responses to its standard output stream, and may also write optional diagonstic and progress information to 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
=