Go Text Protocol (GTP) Version 2 Specification Revision - 11 (January 1, 2002) (c) Copyright 2001 - Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". Table of Contents I. Introduction II. Message Flow III. Basic Rules IV. State V. Commands VI. Error Messages VII. Frequently Asked Questions VIII. References IX. Revision History X. Credits I. Introduction A. Goal The goal of the Go Text Protocol (GTP) is designed to provide a useful and standard interface for communicating between various Go programs. GTP is a modern alternative to the Go Modem Protocol, GMP, and may potentially replace this for use in Go tournaments in the future. It is also intended, through the use of auxiliary programs, to make it easier for go programmers to connect to go servers on the Internet and do automatic regression testing. The Go Text Protocol is an application-level protocol. It is independent of any particular transmission subsystem and requires only a reliable ordered data stream channel, such as TCP/IP or Unix-Pipes. GTP relies on the error detection and error correction of the underlying transmission protocol. To make the communication easy for humans to visually decipher, all communication is done with ASCII text and two control characters, linefeed and carriage return. B. Model The GTP is based on a request/response paradigm between two parties, the Controller and Engine. Once communication is established, the Controller sends commands to the Engine, and the Engine responds. The Controller can be a graphic user interface, a relay, or an arbitrator, while the Engine typically implements a Go-playing program. Controller -------> command --------> Engine Controller <------- response <-------- Engine C. Communication Models There are five (5) typical communication models: 1. Human vs. Computer In Human vs. Computer model, the Controller is a GUI interface that relays moves from the user directly to an Engine. GUI -------> command --------> Engine GUI <------- response <-------- Engine 2. Regression Testing In this model, a script of commands is transmitted to the Engine. The responses from the Engine are then compared against previous tests, or saved in a file for later review. Script -------> command --------> Engine File <------- response <-------- Engine 3. Program vs. Program without an Arbiter In this model, an Engine, acting as a Controller, directly connects to another Engine. Engine A (Controller) -------> command --------> Engine B Engine A (Controller) <------- response <-------- Engine B 4. Program vs. Program with an Arbiter In this model, an Arbiter relays commands between to two Engines using two different communication channels to each. There is no direct link between the two Engines. Arbiter -------> command --------> Engine A Arbiter <------- response <-------- Engine A Arbiter -------> command --------> Engine B Arbiter <------- response <-------- Engine B 5. Go Server In this model, an arbiter acts as a bridge between a Go Server, like IGS or NNGS, and an Engine. The arbiter accepts games on the Go Server, and establishes a connection to an Engine. Moves are relayed back and forth by the Arbiter. There is no direct connection between the Go Server and the Engine. II. Message Flow A. Overview GTP is similar to other Internet protocols, like File Transfer Protocol (FTP), Simple Mail Transport Protocol (SMTP) and Hyper-Text Transport Protocol (HTTP), in that GTP follows the same client/server command and response protocol agreement. In GTP, the client is called the Controller, and the server is called the Engine. The Controller, which initiates the communications to an Engine, sends commands to the Engine. In turn, the Engine responds with a status and possible additional information. B. Command Message The command message has the following three part basic structure: command_id command_name parameter(s) # comment LF The command is exactly one line long, i.e. it ends as soon as a linefeed character appears. It is not possible to give multiple commands on the same line. Carriage return characters are silent disregarded. The first part of the command format is the command_id. (TODO) The second part of the command format is the command name, followed by a list of command parameters, if any. See the "Commands" chapter for a list of commands and definitions. The last part is an optional comment, prefixed with a hash character. The Engine will completely ignore an empty line, a line with only white space, or a line that contains just a comment. The Engine will not return a response. C. Response Message There are two response formats, depending on whether the command is successful or not. If the command is successful, the Engine will respond in the following format: =command_id result LF LF Here the '=' character indicates success. This is followed by a command_id, if any was provided with the command. Next, to follow is the result. The result ends with two (2) consecutive line-feeds (carriage returns are ignored). If the command fails for some reason, the response takes the form: ?command_id error_message LF LF Here the '?' character indicates failure. This is followed by the command_id, if any was provided with the command. Next, is the error_message which gives an explanation of the failure. The error_message ends with two (2) consecutive line feed characters. See chapter "Error Message" for a list of basic error messages and definition. Commands that are not recognized by the Engine should return "unknown command". This allows the Controller to specifically recognize that the given command is not implemented, and allow the Controller to act accordingly. III. Basic Rules A. Character Set The GTP uses plain text to send and receive messages. Specifically, GTP uses the US-ASCII Coded Character Set (ISO-14962-1997 and ANSI-X3.4-1997): alpha = any US-ASCII uppercase or lowercase letter (65-90 & 97-122) digit = any US-ASCII digit (48-57) CR = US-ASCII CR, carriage return (13) LF = US-ASCII LF, linefeed (10) SP = US-ASCII SP, space (32) SYM = any US-ASCII printable symbol (33-64, 91-95 & 123-126) B. Basic Grammar The carriage return character (CR) should be silently discarded. The end-of-line is defined as a linefeed: EOL = LF White space is defined as a space or the end-of-line: WS = SP | EOL A printable character is defined as: printable = alpha | digit | SYM An integer is defined as a sequence of digits: integer = integer-sign integer-sequence | integer-sequence integer -sign = ("-" | "+") integer-sequence = digit | digit integer-sequence A real value is defined as a sequence of digits, which may include one decimal only, ending: real = real-sign real-sequence | real-format real -sign = ("-" | "+") real-format = real-sequence | real-sequence "." real-sequence real-sequence = digit | real-sequence digit A coordinate, or position on a Go board, is in the A1-T19 form or to represent a pass as a move, "pass" string. For example, "a1" and "t19" would specify opposite corners on a 19x19 board. Coordinate are case-insensitive, so "a1" and "pass" are equivalent to "A1" and "PASS" respectively. (TODO: Comment omission of 'i' as a coordinate. Also only board sizes up to 25x25 are supported by this protocol.) A coordinate is defined as: coordinate = (alpha digit | alpha digit digit | "pass") (case insensitive) Color is defined as: color = ("white" | "black" | "b" | "w") (case insensitive) Text is the sequence of all ASCII printable characters: text = text-sequence text-sequence = printable | text-sequence printable D. Grammar: Command The command, or request message, has a command name, optionally followed by command arguments, which finally ending with an end-of-line: command = command-name EOL | command-name SP command-arguments EOL | command-name SP command-arguments "#" command-comment EOL | "#" command-comment EOL command-name = { see Chapter "Commands" for a list} command-arguments = command-argument | SP command-arguments command-argument = text | coordinate | integer | real comment-comment = text E. Grammar: Response The response message has a one-character indicator to show success or failure, followed by an optional message, and ended by (2) two end-of-lines: response = response-indicator EOL EOL | response-indicator SP response-message EOL EOL response-indicator = ("=" | "?") response-message = { depends on the given command; see Chapter "Commands" for descriptions} V. State A. State Maintenance The GTP Engine is expected to maintain the following eight states: 1. Board size. 2. Board contents, for each vertex on the board, either black, white or empty. 3. Number of stones captured by each player. 4. Komi value 5. Scoring system a. Territory b. Area 6. Ko rule a. Simple b. No Repeats (also called Super-Ko) 7. Suicide allowed, either yes or no If a command fails for any reason, the state of the game remains unchanged; except when explicitly stated. For example, some commands if they fail, may be unable to return to the original state. In this case, the state must be reset completely. B. Default State When a connection is established, the state of the GTP Engine will default to an empty board and no captured stones. All other states must have valid values but the engine is free to choose those however it likes. A controller which has any particular wishes for board size, komi, scoring system, and so on, MUST set these explicitly. VI. Commands A. Overview This chapter documents all GTP commands. Not all commands need to be implemented. However, B. Recommended Commands List ??? C. Complete Commands List 1. boardsize 2. fixed_handicap 3. genmove 4. help 5. is_legal 6. ko_setting 7. komi 8. loadsgf 9. move 10. name 11. clear_board 12. scoring_system 13. setup 14. suicide 15. prisoners 16. protocol_version 17. quit 18. undo 19. version All commands and parameters are case-sensitive. 1. boardsize Description: Sets the size of the board. Parameters: Integer: This parameter specifies the new board size. For example, 9 for 9x9 board, 13 for 13x13 board, 15 for 15x15 board, and 19 for 19x19 board. On Success: The board size is changed. Additionally, all stones are removed from the board, the current player is set to white, the current move is set to 0, and the number of stones captured by each player are set to 0. On Failure: The change in board size is not accepted. Error Messages: not_supported invalid_argument invalid_number 2. fixed_handicap (TODO: Remove?) Function: Set up fixed placement of handicap stones. Arguments: Integer: This parameter specifies the number of handicap stones. On Success: The result string contains the coordinates of the handicapped stones. On Failure: Handicap stones are not added to the board. Error Messages: not_supported invalid_argument invalid_number 3. genmove Function: Generate and play the best move for the given player. Arguments: Color: Specifies which player to generate the move for. On Success: The result string contains the move coordinate or pass. In addition, the stone is placed on the board, any captured stones are removed and counted as prisoners, and the move number is incremented. On Failure: The error message may indicate the reason why. Error Messages: not_implemented invalid_argument invalid_color 4. help Function: Returns a list of all implemented commands. Arguments: None. On Success: The result string contains a list of all implemented commands, one per line. On Failure: This command should never fail. Error Messages: None. 5. is_legal Function: Tell whether a move is legal. Arguments: Color: Specifies which player the move is for. Coordinate: The coordinate of the move. On Success: Returns a 1, if the move is legal, or a 0 if not. On Failure: The error message may indicate the reason why. Error Messages: invalid_color invalid_coordinate 6. ko_setting Function: Sets the KO rule for the game. Arguments: Text: The type of KO rule: <"simple"> No move may recreate the board configuration two moves ago. <"super_ko"> No move may recreate any previous board configuration. On Success: The scoring system is changed. On Failure: The error message may indicate the reason why. Error Messages: not_supported 7. komi Description: Sets the Komi value for the game. Parameters: Real: Komi value for the game. On Success: The Komi value changed. On Failure: The Komi value is not changed. Error Messages: invalid_argument out_of_range 8. loadsgf Function: Loads a SGF file, optionally up to a specific move number or the first occurrence of a move. Arguments: Text: The filename of the SGF file. (Optional) Integer: The number of moves to read from SGF file. -or- (Optional) Coordinate: The first occurrence of a move at which to stop reading further moves from the SGF file. On Success: The SGF file is loaded. The state of the game is changed to that described in the SGF file. On Failure: The error message may indicate the reason why. Error Messages: invalid_argument out_of_range unable_to_load_file file_not_found 9. move Function: Plays a stone at the given coordinate and player. Arguments: Color: Specifies which player the move is for. Coordinate: The coordinate of the move. On Success: Stone is played. On Failure: The move is rejected. Error Messages: invalid_argument invalid_coordinate invalid_color illegal_move 10. name Function: Reports the name of the engine. Arguments: None. On Success: The results string contains the name of the engine. On Failure: This command should never fail. Error Messages: None. 11. clear_board Function: Starts a new game. Arguments: None. On Success: A new game is started. All stones are removed from the board, the current player is set to white, the current move is set to 0, and the number of stones captured by each player are set to 0. All other states, like komi value, scoring system, and suicide rule, are left unchanged. On Failure: This command should never fail. Error Messages: None. 12. scoring_system Function: Sets the scoring system for the game. Arguments: Text: The type of scoring system: <"territory"> or <"area"> On Success: The scoring system is changed. On Failure: The error message may indicate the reason why. Error Messages: not_supported 13. setup Function: Places a stone at the given coordinate for a player. This command can only be used during the setup phase of the game, usually to place handicap stones. Arguments: Color: Specifies which stone to place. Coordinate: The coordinate of the stone to place. On Success: Stone is placed on the board. The move number is not incremented. On Failure: The stone placement is rejected. Error Messages: invalid_argument invalid_coordinate invalid_color illegal_move 14. suicide Function: Sets suicide rule for the game. Arguments: Text: Is suicide allowed? <"yes"> or <"y"> for yes, and <"no"> or <"n"> for no. On Success: Changes the suicide rule for the game.. On Failure: The error message may indicate the reason why. Error Messages: not_supported invalid_argument 15. prisoners Function: Returns the number of prisoners taken by either color. Arguments: Color: Specifies which player to return the number of prisoners. On Success: The results string contains the number of prisoners taken. On Failure: The error message may indicate the reason why. Error Messages: invalid_color 16. protocol_version Function: Returns the GTP protocol version number of the engine. The current version is 2. Arguments: None On Success: The result is the GTP protocol version number. On Failure: This command should never fail. On Failure: None. 17. quit Function: The quit command terminates the connection. Arguments: None. On Success: The connection is terminated. On Failure: This command should never fail. Error Messages: None. 18. undo Function: The undo command takes back the last move. Arguments: None. On Success: he move is successfully un-done. On Failure: The move is not un-done. On Failure: The error message may indicate the reason why. Error Messages: not_implemented 19. version Function: Retrieves the version number of the engine. Arguments: None. On Success: The response contains the version number of the engine. On Failure: This command should never fail. Error Messages: None. VI. Error Messages A. Overview A command may return an error message. There is a set of standard error messages that fit most situations. It is recommended that these error messages be used, if applicable. Doing so will allow Controller to detect a specific type of error, rather than just a general failure. 1. unknown command = the command is not implemented by the Engine 2. not_supported = a feature of the command is not supported 3. invalid_argument = the specified argument is not formatted correctly, or it is unexpected 4. invalid_color = color value not formatted correctly 5. invalid_coordinate = coordinate value not formatted correctly 6. illegal_move = illegal move because position already, ko violation, incorrect player, etc. 7. out_of_range = value out of range 8. unable_to_load_file = unable to load file, something could be wrong with the file format 9. file_not_found = unable to find file VII. Frequently Asked Questions 1. Is there a freely distributed GTP implementation? Yes, a freely distributed GTP implementation with the source code is available from the GNU Go Project (www.gnu.org/software/gnugo). 2. Is there a GTP mailing list? Yes, a technical discussions mailing list exists with the primary goal of standardizing the Go Text Protocol and documenting it (e.g., this document). You can subscribe or view the list archive by visiting: http://lists.lysator.liu.se/mailman/listinfo/gtp IX. References [1] Go Modem Protocol (GMP) - http://www.britgo.org/tech/gmp.html [2] Smart Go Format (SGF) - http://www.red-bean.com/sgf/index.html [3] GNU Go - http://ww.gnu.org/software/gnugo [4] Ko Rules - http://home.snafu.de/jasiek/korules.html IX. Revision History 8/11/2001 - Initial Document 9/03/2001 - Converted to document to ASCII. X. Credits Gunnar Farneback (gunnar@lysator.liu.se) wrote the original description of the Go Text Protocol (GTP) from which this specification is based. Additional contributions were made by: Daniel Bump (bump@match.Stanford.edu) Don Dailey (drd@supertech.lcs.mit.edu) Philipp Garcia (philippgarcia@home.com) Anders Kierulf (anders@smartgo.com) Heikki Levanto (heikki@lsd.dk) Pierce T. Wetter III (pierce@alumni.caltech.edu)