/ 
Game-Checkers-0.01
/ Game::Checkers::Squares

NAME

Game::Checkers::Squares - the board numbering, and the step and jump tables built from it

VERSION

Version 0.01

SYNOPSIS

use Game::Checkers::Squares;

my ($row, $col) = Game::Checkers::Squares::coords(15);
my $steps = Game::Checkers::Squares::steps(15);      # { NE => 11, NW => 10, SE => 19, SW => 18 }
my ($over, $landing) = Game::Checkers::Squares::jump(15, 'SE');   # (19, 24)

DESCRIPTION

The standard draughts numbering, with Black's back rank at the top of the board. Rows run 1 to 8 from the top and files a to h from the left. Only the 32 dark squares play, numbered 1 to 32 from left to right and top to bottom: squares 1 to 4 are the top row and 29 to 32 the bottom row.

Black starts on squares 1 to 12 and moves toward higher numbers. White starts on squares 21 to 32 and moves toward lower numbers. Black moves first.

Directions are board absolute, with north at the top, so SE means one row down and one column right whichever colour is moving. Forward is a per colour lookup through "forward_dirs" and never a sign in the caller.

Every function dies on a square outside 1 to 32 or a side that is not black or white: those are programmer errors, not player mistakes, and a player's mistake is a Game::Checkers::Error instead.

PACKAGE VARIABLES

The tables are built once when the module is loaded and are the fast path the search uses. They are documented because Game::Checkers::Bot reads them directly rather than calling an accessor several million times a move.

@STEP

$STEP[($n * 4) + $dir] is the square one step from $n in $dir, or 0 when that step leaves the board.

@JUMP_OVER and @JUMP_TO

$JUMP_TO[($n * 4) + $dir] is the square a jump from $n in $dir lands on and $JUMP_OVER[...] is the square it passes over, or 0 in both when no jump in that direction fits on the board. A direction with a step but no landing square has 0 in both, so testing @JUMP_TO alone is enough.

@ROW and @COL

$ROW[$n] and $COL[$n] are the zero based row and column of square $n. Row 0 is Black's back rank.

CONSTANTS

NE, NW, SE and SW are the direction indices 0, 1, 2 and 3. @DIRS is all four in that order and @DIR_NAME maps an index back to its name.

FUNCTIONS

coords

Returns the zero based row and column of a square.

my ($row, $col) = Game::Checkers::Squares::coords(9);   # (2, 1)

square

Returns the square number at a row and column, or undef when the coordinates are off the board or name a light square. Unlike the rest of this module it does not die, because it is the function used to walk off the edge on purpose.

Game::Checkers::Squares::square(2, 1);   # 9
Game::Checkers::Squares::square(2, 2);   # undef, a light square

row_of

The zero based row of a square, 0 for Black's back rank and 7 for White's.

col_of

The zero based column of a square.

coord_name

The algebraic name of a square for display, with file a on the left and rank 8 on Black's back rank.

Game::Checkers::Squares::coord_name(1);   # 'b8'

coord_square

The square an algebraic name stands for, or undef when the name is not one of the 32 playing squares. The file may be upper case. Like "square" it does not die, because it is given what somebody typed.

Game::Checkers::Squares::coord_square('b8');   # 1
Game::Checkers::Squares::coord_square('a8');   # undef, a light square

steps

Returns a hashref of the four neighbouring squares by direction name, with undef for a direction that leaves the board.

Game::Checkers::Squares::steps(5);   # { NE => 1, NW => undef, SE => 9, SW => undef }

jump

Returns the jumped square and the landing square for a jump from $n in $dir, or the empty list when no such jump fits on the board. The direction may be a name or an index.

my ($over, $landing) = Game::Checkers::Squares::jump(9, 'SE');   # (14, 18)

dir_index

Turns a direction name into its index, passing an index through unchanged.

dir_name

Turns a direction index into its name.

forward_dirs

The two directions a man of the given side moves in.

my @dirs = Game::Checkers::Squares::forward_dirs('black');   # (SE, SW)

crowning

True when the square is the given side's promotion row: 29 to 32 for Black and 1 to 4 for White.

AUTHOR

LNATION, <email at lnation.org>

BUGS

Please report any bugs or feature requests to bug-game-checkers at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Game-Checkers. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Game::Checkers

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)