NAME

Games::Go::Referee - Check the moves of a game of Go for rule violations.

SYNOPSIS

Analyse a file:

  use Games::Go::Referee;
  my $referee = new Games::Go::Referee();
  $referee->sgffile('file.sgf');
  print $referee->errors;

or

Analyse move by move:

  use Games::Go::Referee;
  my $referee = new Games::Go::Referee();
  $referee->size(19);
  $referee->ruleset('AGA');
  $referee->play('B','ab');
  $referee->restore(-1) if $referee->errors;

DESCRIPTION

Check a game of Go for rules violations, against a specific rule set.

General use

Games::Go::Referee can be used in two ways; to analyse an sgf file, or to check plays move by move.

If checking a file, the file will be completely read, and any errors found can be displayed later using the errors method. Any illegal plays found are 'allowed' (ie play is assumed to continue as if they were legal). The rule set to be used will be read from the RU sgf property in the file, alternatively various rules can be set manually.

If checking move by move, it may be necessary to specify the size and rule set to be used before starting.

There are basically two rules that can be set: self-capture allowed/disallowed and situational superko (ssk) on/off. If ssk is off, positional superko is assumed.

The following errors are reported:

    Not a board co-ordinate
    Point already occupied
    Illegal setup           (if the setup caused a capture to occur)
    Illegal self-capture
    Board repetition
    Alternation error       (two Black moves in a row for example)
    Play over               (play continues when the game is over)

METHODS

ruleset

The ruleset method sets the rule set to be used. If a file is being checked, the value of the sgf property RU will be used. If that is not found, Japanese rules are assumed.

    $referee->ruleset('AGA');

size

The size method sets the size of the board to be used. If a file is being checked, the value of the sgf property SZ will be used. If that is not found, the board is assumed to be 19 x 19.

    $referee->size(19);

ssk

The ssk method sets or unsets whether the situational superko rule is being used. ssk can be turned on only by using this method, or by specifying 'AGA' via the ruleset method.

    $referee->ssk('on');
    $referee->ssk('off');

selfcapture

The selfcapture method sets or unsets whether self-capture (aka suicide) is allowed or not. selfcapture can be turned on only by using this method, or by specifying New Zealand or Ing via the rulset method.

    $referee->selfcapture('on');
    $referee->selfcapture('off');

passes

The passes method sets the number of consecutive passes required to end the game. The default value is 2. If the Ing ruleset is being used, this value becomes 4.

    $referee->passes(3);

setup

For move by move analysis, the following two methods are availale.

The setup method is used to place preliminary stones on the board.

Setup types (the first argument) are 'AB', 'AW' and 'AE'. Each use of setup can only use one of these types.

Setup points (the second argument) are a list of sgf style board co-ordinates.

    $referee->setup('AW','ii,jj,gh');
    $referee->setup('AB','aa,bb');

If the setup creates group with no liberties, an error is reported. The method returns true if an error was found, otherwise false.

handicap

The handicap method takes as its argument a number from 2 to 9

    $referee->handicap(3);

This method can be used as a convenient way of placing handicap stones, provided the board size is 19, and the rules indicate that handicap placement is fixed (ie neither Ing, AGA nor Chinese).

If handicap placement is fixed, but the board size is not 19, use the setup method.

If handicap placement is not fixed, the handicap method should still be used as then the appropriate number of black consecutive plays will be allowed.

play

Play a move.

Play types (the first argument) are 'B' or 'W'. Each use of play can only use one of these types.

The point played (the second argument) is a single sgf style co-ordinate (or '' for a pass.)

    $referee->play('B','pd');

The method returns true if an error was found, otherwise false.

haslegal

$referee->haslegal($colour); # $colour must be 'B' or 'W'

Returns true if $colour (ie 'B' or 'W') has a legal move, otherwise returns false. Usage example -

    while ($referee->haslegal($colour)){
      my $point = getmove();
      $referee->play($colour, $point);
      if ($referee->errors) {
        $referee->restore(-1);
      } else {
        $colour = ($colour eq 'B') ? 'W' : 'B';
      }
    }

legal

my @points = $referee->legal($colour); # $colour must be 'B' or 'W'

Returns an array of a player's legal move co-ordinates.

Usage example -

    my @legalpoints = $referee->legal($colour);
    while ($#legalpoints >= 0){
      # play a random legal move
      $referee->play($colour, @points[int(rand($#legalpoints))]);
      $colour = ($colour eq 'B') ? 'W' : 'B';
      @legalpoints = $referee->legal($colour);
    }

errors

    print $referee->errors;

Lists any errors occurring either in the file analysed, or as a result of the previous move/setup.

sgffile

  $referee->sgffile('file.sgf');

or

  my $sgf = new Games::Go::SGF('file.sgf');
  $referee->sgffile($sgf);

Specify an sgf file to be analysed.

TODO

Score?

BUGS/CAVEATS

The move number of a reported error is one too large if it occurs in a variation. Putting setup stones within a file (not just the first node) can cause problems. For example, after some stones have been added like this, who is next to play? This needs to be known for situational superko. Currently no look-ahead is done to see who, in fact, played next.

Natural Superko - if I understood the difference between this and SSK, I might put it in.

Ko-pass moves, game resumption ... my head hurts.

AUTHOR (version 0.01)

DG

cpanm Games::Go::Referee

perl -MCPAN -e shell
install Games::Go::Referee