General Information This is version 3.0 of gnugoclient, a program which can be used to connect GNU Go and other go programs to a go server and have it play games without supervision. The requirement on the go program is that it supports the Go Text Protocol (GTP) and can communicate either over TCP/IP or via pipes. When this program is started it connects to the go program, optionally first starting it in a separate process, and then establishes a connection to a specified server, where it waits for match requests. In response to a request it accepts the game and uses GTP commands to set up the game parameters and transfer moves to and from the game until the game is finished or interrupted in some other way, e.g. by adjournment. When the game is over it goes back to listening for match requests. The program is written in Pike. More information about this language can be found at the following site: http://pike.ida.liu.se More information about GNU Go can be found at: http://www.gnu.org/software/gnugo/gnugo.html More information about the Go Text Protocol (GTP) can be found at: http://www.lysator.liu.se/~gunnar/gtp The latest version of gnugoclient should be available at: http://www.lysator.liu.se/~gunnar/gnugo/gnugoclient Author Copyright 1998-2004 by Gunnar Farnebäck. This program is *not* a part of the GNU Go project, although developed in close cooperation. License This program is distributed under the GNU GPL, the GNU General Public License. The license allows modification and redistribution of the program, as long as it remains under the GNU GPL. Details about the license can be found in the file COPYING. Please send bug reports, suggestions for improvements, and patches to gunnar@lysator.liu.se. Features * Completely unsupervised. * Works with any GTP version 2 compliant go program. GTP version 1 support remains but is deprecated and untested. * Can communicate with the engine either over pipes or TCP/IP. * Adjourned games can be resumed. * Support for automatic removal of dead stones in the scoring phase. * Undo supported by replaying the last move (i.e. rejecting the undo). * Automatic reconnection if the connection to the server is lost. * Possible to manually challenge other players. * Possible to manually give commands to the server. * Should work on any platform where Pike is available, which means almost any brand of Unix and possibly also Windows. It has been tested on Debian GNU/Linux and Solaris 9. * Saves game records of all played games locally, as well as logging tells and game results. * Possible to dump complete GTP communication for debugging. * Specific support for the Gifu 2004 tournament. Limitations * Undo supported by replaying the last move (i.e. rejecting the undo). * Does only work with NNGS and compatible servers. IGS support should not be difficult to add but would take some testing to find out the exact protocol differences. Known Bugs Currently none. Installation * Untar the archive. If you read this you most probably have already done that. The available files should be: COPYING - Details of the GPL. NEWS - Summary of changes between versions. README - What you're reading right now. Gifu.pike - Special code for the Gifu 2004 tournament. Gtp.pike - Code to communicate with go programs using the Go Text Protocol. GtpClient.pike - Code to communicate with the server. Sgf.pmod - Code to build and write SGF game records. * If you have not already done this, install Pike version 7.6 (the most recent stable version). Version 7.4 should also work but it is unknown whether older versions do. Pike can be downloaded from http://pike.ida.liu.se. * Make sure pike is in your path or enter the full path directly on the first line of Gnugo.pike. Running Start the program by giving the command ./GtpClient.pike arg1 [arg2 ...] or pike GtpClient.pike arg1 [arg2 ...] There can be any number of arguments and they all specify an option or an options file. Any argument starting with "--" is considered an option while all other are assumed to be files containing options, one per line. Option files are processed first, in the given order, and then the options on the command line are processed, also in the given order. Thus command line options can be used to modify the contents of an option file. Each option is of the form "name=value" or "name=". In the latter case the value is the empty string. The available options and their meaning are discussed in the next section. Examples: ./GtpClient.pike --server_address=nngs.cosmic.org --server_port=9696 --command_line=/usr/local/bin/brown --name=guest This connects to the NNGS server at nngs.cosmic.org 9696 and logs in as guest. The engine is started by running /usr/local/bin/brown and the communication is done over pipes (default). ./GtpClient.pike robot_at_nngs This does the same thing as the previous example, assuming that the file robot_at_nngs contains the lines: server_address=nngs.cosmic.org server_port=9696 command_line=/usr/local/bin/brown name=guest ./GtpClient.pike --name=robot2 --password=xxx robot_at_nngs This first reads in the options from the file robot_at_nngs, then changes the name to be used on the server to robot2 and the password to xxx. Configuration The following options can be set. The default value "[none]" means the empty string. minboard The minimum board size to accept games for. Default: 9 maxboard The maximum board size to accept games for. Default: 19 keepalive Send an "ayt" command every x minutes. On some servers this may be needed to guarantee not being thrown out due to inactivity. Default: 50 server_address IP address of the server to connect to, e.g. "nngs.cosmic.org". Default: [none] server_port IP port for connecting to the server. Default: 9696 server_protocol Name of the protocol used by the server (used internally). Default: nngs Valid values: nngs, pgs server_name Name of the server to be used in the PC property of saved sgf files. Default: [none] command_line Command line used when starting the engine. Arguments are assumed to be split on spaces, shell quoting is not effective. Default: [none] gtp_connection_method How to connect to the engine. Default: pipes Valid values: pipes, tcp_connect, tcp_listen gtp_host Host where the engine is listening for connection if the connection method is tcp_connect. Default: [none] gtp_port Port to listen to for connection from the engine if the connection method is tcp_listen. Port where the engine is listening for connection if the connection method is tcp_connect. Default: [none] blacklist Comma-separated list of opponents we refuse to play with. Default: [none] whitelist Comma-separated list of opponents we want to play with. If this is non-empty, only these opponents are accepted. Default: [none] min_main_time Minimum amount of main time accepted. Default: 0 min_byo_time Minimum amount of byo yomi time accepted. Default: 0 name Name to login with on the server. Default: [none] password Password to use when logging in. If using a guest account this can left empty. Default: [none] sgf_copyright String to use in CP property of saved sgf files. Default: [none] sgf_save_time_info Whether to include time information in saved sgf files. Default: off Valid values: on, off interactive Whether an operator also can enter commands to the server. Default: on Valid values: on, off stone_removal_policy How to handle stone removal in the scoring phase. This can be: * automatic, gnugoclient removes stones based on the response to the final_status_list command. * opponent, the opponent is trusted to do the removal, gnugoclient only says "done" regardless of what is removed. * manual, gnugoclient does nothing and it is left to an operator to perform the scoring. It is not advisable to use "automatic" unless the engine can reliably determine life and death status at the end of the game. "opponent" has the drawback that the opponent can cheat. "manual" requires manual intervention but can be a good alternative to "opponent" in important games or against another robot using "opponent". Default: automatic Valid values: automatic, opponent, manual debug_gtp Whether to print the GTP traffic to the console. Default: off Valid values: on, off showboard_after_move Whether to send the showboard command to the engine after each move, and if debug_gtp is off, copy the response to the console. Default: off Valid values: on, off supervisor Whom the opponent will be referred to if there is a disagreement about the scoring in "automatic" scoring mode. It is recommended to either use your account name on the server or your email address. Default: [none] logfile Name of a file to write log messages to. This may include certain codes described below. Default: ./%s/log dump_gtp_commands Name of a file to write log messages to. This may include certain codes described below. Default: [none] dump_gtp_responses Name of a file to write log messages to. This may include certain codes described below. Default: [none] sgfname_white Name of a file to write log messages to. This may include certain codes described below. Default: ./%s/%n%v-%o-%d.sgf sgfname_black Name of a file to write log messages to. This may include certain codes described below. Default: ./%s/%o-%n%v-%d.sgf All filenames may contain the special codes "%s" and "%N". Names of sgf files may also contain "%n", "%v", and "%o". These codes are replaced by other strings as follows: %s - server name as set by the server_name option %N - login name on the server, as set by the name option %n - engine name as given by the response to the name command %v - engine version as given by the response to the version command %o - name of the current opponent, as given by the server Advanced Configuration If the configuration options above are insufficient, e.g. because the engine can play on 9x9, 13x13, and 19x19 but no other sizes, this can only be solved by further programming. Although modifying the code directly is possible a better option would be to, in a new file, inherit GtpClient.pike and then overload the functions needing modifications. An example of this can be found in the file Gifu.pike. User Instructions For the benefit of the potential opponents on the server, you may wish to include something similar to the following text To play, just set up a game. If I play black and you wish to give me handicap stones, do "tell GnuGo handicap n" before setting up. I can't undo moves. in the info lines that can be viewed with the 'stats' command on the server. 'GnuGo' should of course be replaced by the name you are using. Operator Instructions Assuming that the interactive option is turned on (default), the operator can enter commands to the server, e.g. talking to other players. In particular the match command can be used to set up games. To set up a handicap game where the engine plays black, first issue the command "use_handicap n", which is not forwarded to server, then use the match command as usual. A warning, be careful with the games command, as this may confuse gnugoclient. Gifu instructions The file Gifu.pike contains modifications of GtpClient.pike which are appropriate for the Gifu 2004 tournament. The differences are: * Some default options are changed: - server_address=nngs.computer-go.jp - server_name=Gifu - sgf_save_time_info=on * Only games with time limits of 40 minutes main time and no byo yomi time are accepted. * Komi is automatically set to 6.5 when starting a game. * When scoring is entered, the responses of final_score and final_status_list are written to console and the sgf file. Then the program exits. Running Gifu.pike is no different from GtpClient.pike. Just change the name in the previous instructions. Needed GTP commands The following GTP version 2 commands are used by gnugoclient 3.0: protocol_version name version list_commands quit boardsize clear_board komi play genmove fixed_handicap final_score (*) final_status_list (**) time_settings (***) time_left (***) (*) Optional, result stored as comment in sgf file. (**) Optional, only needed if you want automatic removal of dead stones. (***) Optional, needed if you want to get time information. Gunnar Farnebäck Boston, September 13, 2004