Specification of the Go Text Protocol, version 2, draft 1

Gunnar Farnebäck

July, 2002

http://www.lysator.liu.se/ ${}_{\tilde{}} $gunnar/gtp
This is a draft only.
Permission is granted to make and distribute verbatim or modified copies of this specification provided that the terms of the GNU Free Documentation License (section 10) are respected.


Contents

1 Introduction

This document gives a specification of the Go Text Protocol (GTP), version 2.

1.1 Purpose of the Protocol

1.2 History

The Go Text Protocol was developed within the GNU Go project, initially to create a framework for automated regression testing and to simplify connecting the program to go servers. The first appearance of the protocol was on May 18, 2000, in GNU Go development version 2.7.95. The first stable release of GNU Go with GTP support was GNU Go 3.0.0, released August 24, 2001, which is the reference implementation for version 1 of the protocol. There is no good specification of GTP version 1, however, and this document is intended to provide one for version 2.

1.3 Communication Model

1.4 Typical Use Cases

1.5 Terminology

1.6 Reference Implementation

The reference implementation for GTP version 2 is GNU Go version 3.4. In cases of incompleteness or unclarity in this specification, the reference implementation decides the correct behaviour. Notice, however, that any command available in GNU Go 3.4, but not included in this specification (full list in section 6), is to be considered as a private extension (see section 2.13).

Temporary comment: GNU Go 3.4 is currently under development and GTP version 2 has not yet been implemented in the development versions.

2 Protocol Basics


2.1 Character Set

All messages exchanged in this protocol are to be considered as 8-bit character sequences. Only characters in the US-ASCII character set (ANSI X3.4-1986) are used for standardized commands and responses. Other characters may be used in comments (section 2.9) and private extensions (section 2.13) but there is no preferred character set specified for those.

2.2 Control Characters

Character values 0-31 and 127 are control characters in ASCII. The following control characters have a specific meaning in the protocol:

HT (dec 9) Horizontal Tab
CR (dec 13) Carriage Return
LF (dec 10) Line Feed

All other control characters must be discarded on input and should not be used on output.


2.3 Whitespace

The following ASCII characters can be used to indicate whitespace in the protocol:

SPACE (dec 32) Space
HT (dec 9) Horizontal Tab

In the rest of the specification we use 'space' to denote a whitespace character. On input this may be either a SPACE or a HT. On output only a SPACE should be used.


2.4 Newline Convention

A newline is indicated by a single LF character. Any occurence of a CR character must be discarded on input, both by the engine and the controller. On output either LF or some combination of CR and LF can be used. In syntax descriptions we use \n to indicate a newline.

2.5 Command Structure

A command is exactly one line long, with the syntax

[id] command_name [arguments]

Here id is an optional identity number and command_name a string. The rest of the line (up to the first newline) gives the arguments of the command.

2.6 Response Structure

If successful, the engine returns a response of the form

=[id] result

Here '=' indicates success, id is the identity number given in the command, and result is a piece of text ending with two consecutive newlines.

2.7 Error Messages

If unsuccessful, the engine returns a response of the form

?[id] error_message

Here '?' indicates failure, id is the identity number given in the command, and error_message gives an explanation for the failure, also ending with two consecutive newlines.


2.8 Timing

There are no synchronization requirements between the controller and the engine. The controller may send commands at any time, regardless of whether it has obtained responses for previous commands. The engine may send responses whenever they are ready. It must, however, respond to the commands in the same order as they come in. The engine is allowed to make pauses while sending a response.


2.9 Comments

Comments can be included in the command stream. All text between a hash sign (#) and the following newline is considered as comments and should be discarded on input.

2.10 Empty lines

Empty lines and lines with only whitespace sent by the controller must be ignored by the engine. No response must be generated. Empty lines and lines with only whitespace sent by the engine and occuring outside a response must be ignored by the controller. Notice that pure comment lines will appear as empty lines after the comment has been discarded.


2.11 Board Coordinates

Board intersections, in this document called vertices, are encoded by a letter plus a number. On a 19x19 board the letters go from A to T, excluding I, from the left to the right. The numbers go from 1 to 19, from the bottom to the top. Thus the lower left corner is called A1, the lower right corner T1, the upper left corner A19, and the upper right corner T19. Smaller boards use the obvious subset of these coordinates. Larger boards, up to 25x25, are handled by extending the letters with U to Z as needed. Boards larger than 25x25 are not supported by the protocol.

2.12 Protocol Subsets

An engine does not have to implement all commands listed in this specification. In general, for an engine to be used with some specific controller, it is only required that the engine understands exactly the commands needed by that controller. To simplify this matching of capabilities, there are two predefined protocol subsets called the tournament and the regression subsets. There is also a small set of commands required for all GTP supporting engines.


2.13 Private Extensions

The protocol is trivial to extend with new commands. Obviously there is a risk for conflicts if multiple engines make incompatible private extensions of the protocol or if an engine makes a private extension which turns out to be incompatible with a future extension of the standard protocol.

In order to avoid this problem, standard commands do not include the dash (-) character. Private extensions are recommended to be of the form XXX-YYYYY, where XXX is a prefix which is sufficiently unique for the engine or controller in question, and YYYYY describes the command. E.g. a private variant of the genmove command used by GNU Go could be called gg-genmove.

Engines are allowed to use private extensions without a dash in the name, but then they do it at their own risk and must be prepared to change if the name later becomes used for a standard command.

2.14 Panic Situations

If an engine for some reason, e.g. an internal error, finds itself in a position where it cannot meaningfully continue the session, the correct action is to just close the connection. This is also what typically will happen if the program should happen to encounter an uncontrolled crash.

3 Protocol Details


3.1 Preprocessing

When a command string arrives to an engine, it is expected to perform the following four operations before any further parsing takes place:

  1. Remove all occurences of CR and other control characters except for HT and LF.
  2. For each line with a hash sign (#), remove all text following and including this character.
  3. Convert all occurences of HT to SPACE.
  4. Discard any empty or white-space only lines.

When a response arrives to a controller, it is expected only to do steps 1 and 3 above.

Naturally an implementation does not have to actually do this preprocessing as a separate step but may interleave it with other parts of the parsing. For purposes of the following specifications, though, the preprocessing is supposed to have been carried out in full.

3.2 Syntactic Entities


3.2.1 Simple Entities


3.2.2 Compound Entities

3.3 Commands

A command has one of the syntaxes

id command_name arguments\n
id command_name\n
command_name arguments\n
command_name\n

3.4 Success Responses

A successful response has one of the syntaxes

=id response\n\n
=id\n\n
= response\n\n
=\n\n

3.5 Failure Responses

An unsuccessful response has one of the syntaxes
?id error_message\n\n
? error_message\n\n

3.6 Standard Error Messages

4 Important Concepts

FIXME: Rename chapter?

4.1 Handicap Placement

The protocol supports both fixed placement of handicap stones and free placement. The handicap stones are always black.


4.1.1 Fixed Handicap Placement

With fixed placement the handicap stones are set in predetermined positions. The maximum number of fixed handicap stones varies with the board size but is never larger than 9. On a 19x19 board, the positions for the handicap stones are given by this table:

Handicap Vertices
2 D4 Q16
3 D4 Q16 D16
4 D4 Q16 D16 Q4
5 D4 Q16 D16 Q4 K10
6 D4 Q16 D16 Q4 D10 Q10
7 D4 Q16 D16 Q4 D10 Q10 K10
8 D4 Q16 D16 Q4 D10 Q10 K4 K16
9 D4 Q16 D16 Q4 D10 Q10 K4 K16 K10

The placement of handicap stones on other board sizes mirrors that of 19x19 with stones at a specific distance from the edges and on the middle lines of the board, with the following caveats:

More explicitly we obtain the following table:

board size max handicap edge distance
25 9 4
24 4 4
23 9 4
22 4 4
21 9 4
20 4 4
19 9 4
18 4 4
17 9 4
16 4 4
15 9 4
14 4 4
13 9 4
12 4 3
11 9 3
10 4 3
9 9 3
8 4 3
7 4 3
6 - -
5 - -
4 - -
3 - -
2 - -


4.1.2 Free Handicap Placement

With free placement the handicap stones are set as chosen by the controller or by one of the engines (for normal tournament use the engine playing the black stones would make the choice). The smallest number of handicap stones is 2. The maximum number requires some discussion. Let the board size be $N$ and thus the number of vertices $N^2$.

The theoretical upper limit for the number of handicap stones is $N^2-1$, but since this would leave all stones in atari, black is clearly better off with fewer stones. In fact, for sufficiently large (but smaller than $N^2-1$) handicaps, black can arrange the stones so that white cannot possibly form a single living group even if black passes for the entire game. In particular, with $N^2/2$ stones, black can trivially place the stones in a chessboard pattern so that white does not have a single legal move.

With this in mind, we do allow up to $N^2-1$ handicap stones. However, an engine asked to choose placement of handicap stones is allowed to place a smaller number of stones than the one requested, if this is larger than some threshold. To be more precise, let $m$ be the threshold and $n$ the requested number of handicap stones. If $n>=m$, the engine must place $m$ handicap stones and if $n<m$, the engine must place $n$ handicap stones. The value of $m$ is determined by the engine and may vary with the board size. It is recommended that every engine has a threshold of at least 40 for 19x19, unless it is totally convinced that there is some smaller number for which it cannot possibly lose against any opponent.


4.2 Time Handling

The protocol has support for Canadian byo yomi, including absolute time (no byo yomi) as a special case. Canadian byo yomi is characterized by the three parameters

The semantics is that the clock is first set to $m$. The engine has no requirements on the number of stones while this time is running. When it is up, the clock is reset to $b$ and the engine has to play $s$ stones before this time is up. When $s$ stones have been played, the clock is reset to $b$, regardless of remaining time. Then the engine has to play another $s$ stones before the time is up. This procedure repeats until the game is over. If an engine fails to play $s$ stones before its byo yomi time is up, it loses on time.

Setting $m=0$ means that the engine immediately starts in byo yomi. Setting $b=0$ means that if the main time is up before the game is over, the engine loses on time. Setting $b>0$ and $s=0$ means no time limits.

4.3 Scoring

5 Internal State


5.1 State Variables

An engine is expected to keep track of the following state information:


5.2 Default State

There is no default state for any state variable. When first started, the engine may set these as it likes. A controller which has some specific opinion about these values must set them explicitly with the appropriate commands, including clearing the board.

5.3 State Maintenance

The state is changed by certain commands, as specified in their description in section 6. State which is not explicitly modified must remain unchanged. A failed command must never change any state.


6 Commands

6.1 Required Commands

All implementations are required to support the following commands.

protocol_version
name
version
known_command
list_commands
quit
boardsize
clear_board
komi
play
genmove

6.2 Protocol Subsets

6.2.1 Tournament

The tournament subset adds the commands:
fixed_handicap, place_free_handicap, set_free_handicap

6.2.2 Regression

The regression subset adds the commands:
loadsgf, reg_genmove

6.3 List of All Commands

6.3.1 Adminstrative Commands

6.3.2 Setup Commands

6.3.3 Core Play Commands

6.3.4 Tournament Commands


6.3.5 Regression Commands

6.3.6 Debug Commands

7 Example

8 Comments on the Specification

8.1 Design Principles

  1. The protocol is primarily intended for machine-machine communication. At the same time we want it to be reasonably human readable as well. There are two principal reasons for this. The first one is to make it easy to debug a protocol implementation or to find the error if the communication breaks down, e.g. if two engines involved in a game get their boards out of sync. The second reason is to make it easy to online issue GTP commands, or write scripts, for engine testing.

    The protocol is not intended as a user interface for playing games though, even if it can be done for testing purposes.

  2. The protocol intentionally does not include any negotiation options. The controller dictates everything and the engine has to comply, unless it is technically unable to, in which case it has to fail. While this to some extent limits the power of the protocol, it considerably simplifies implementation of both engines and controllers.

    Arguably an engine could fail on purpose as some kind of attempt to force negotiation. This is not encouraged and is considered bad style. A controller has absolutely no obligation to try to work around such failures.

8.2 Detail Comments

8.3 Missing Features

  1. Ruleset Commands and Scoring Options
    This version of the protocol has no provisions to specify what ruleset and/or scoring options to use. This is planned for future revisions but has been omitted here due to the complexity of the issue.

    The reason why this is considered complex is that there are numerous rulesets (using the term loosely) such as Japanese, Chinese, AGA, Ing, IGS, and New Zealand, which differ with respect to one or more of ko rule, area or territory scoring, scoring of seki, legality of suicide, effect of handicap stones on scoring, and so on.

    As a workaround this kind of information has to be passed through other channels than GTP, e.g. as command line options when starting the engine.

    In practice this is not all that much of a problem since these settings rarely vary between games, e.g. within a tournament. Still it is desirable to have this functionality in the protocol, but it is worth waiting for a well thought through design of the commands.

  2. Introspective Commands GNU Go includes a large number of commands to query the board, e.g. list legal moves, find connected strings, count liberties, and so on. These can be useful when writing a ``stupid'' user interface which does not itself know anything about the board logic. They have been omitted from this specification mainly to keep it shorter and make it look less imposing. They are under consideration for inclusion in later revisions.

8.4 Licensing

Anyone may use this protocol for any purpose without any restrictions.

This document may be copied, modified, and distributed according to the terms of the GNU Free Documentation License, included in section 10.

While this in theory allows anyone to create modified protocol specifications, which could potentially lead to great chaos, that would benefit noone and we trust people not be that stupid.

The reason why we allow modification at all is to make sure that new authors can continue evolving the protocol if previous authors disappear, without having to rewrite everything from scratch.

People who want to use this protocol as a basis for development of some other protocol are most welcome to start from this protocol specification.

9 Credits


10 GNU Free Documentation License

Version 1.1, March 2000

Copyright © 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

Preamble

The purpose of this License is to make a manual, textbook, or other written document ``free'' in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of ``copyleft'', which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

10.1 Applicability and Definitions

This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The ``Document'', below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as ``you''.

A ``Modified Version'' of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A ``Secondary Section'' is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The ``Invariant Sections'' are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

The ``Cover Texts'' are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

A ``Transparent'' copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not ``Transparent'' is called ``Opaque''.

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LATEX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

The ``Title Page'' means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, ``Title Page'' means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

10.2 Verbatim Copying

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

10.3 Copying in Quantity

If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

10.4 Modifications

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section entitled ``Endorsements'', provided it contains nothing but endorsements of your Modified Version by various parties - for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

10.5 Combining Documents

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections entitled ``History'' in the various original documents, forming one section entitled ``History''; likewise combine any sections entitled ``Acknowledgements'', and any sections entitled ``Dedications''. You must delete all sections entitled ``Endorsements.''

10.6 Collections of Documents

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

10.7 Aggregation With Independent Works

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an ``aggregate'', and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.

10.8 Translation

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.

10.9 Termination

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

10.10 Future Revisions of This License

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

Copyright © YEAR YOUR NAME. 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 Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled ``GNU Free Documentation License''.

If you have no Invariant Sections, write ``with no Invariant Sections'' instead of saying which ones are invariant. If you have no Front-Cover Texts, write ``no Front-Cover Texts'' instead of ``Front-Cover Texts being LIST''; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

About this document ...

Specification of the Go Text Protocol, version 2, draft 1

This document was generated using the LaTeX2HTML translator Version 2002 (1.67)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -split 0 -show_section_numbers -nonavigation gtp2-spec.tex

The translation was initiated by Gunnar Farneback on 2002-07-12


Gunnar Farneback 2002-07-12