kgsGtp

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:

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:

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

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:

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.

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.

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

Setup Commands

Core Play Commands

Tournament Commands

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:

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:

kgsGtp documentation