<chapter id="compatibility">

<title>Compatibility</title>

<indexterm>
<primary><acronym>Go Text Protocol</acronym></primary>
</indexterm>

<para>
GoGui will work with all programs that can understand the most basic commands
of version 1 or 2 of the
<ulink url="http://www.lysator.liu.se/~gunnar/gtp/">Go Text Protocol</ulink>.
</para>
<para><!-- Empty paragraph to enforce space in JEditorPane --></para>

<section>
<title>Required Commands</title>

<para>
It is required that the Go program can handle the following commands:
</para>

<itemizedlist>
<listitem>
<simpara>
<command>boardsize</command>, <command>clear_board</command>
(<command>boardsize</command>)
</simpara>
</listitem>
<listitem>
<simpara>
<command>play</command>
(<command>black</command>, <command>white</command>)
</simpara>
</listitem>
<listitem>
<simpara>
<command>genmove</command>
(<command>genmove_black</command>, <command>genmove_white</command>)
</simpara>
</listitem>
</itemizedlist>

<para>
The commands in parentheses are used if the program supports
the <command>protocol_version</command> command and responds with 1.
</para>

<para>
If the Go engine does not support generating moves, because it provides
only other functionality, it is recommended that it implements
<command>list_commands</command>, so that GoGui can detect that
<command>genmove</command> is not supported.
In this case, GoGui will always set the computer color by default to None, so
that the engine should not be made playing moves automatically.
Since the user can still issue play commands, it is recommended that the
engine responds to a <command>genmove</command> command with a meaningful
failure response.
</para>

<para><!-- Empty paragraph to enforce space in JEditorPane --></para>
</section>

<section>
<title>Optional Commands</title>

<para>
The following other commands are used by GoGui:
</para>

<itemizedlist>
<listitem>
<simpara>
<command>name</command>
</simpara>
</listitem>
<listitem>
<simpara>
<command>final_status_list dead</command>
</simpara>
</listitem>
<listitem>
<simpara>
<command>gg-undo</command>
</simpara>
</listitem>
<listitem>
<simpara>
<command>list_commands</command>
(<command>help</command>)
</simpara>
</listitem>
<listitem>
<simpara>
<command>kgs-genmove_cleanup</command>
</simpara>
</listitem>
<listitem>
<simpara>
<command>komi</command>
</simpara>
</listitem>
<listitem>
<simpara>
<command>set_free_handicap</command>
</simpara>
</listitem>
<listitem>
<simpara>
<command>time_left</command>
</simpara>
</listitem>
<listitem>
<simpara>
<command>time_settings</command>
</simpara>
</listitem>
<listitem>
<simpara>
<command>undo</command>
</simpara>
</listitem>
<listitem>
<simpara>
<command>version</command>
</simpara>
</listitem>
<listitem>
<simpara>
<command>quit</command>
</simpara>
</listitem>
</itemizedlist>

<para>
If the Go program does not understand them, you will still be able to play
games, but you cannot use all of the functionality of GoGui.
If <command>undo</command> is not supported, the position will be
synchronized with the Go program after an undo by sending the complete
game from the beginning.
If <command>set_free_handicap</command> is not supported, GoGui
will transmit handicap stones with <command>play</command> commands.
</para>

<para>
The command <command>gg-undo</command> is en extension command used by GNU Go,
which differs from <command>undo</command> by an optional integer argument
to undo multiple moves.
</para>

<para>
The following GoGui specific GTP extension commands are used if supported by
the program:
</para>

<variablelist>
<varlistentry>
<term><command>gogui-analyze_commands</command></term>
<listitem>
<para>
See <xref linkend="analyze"/>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>gogui-interrupt</command></term>
<listitem>
<para>
See <xref linkend="interrupt"/>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>gogui-sigint</command></term>
<listitem>
<para>
See <xref linkend="interrupt"/>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>gogui-title</command></term>
<listitem>
<para>
For providing a window title, which may be game specific, or include
a player name that is not known at program creation time.
The title is queried and set after a new game is started.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>gogui-play_sequence</command></term>
<listitem>
<para>
This is an extension to the standard <command>play</command> command which
can take a sequence of moves.
If the Go program supports it (together with GNU Go's
<command>gg-undo</command> for multiple undo), then navigating in games
will be much faster, because only a single command is used instead of a
large number of <command>play</command> and <command>undo</command> commands).
Note that the command line length can become large for this command; the Go
program should not use a limit for the command length.
The Go program is expected to return a failure and not to change its current
board state if it cannot execute all of the moves in the sequence.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>gogui-setup</command></term>
<listitem>
<para>
See <xref linkend="setup"/>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>gogui-setup_player</command></term>
<listitem>
<para>
See <xref linkend="setup"/>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para><!-- Empty paragraph to enforce space in JEditorPane --></para>
</section>

</chapter>
