Previous: Incremental Board, Up: Libboard
Reading, often called search in computer game
theory, is a fundamental process in GNU Go. This is the process
of generating hypothetical future boards in order to determine
the answer to some question, for example "can these stones live."
Since these are hypothetical future positions, it is important
to be able to undo them, ultimately returning to the present
board. Thus a move stack is maintained during reading. When
a move is tried, by the function trymove
, or its
variant tryko
. This function pushes the current board
on the stack and plays a move. The stack pointer stackp
,
which keeps track of the position, is incremented. The function
popgo()
pops the move stack, decrementing stackp
and
undoing the last move made.
Every successful trymove()
must be matched with a popgo()
.
Thus the correct way of using this function is:
if (trymove(pos, color, ... )) { ... [potentially lots of code here] popgo(); }
In case the move is a ko capture, the legality of the capture is subject to the komaster scheme (see Ko).
int trymove(int pos, int color, const char *message)
Returns true if(pos)
is a legal move forcolor
. In that case, it pushes the board on the stack and makes the move, incrementingstackp
. If the reading code is recording reading variations (as with --decide-string or with -o), the string*message
will be inserted in the SGF file as a comment. The comment will also refer to the string atstr
if this is not0
. The value ofstr
can be NO_MOVE if it is not needed but otherwise the location ofstr
is included in the comment.
int tryko(int pos, int color, const char *message)
tryko()
pushes the position onto the stack, and makes a movepos
ofcolor
. The move is allowed even if it is an illegal ko capture. It is to be imagined thatcolor
has made an intervening ko threat which was answered and now the continuation is to be explored. Return 1 if the move is legal with the above caveat. Returns zero if it is not legal because of suicide.
void popgo()
Pops the move stack. This function must (eventually) be called after a succesfultrymove
ortryko
to restore the board position. It undoes all the changes done by the call totrymove/tryko
and leaves the board in the same state as it was before the call.NOTE: If
trymove/tryko
returns0
, i.e. the tried move was not legal, you must not callpopgo
.
int komaster_trymove(int pos, int color, const char *message, int str, int *is_conditional_ko, int consider_conditional_ko)
Variation oftrymove
/tryko
where ko captures (both conditional and unconditional) must follow a komaster scheme (see Ko).
As you see, trymove()
plays a move which can be easily
retracted (with popgo()
) and it is call thousands of
times per actual game move as GNU Go analyzes the board position.
By contrast the function play_move()
plays a move which
is intended to be permanent, though it is still possible to
undo it if, for example, the opponent retracts a move.
void play_move(int pos, int color)
Play a move. If you want to test for legality you should first callis_legal()
. This function strictly follows the algorithm:In spite of the name “permanent move”, this move can (usually) be unplayed by
- Place a stone of given color on the board.
- If there are any adjacent opponent strings without liberties, remove them and increase the prisoner count.
- If the newly placed stone is part of a string without liberties, remove it and increase the prisoner count.
undo_move()
, but it is significantly more costly than unplaying a temporary move. There are limitations on the available move history, so under certain circumstances the move may not be possible to unplay at a later time.
int undo_move(int n)
Undo `n' permanent moves. Returns 1 if successful and 0 if it fails. If `n' moves cannot be undone, no move is undone.
Other board functions are documented in See Board Utilities.