Running a GTP Engine on KGS

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.4 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

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 four 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 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.

4. Use kgsGtp as a library in a Java engine

kgsGtp can be used as a library in a java engine. The only API entries you need are a constructor and a function to start it: 
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 logger A logger to write any status to.
   * @param args Our options.
   */
  public GtpClient(java.io.InputStream in, java.io.OutputStream out,
                   java.util.logging.Logger logger, java.util.Properties args);

  /**
   * 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();
}

Just add kgsGtp.jar to your classpath, then construct a GTP client. The input and output streams must be from your engine. The logger is a standard java logger, it will report status. The properties has any options you need to pass in. 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
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 or opponent (or both) 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 or open (or both) must be specified.
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."
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. 
name=gtpProg
password=pxss!rd
room=English Room
open=t
gameNotes=Connecting GnuGo to KGS
rules=chinese
rules.boardSize=19
rules.time=10:00+25/10:00
verbose=t
engine=/home/wms/src/gnugo-3.4/interface/gnugo --mode gtp

kgsGtp's use of GTP

kgsGtp does not use all of GTP's commands. These are the commands that it will send to engines:

list_commands
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
version
The name and version are added as comments every time that kgsGtp starts a game. They are optional; 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.
boardsize
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.
komi
Sent when each game starts up.
time_settings
kgs-time_settings
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.
place_free_handicap
set_free_handicap
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.
play
genmove
time_left
Used as normal. If your engine does not support time_left then you may simply return errors from it.
undo
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 any undos that your opponents request will be denied, so this command is optional from kgsGtp's point of view.
final_status_list
After the game enters scoring kgsGtp will send this command. If you 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.
clear_board
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.

Limitations

Free games only. GTP has no way to argue over dead stones at the end of the game, so if your opponent changes the stones that you mark dead, kgsGtp simply accepts the changes. This makes it very easy to cheat a kgsGtp player, so only free games are allowed right now. To let it play rated games, I may add a genmove extension that never passes, and tries to kill a group. For example, if the human insists that a group is alive and the engine thinks it is dead, something like genmove_nopass would tell it to keep playing and kill "dead" groups on the board. This could be used in non-Japanese rule sets to resolve disagreements at the end of the game. I may implement a kgs-specific command like this in the future.

Another option would be to refuse to let the game finish if your opponent disagrees with the set of living/dead stones. This could work fairly well with engines that are good at determining living/dead stones, but would cause lots of problems with engines that aren't as accurate.

Changes

Since 2.5.6 beta1: