Difference between revisions of "GTP"
(→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 | + | 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.
Contents
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
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 =
