Difference between revisions of "GTP"

From HexWiki
Jump to: navigation, search
(→‎Example session: Added example session)
(→‎Backends: Added KataHex)
 
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
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]].
+
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 [[MoHex]] or [[KataHex]], 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.
 
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.
Line 19: Line 19:
 
* [[MoHex]]
 
* [[MoHex]]
 
* [[Wolve]]
 
* [[Wolve]]
−
* Todo: add more
+
* [[KataHex]]
  
 
== Protocol specification ==
 
== Protocol specification ==
  
−
Not yet written.
+
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:
 +
 
 +
{| class="wikitable" style="width: 100%"
 +
! style="width: 150pt; vertical-align: top" | 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 ====
 +
 
 +
{| class="wikitable" style="width: 100%"
 +
! style="width: 150pt; vertical-align: top" | Command
 +
! Meaning
 +
|-
 +
| boardsize ''n''
 +
| Set the board size to ''n'' × ''n'' and clear the board.
 +
|-
 +
| boardsize ''n'' ''m''
 +
| Set the board size to ''n'' × ''m'' 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 ====
 +
 
 +
{| class="wikitable" style="width: 100%"
 +
! style="width: 150pt; vertical-align: top" | 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 ====
 +
 
 +
{| class="wikitable" style="width: 100%"
 +
! style="width: 150pt; vertical-align: top" | 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 ==
 
== Example session ==
Line 79: Line 179:
  
 
  genmove black
 
  genmove black
−
f6707 info: Winning SC.
 
 
  = b6
 
  = b6
  
Line 115: Line 214:
 
  quit
 
  quit
 
  =
 
  =
 +
 +
[[Category:Computer Hex]]

Latest revision as of 16:14, 24 October 2024

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 MoHex or KataHex, 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.
boardsize n m Set the board size to n × m 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
=
Retrieved from "https://www.hexwiki.net/index.php?title=GTP&oldid=8736"