17. Application Programmers Interface to GNU Go

If you want to write your own interface to GNU Go, or if you want to create a go application using the GNU Go engine, this chapter is of interest to you.

First an overview: GNU Go consists of two parts: the GNU Go engine and a program (user interface) which uses this engine. These are linked together into one binary. The current program implements the following user modes:

• An interactive board playable on ASCII terminals
• solo play - GNU Go plays against itself
• replay - a mode which lets the user investigate moves in an existing SGF file.
• GMP - Go Modem Protocol, a protocol for automatic play between two computers.
• GTP - Go Text Protocol, a more general go protocol, see section The Go Text Protocol.

The GNU Go engine can be used in other applications. For example, supplied with GNU Go is another program using the engine, called ‘debugboard’, in the directory ‘interface/debugboard/’. The program debugboard lets the user load SGF files and can then interactively look at different properties of the position such as group status and eye status.

The purpose of this Chapter is to show how to interface your own program such as debugboard with the GNU Go engine.

Figure 1 describes the structure of a program using the GNU Go engine.

                 +-----------------------------------+
                 |                                   |
                 |          Go application           |
                 |                                   |
                 +-----+----------+------+           |
                 |     |          |      |           |
                 |     |   Game   |      |           |
                 |     | handling |      |           |
                 |     |          |      |           |
                 |     +----+-----+      |           |
                 |   SGF    |    Move    |           |
                 | handling | generation |           |
                 |          |            |           |
                 +----------+------------+-----------+
                 |                                   |
                 |           Board handling          |
                 |                                   |
                 +-----------------------------------+
     
        Figure 1: The structure of a program using the GNU Go engine

The foundation is a library called libboard.a which provides efficient handling of a go board with rule checks for moves, with incremental handling of connected strings of stones and with methods to efficiently hash go positions.

On top of this, there is a library which helps the application use Smart Game Format (SGF) files, with complete handling of game trees in memory and in files. This library is called libsgf.a

The main part of the code within GNU Go is the move generation library which given a position generates a move. This part of the engine can also be used to manipulate a go position, add or remove stones, do tactical and strategic reading and to query the engine for legal moves. These functions are collected into libengine.a.

The game handling code helps the application programmer keep tracks of the moves in a game. Games can be saved to SGF files and then later be read back again. These are also within libengine.a.

The responsibility of the application is to provide the user with a user interface, graphical or not, and let the user interact with the engine.

17.1 How to use the engine in your own program: getting started

To use the GNU Go engine in your own program you must include the file ‘gnugo.h’. This file describes the whole public API. There is another file, ‘liberty.h’, which describes the internal interface within the engine. If you want to make a new module within the engine, e.g. for suggesting moves you will have to include this file also. In this section we will only describe the public interface.

Before you do anything else, you have to call the function init_gnugo(). This function initializes everything within the engine. It takes one parameter: the number of megabytes the engine can use for the internal hash table. In addition to this the engine will use a few megabytes for other purposesode>debof megabyteol, a pror theif; fonoi | /codeFFFFF" text="#020000" link="#0000FF" vlink="#800080" alink="#FF0000">

BOARDSIZE is the actual size of the 1D board array, BOARDMIN is the first index corresponding to a point on the board, and BOARDMAX is one larger than the last index corresponding to a point on the board.

Often one wants to traverse the board, carrying out some function at every vertex. Here are two possible ways of doing this:

  int m, n;
  for (m = 0; m < board_size;ding ordea"> < ]< "> < ]< "> <  is the firle" align="le #
 4|   # , vali #
 link="#0000r>