<chapter id="setup">
<title>Setup Commands</title>

<indexterm>
<primary>setup</primary>
</indexterm>

<para>
The GTP version 2 specification contains no commands for setting up
positions by specifying the location of stones on the board.
GoGui will send setup stones as moves to the Go program, if possible.
</para>
<para>
This method has disadvantages.
For example, the program cannot know that these moves are not real moves
and if it maintains its own game tree for saving information like search
traces, the internal trees will start with a long series of move nodes, if
an initial setup position was transmitted by moves.
</para>
<para>
Therefore, GoGui defines the following GTP extension commands for setting up
positions, which will be used if the Go program supports them:
<variablelist>
<varlistentry>
<term><command>gogui-setup</command></term>
<listitem>
<para>
The argument to this command is a sequence of color point
pairs (like for <command>gogui-play_sequence</command>).
The effect of the command is that the stones are placed on the board.
This command should only be sent after a <command>clear_board</command> and
return a failure, if the board is not empty.
It is allowed to setup positions that contain blocks with no liberties.
If the Go program cannot handle such positions it should detect it and
respond with a failure.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>gogui-setup_player</command></term>
<listitem>
<para>
The argument is a color (<userinput>b</userinput> or <userinput>w</userinput>)
and should set the color to play in the setup position.
This command is sent after the <command>gogui-setup</command> command, but
only, if the color to play is known and if the command is supported by the Go
program.
Note that the color to play is not always well-defined (e.g. for combinatorial
subgames) or known (e.g. SGF files with setup stones, but no player property).
Support for this command is optional, because it is not a critical condition,
if the engine is not informed about the color to play, although it can be
desirable in some situations.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para><!-- Empty paragraph to enforce space in JEditorPane --></para>

</chapter>
