kgsGtp documentation

This page is out of date. Instead, please read the documentation that was
included with your download of kgsGtp.

Basics

GTP (Go Text Protocol) is a protocol that allows computer go playing
programs (called "engines") to communicate with other programs. It was
designed to be an improvement on the older "Go Modem Protocol". It is
easy to implement and very useful for controlling go programs. Documentation
on this standard can be found
at the GTP home page.

There is a KGS client called kgsGtp which understands both GTP and
the KGS server's protocol. It can serve as a bridge, connecting the GTP
engine to the KGS server, allowing the GTP engine to play on KGS.

How to Run kgsGtp

First, you need to create an account on KGS, using the standard KGS client.
Then you need to set up a configuration file for kgsGtp. Lastly, you need
to run both it and the GTP engine together. Since kgsGtp is a java program
that comes bundled as a jar file, you usually run it with a command line
like this:

java -jar kgsGtp.jar <config file><extra options>

kgsGtp requires java 1.5 or later to run. No external libraries are
needed.

When you run kgsGtp, you must specify a config file. This is a standard
Java properties file. It is plain text, with one option specified per line,
in the format:

optionName=optionValue

Like all java properties files, the file is encoded in ISO-8859-1; if
you need to represent other characters, you will need to use escape sequences.
The standard Java programs "native2ascii" or "ascii2native" is the best
way to write these secape sequences. Search
http://java.sun.com for more information on using these
tools.

In addition to these options, you can put options in the command line.
Any options in both the command line and the config file will use the command
line value and ignore what is in the config file.

Connecting kgsGtp to the GTP Engine

There are five ways that kgsGtp can be connected to the GTP engine:

1. Have kgsGtp start the engine

To do this, just use the "engine=engine command line"
option in either the config file or on the command line. The engine must read
from its standard input to get the GTP commands, and write its responses to
its standard output.

2. Use named pipes

You need two named pipes - one for the engine to kgsGtp, and one for kgsGtp
to the engine. Run kgsGtp, and instead of specifying the engine, you need
to specify "gtp.in=Engine to kgsGtp file" and
"gtp.out=kgsGtp to engine file". If you have an engine
set, that will override these settings, and they will be ignored!

3. Use TCP/IP sockets

If you specify "engine.port=port number" then
kgsGtp will open up a TCP port and start listening. It expects the
next inbound connection to be the engine.

4. Use stdin/stdout

This system is used if no options are present. You just need to make sure
that stdin for kgsGtp it connected to the engine's output and stdout for
kgsGtp is connected to the engine's input. Usually, the easiest way to do
this is by forking and execing kgsGtp from within
your engine.

5. Use kgsGtp as a library in a Java engine

kgsGtp can be used as a library in a java engine. You need to
construct a set of configuration options, construct the client, then
tell it to start:

package org.igoweb.igoweb.client.gtp;
public class GtpClient {
/**
* Create a new GTP Client.
*
* @param in An input stream that will give us any responses from the engine.
* @param out An output stream that will go to the engine with our commands.
* @param args Our options.
*/
public GtpClient(java.io.InputStream in, java.io.OutputStream out,
Options options);
/**
* Connect to the server and operate the GTP interface.
*
* @return <code>true</code> on success, <code>false</code> if we were
* unable to do what was requested.
*/
public boolean go();
}
public class Options {
/**
* Construct a new set of options for the kgsGtp client by pulling values
* out of a set of properties. Any values that we use will be removed from
* the properties, so anything left over is unused.
*
* @param props The properties that holds our options as string values.
* @param logName The name of the java logger that we will construct.
* @throws IllegalArgumentException If any required values are missing or if
* any illegal values are detected.
*/
public Options(java.util.Properties props, String logName);
}

Just add kgsGtp.jar to your classpath, then construct a set of
options from a Properties object. Once you have the options,
you can construct a client. The input and output streams must be from
your engine. Once you have build a GTP client, just call
go() and it will start running. It will return only after
shutting down.

kgsGtp Options

Running kgsGtp with the single option -help lists all options.
Here is a more detailed list:

Logging Options

logFile

Specifies that logging should be done to a file instead of to
stderr. The value is the name of the file to use.

verbose

Setting this to t will make kgsGtp emit a lot of logging
info. Every message between kgsGtp and the engine will be logged
and a lot of KGS server events will be logged as well.

Engine Connection
Options

gtp.in

Specifies a named pipe to read GTP responses from. Ignored if the
option engine is set.

gtp.out

Specifies a named pipe to write GTP commands to. Ignored if the
option engine is set.

engine

Specifies the command line to run to create the engine.

KGS Connection
Options

server.host

Sets the host name or IP address of the KGS server. You only
need to set this if you are tunneling through a port
forwarder (for example, to get through a firewall).

server.port

Sets the TCP port of the KGS server. You only
need to set this if you are going through a port forwarder.

reconnect

If set, the client will try to reconnect to the server if it gets
cut off. It will not reconnect if the GTP engine dies or if there is
an error in the GTP protocol.

name

The user name of your KGS account. Required.

password

The password of your KGS account. Required.

room

The room that the engine should join. If this isn't set, then it
will join the same room it was in last time it connected. The
engine can only be in one room.

open

Setting this to t will make the engine create an open
game and wait for challenges. Either this, tournament,
or opponent must be specified.

opponent

Sets the user name who the engine is to play. If open is
set, then any challenges that come from any other user will be
declined. If open is not set, then the engine will look
for open games by the given opponent, and challenge them. Either
this, open, or tournament must be
specified.

tournament

Setting this to t indicates that you intend to be playing in a
tournament. All tournament games will be accepted, all others will be
ignored. Either this, open, or opponent must be
specified.

undo

Setting this to f will refuse all undos. Normally, undo is
allowed in free games the engine allows it and refused in ranked games.

Options on the
servers

talk

If anybody tries to talk to the engine in a private
conversation, it will answer with
this message. Should be something like "I'm a computer program
and cannot talk."

hint.noArguing

If your engine does not support the
kgs-genmove_cleanup command (or the game uses
Japanese rules, where kgs-genmove_cleanup can't be
used), and your opponent does not agree with the dead stones
that the engine settled on, then this message will be
written to your opponent. It should tell them that they must either
agree with the engine or leave the game. The default message
does exactly that, in English.

hint.cleanup

If kgs-genmove_cleanup is usable in this game, and
your opponent disagrees on which stones are dead, then this
message is sent to them. It should tell them to undo if they
want to play out the game to determine which stones are
dead. The default message says exactly that, in English.

gameNotes

Sets the notes that will appear in any open games that are
created.

rules

Should be one of japanese, chinese, aga,
or newzealand. Sets the rules that will be used when it
creates an open game. People can override this though, so this
doesn't guarantee that the rules will actually be used.

rules.boardSize

Sets the size of the board that will be in open games. Again, it
can be overridden.

rules.time

Sets the time system that will appear in open games. There are
several formats:

"0" for no time limit.

"m:ss" for absolute time. For example, 30:00 for a game
where each player has a half hour for all their moves.

"m:ss+nxm:ss" for byo-yomi time. For example,
30:00+5x0:30 for a half hour of main time and 5 byo-yomi periods
of 30 seconds each.

"m:ss+n/m:ss" for canadian time. For example,
30:00+25/10:00 means a half hour of main time, with 10 minute
byo-yomi periods of 25 stones each.

Example kgsGtp Config File

This example config file was used when I was testing kgsGtp. It
connects as "gtpProg" and plays anybody who challenges. Gnugo is run
by kgsGtp to provide the engine.

kgsGtp's use of GTP

kgsGtp does not use all of GTP's commands. Only a very small set of
commands (three, in fact) are absolutely required. Any non-required
commands may be sent to the engine, but it is acceptable for the
engine to simply return errors for all of them. These are the commands
that it will send to engines:

Administrative Commands

list_commands — Recommended

Sent when first connecting to the client. kgsGtp will never send
nonstandard commands unless the engine states that they are supported. kgsGtp
may send standard commands even though the engine does not claim to support
them. If you do not support list_commands then only very
basic functionality will be used in your engine.

name — Optional

version — Optional

The name and version are added as comments every time that kgsGtp starts
a game. If the engine does not provide a name and version,
then nothing will be written. If you use non-ASCII characters in the
name or version of your engine, these characters must be encoded using
UTF-8.

quit — Optional

If clear_board is not supported, then we send a quit
after the game ends because there is nothing else we can do. If the
quit fails, then we just close everything up with an error.

Setup Commands

boardsize — Required

This will be sent before the game starts. If you cannot play the
size specified, reply with an error. Any challenges that come with
board sizes that your engine cannot support will not be accepted. Note
that you will often get multiple boardsize commands before
the game start - one or more as each challenge comes in to ensure that
your engine can play the board size specified, then a final
boardsize when the game actually starts.

clear_board — Recommended

Used before each game to ensure a clean starting point. If you
don't support this, then you will be limited to one game for each time
you run kgsGtp.

komi — Optional

Sent when each game starts up.

place_free_handicap — Recommended

set_free_handicap — Recommended

Used to set or ask for handicap stone positions. The fixed handicap
GTP command is not used. If the game is fixed handicap, you
will get the set_free_handicap command instead. GTP does
not have enough flexibility in its fixed handicap command to support
KGS. If your engine does not support these commands then handicap
games will be refused.

Core Play Commands

play — Required

genmove — Required

Used as normal.

undo — Optional

If your engine supports this command, you will get it as normal. If your
engine does not include undo as a response to
list_commands, then KGS will use clear_board
followed by a series of play commands when an undo is
required. If your engine supports neither of these commands, then
any undos that your opponents request will be denied.

Tournament Commands

time_settings — Optional

kgs-time_settings — Optional

Similar to the boardsize command, you may get several
time settings commands; any settings that your engine cannot play with,
you should return an error. If your engine supports the
kgs-time_settings command, then you will get that instead of
the standard time_settings command. The reson for the
KGS-specific time setting is that GTP's standard time settings has no
way to describe the byo-yomi time system. This system is quite popular
in tournaments and is used often on KGS. The format for the
kgs-time_settings command is the same as
time_settings, but another parameter is inserted
as the first parameter, which describes the time system as either
none, absolute, byoyomi, or canadian.
For the none and absolute time systems there will be
fewer than two options. If you do not support kgs-time_settings
and your engine is put into a byo-yomi game, kgsGtp will tell your engine
that it is an absolute time game with no byo-yomi periods and a total time
equal to the main time and all of the periods.

time_left — Optional

Used as normal.

final_status_list — Optional, required for rated
games

After the game enters scoring kgsGtp will send this command,
asking for dead stones. kgsGtp will never ask questions about seki,
only about dead stones. If you successfully return a list of dead
stones, then kgsGtp will mark those on the board. If you return an
error, then kgsGtp will not mark any stones dead and your opponent
will have to do that instead.

kgs-genmove_cleanup — Optional, recommended for
playing ranked games

This is a kgsGtp-specific command. Engines that support it should treat
it the same as the genmove command, except that they should not pass
until all dead stones are removed from the board. This is used by kgsGtp
when the engine and the opponent disagree on which stones are dead at the
end of the game.

KGS and Ranked Games

It is important that ranked games do not allow people to "cheat" and abuse
the engine or kgsGtp to inflate their personal ranks. The possible ways to
cheat include:

Marking living stones dead, or dead stones living, to change the score
of a lost game to a won game.

Escaping from games that you are losing.

Setting time parameters so that the engine cannot hope to win (for example,
if the engine always uses at least 5 seconds per move, you can set the time
to give only 3 seconds per move, then play random moves very fast until you
win).

Running kgsGtp in your own account to inflate your rank (this obviously
only works if you have an engine that is stronger than yourself).

Running the engine standalone, and copying its moves into your games
that you play with the standard client.

Clearly
there is no way to stop #5, but fortunately that technique is fairly tedious
so most players probably will not be interested in doing that.

To try to keep a handle on ranked game play on the server, to
prevent players from cheating on the engines (or using engines to
cheat for themselves), kgsGtp will behave as follows when playing
ranked games:

"Normal" accounts cannot play ranked games when connected by GTP,
only when using one of the "human" clients.

Accounts can be set to "Ranked Robot" authorization. Please email to
admin@igoweb.org to ask for this
authorization. Once it is set for an account, the GTP engine can play
ranked against other GTP engines or against "human" clients, and humans who
log in to that account cannot play ranked games.

A kgsGtp engine will refuse to start a new ranked game with a
player if there is already an unfinished ranked game against that
player.

To play ranked games, an engine must support the
final_status_list command.

All undos are declined in ranked games.

The kgsGtp engine will refuse to play ranked unless the rules of the game
exactly match what is specified in the configuration file and/or command
line.

If the engine and the human disagree on the status of living and dead
stones at the end of the game, one of two things will happen: If the game
uses non-Japanese rules and the engine supports the
kgs-genmove_cleanup command, then kgsGtp will recommend
that the human press "undo", after which play will continue but the engine
will get kgs-genmove_cleanup commands (in place of genmove
commands). In all other cases, kgsGtp will simply refuse to finish the game
unless the human agrees to the dead stones that the engine listed in its
response to the final_status_list command.

It is recommended that engines that play ranked games support the
kgs-genmove_cleanup command and play non-Japanese rules
games. It is especially important that your engine support that
command if it isn't so good at computing living/dead groups at the
end of the game, otherwise you will get a lot of angry opponents
left standing around in an unfinished game!

Changes

Version 2.6.11:

Fixed bug that would send kgs-genmove_cleanup in games with
Japanese rules.

Version 2.6.10:

Will now claim win when opponent runs out of time.

Fixed several bugs that made it impossible to use kgsGtp as a java
library.

Added ability to play in tournaments.

Added undo option.

Fixed a bug that would make the client hang when it got an error response
from final_status_list.

Fixed a bug that would hit if the engine is playing black in a handicap
game, supports clear_board but not undo, and the opponent
chooses to make an undo.

Fixed a bug that would make it crash when the engine reported no
dead stones.

Version 2.5.6 beta4:

Fixed a bug that made it crash on startup

Version 2.5.6 beta3:

Undo will use clear_board and a rebuild of the whole board if
either the client doesn't support undo or if an undo
fails.

If you enter a game and your opponent is not there when you enter, it
sets up a timer to give up and leave as if the opponent had left the
game.

If you support the kgs-genmove_cleanup command, you can play
rated.

The "talk" option works now.

If the engine gets stuck and never answers a command, it will not
make an open game until the command is answered.

Ranked games works (on server 2.5.6 or later).

Version 2.5.6 beta2:

Now checks to make sure that boardsize and
time_settings succeed before a challenge is
accepted.

Does a clear_board before starting a game,
instead of after.

Shuts down cleanly when the engine goes away instead of
stalling.

Can now resume games. When your opponent loads a game, if kgsGtp
is waiting for a challenge, then it drops the challenge and joins
the game. Note: This will not work on server 2.5.5 because
of a server bug that prevents you from loading games when your
opponent is waiting for a match. When KGS server 2.5.6 is out, this
will work.

Is better about returning errors instead of exiting when there is
a problem.