Chess-Plisco

 view release on metacpan or  search on metacpan

lib/Chess/Plisco.pod  view on Meta::CPAN

=head1 NAME 

Chess::Plisco - A comprehensive chess library for Perl

=encoding utf-8

=head1 SYNOPSIS

    use Chess::Plisco(:all);

    $pos = Chess::Plisco->new;
    $pos = Chess::Plisco->new('k7/8/8/8/8/8/8/7K w - - 0 1');

=head1 DESCRIPTION

B<Chess::Plisco> is a comprehensive chess library for Perl, aiming at being
as fast and efficient as possible for a scripting language.  It is also
somewhat opinionated but this is not an end in itself but owed to its intention
of being fast and efficient.  In doubt, flexibility is sacrificed for
performance and efficiency.

The software also ships a UCI compatible chess engine F<plisco>. If it is
online, you can challenge it on Lichess: L<https://lichess.org/@/plisco-bot>.
On Lichess, it currently has a rating of around 2000, leaving many engines written
in high-level languages like C/C++, Rust, Scala, and C# behind.

The library features:

=over 4

=item bitboards for board representation

=item macros/inline functions for often used computations

=item pseudo-legal move generation

=item legality checks for moves

=item magic bitboards for generation of sliding piece moves and attacks

=item handling of moves in Standard-Algebraic Notation (SAN) as well as coordinate notation

=item FEN (Forsyth-Edwards Notation) import and export

=item EPD (Extended Position Notation) parser

=item Static Exchange Evaluation (SEE)

=item Zobrist Keys

=item Syzygy endgame table probing

=back

For a gentler introduction, please see L<Chess::Plisco::Tutorial>.  The rest
of this document contains reference documentation only.

If performance is key for you, you are strongly advised to have a look at
L<Chess::Plisco::Macro> which documents macros resp. inline functions that
speed up tasks that can be done with L<Chess::Plisco> significantly.

The class exports a number of constants that can either be imported
individually, by export tag, or all at once by the export tag ':all'.  All
constants are prefixed with 'CP_' and you will have little reason to not
import all constants.

=head2 Internals

An instance of a B<Chess::Plisco> is a blessed array reference.  You can
access its properties through accessor macros or by using constants for
the array indices.

A move in B<Chess::Plisco> is a regular scalar, more precisely an unsigned
integer. You can access its properties with the move methods described below.

It is guaranteed that every legal chess move is represented by a non-zero
integer.  It is therefore safe to use moves in boolean context.

=head2 Terminology

For the sake of brevity, this document uses the following terms without
further explanation:

=over 4

=item I<Square>

A square is a square of the chess board as a string like "e4" or "f7".

=item I<Coordinates>

Coordinates are a pair of a file (0-7) and a rank (0-7).

=item I<Shift>

A "shift" is an integer in the range of 0-63 where 0 is the shift for "a1" and
63 is the shift for "h8".

=item I<Bitboard>

A bitboard is an unsigned 64-bit integer.  Each bit stands for one square of
the chess board.

=item I<Shift Mask>

A shift mask is a bitboard with exactly one bit set.  The shift mask
representing "e4" is a 1 shifted left 28 bits, because the shift for "e4" is 28.

=item I<Move>

When an argument is called "move", it is really an integer representing a chess
move.

=item I<Notation>

When an argument is called "notation", it is a supported notation of a chess
move, either Standard-Algebraic Notation SAN or coordinate notation.

=back

lib/Chess/Plisco.pod  view on Meta::CPAN

with L<Time::HiRes/gettimeofday> and reported at the end as well as the
number of nodes found.

This method can be used directly to implement the command "go perft" for a UCI
compatible chess engine.

=back

=head2 Methods for Debugging and Diagnostics

=over 4

=item B<consistent>

Does an extensive consistency check on the position and throws an exception
if any inconsistency is encountered.

=item B<dumpBitboard(BITBOARD)>

Generate a string representation of B<BITBOARD> in ASCII art.

=item B<dumpAll>

Generates a string representation of all bitboards in ASCII art plus some
additional information.

=item B<dumpInfo(INFO)>

Returns a string with the decoded position information as retured by
L</info>.

=item B<movesCoordinateNotation(MOVES)>

Takes an array of moves (as integers) and converts it into an array of moves
in coordinate notation.

=back

=head2 Other Methods

=over 4

=item B<RNG>

Returns a pseudo-random integer created by the well-known xor-shift
pseudo-random number generator.

The random-number generator is always seeded with the same seed (initial value).
This is on purpose, so that the numbers returned are deterministic.  The
method is currently only used for generating the Zobrist keys for position
signatures.

If you want a different seed, you should override the constant
L</CP_RANDOM_SEED>.

=back

=head1 PROPERTIES

You can access individual properties either by using index constants or by
using accessor macros from L<Chess::Plisco::Macro>.  All accessor macros
can be assigned to; they are L-values.  But you are strongly advised
to modify properties of a B<Chess::Plisco> instance only with the methods
documented here.

For getting or setting the bitboard of all white pieces, you have
these options:

    $whites_pieces = $pos->[CP_W_PIECES];
    $white_pieces = cp_w_pieces $pos;
    $white_pieces = cp_w_pieces($pos);
    $pos->[CP_W_PIECES] = $white_pieces;
    cp_w_pieces $pos = $white_pieces;
    cp_w_pieces($pos) = $white_pieces;

The macros (all starting with "cp_") are only available when you have loaded
L<Chess::Plisco::Macro>, see there for more information.

All elements of the position array are documented below under
L</Accessor Indices (:accessors)>.

=head1 EXPORT TAGS

The module exports only constants, all prefixed with "CP_".

Note that (lowercase) macros "cp_" are defined by using
L<Chess::Plisco::Macro>.

=head2 All Constants (:all)

You can import all constants with the export tag ":all".

=head2 Accessor Indices (:accessors)

The array indices were carefully selected so that the following conditions are met:

=over 4

=item All piece types (L</CP_PAWN>, L</CP_KNIGHT>, ..., L</CP_KING>) can be used as indexes into the instance in order to retrieve their respective bitboard

=item The white bitboard comes directly before the black bitboard.

=back

The bitboard for the pieces of the side to move is therefore always at the
location C<CP_POS_WHITE_PIECES + $pos->toMove>.  Or in other words, the
constants C<CP_POS_PAWNS> and C<CP_PAWN> (likewise for the other piece types)
are guaranteed to be the same and to point to the corresponding piece bitboard.

=over 4

=item B<POS_E<gt>[CP_POS_HALFMOVES]>

The number of halfmoves in this position.

=item B<POS-E<gt>[CP_POS_PAWNS]>

A bitboard of all pawns (black and white) on the board.  See also L</pawns>.

=item B<POS-E<gt>[CP_POS_KNIGHTS]>

A bitboard of all knights (black and white) on the board.  See also L</knights>.

=item B<POS-E<gt>[CP_POS_BISHOPS]>

A bitboard of all bishops (black and white) on the board.  See also L</bishops>.

=item B<POS-E<gt>[CP_POS_QUEENS]>

A bitboard of all rooks (black and white) on the board.  See also L</queens>.

=item B<POS-E<gt>[CP_POS_KINGS]>

A bitboard of all kings (black and white) on the board.  See also L</kings>.

=item B<POS-E<gt>[CP_POS_ROOKS]>

A bitboard of all rooks (black and white) on the board.  See also L</rooks>.

=item B<POS-E<gt>[CP_POS_WHITE_PIECES]>

A bitboard of all white pieces on the board. See also L</whitePieces>.

=item B<POS-E<gt>[CP_POS_BLACK_PIECES]>

A bitboard of all black pieces on the board.  See also L</blackPieces>.

lib/Chess/Plisco.pod  view on Meta::CPAN

Value of a queen in centipawns.  Feel free to override this constant in derived
classes.

Note that there is no value for a king.  This is on purpose.

=head3 CP_PIECE_CHARS

An array of arrays that maps numeric piece constants (C<CP_PAWN>, C<CP_KNIGHT>,
...) to characters.  The first array are uppercase letters, normally used
for white pieces, the second one are lowercase letters, normally used for
black pieces.

Example to get the character for a black knight:

    $char = CP_PIECE_CHARS->[CP_BLACK]->[CP_KNIGHT];

=head2 Board Constants (:board)

=head3 CP_A_MASK .. CP_H_MASK

These are bitboards of all files ("a" to "h") of the chess board.

=head3 CP_1_MASK .. CP_8_MASK

These are bitboards of all ranks ("1" to "8") of the chess board.

=head3 CP_WHITE_MASK

Bitboard of all white squares (b1, d1, ... g8)

=head3 CP_BLACK_MASK

Bitboard of all black squares (a1, c1, ... h8)

=head3 CP_LIGHT_MASK

An alias for CP_WHITE_MASK. Added in version 0.7.

=head3 CP_DARK_MASK

An alias for CP_BLACK_MASK. Added in version 0.7.

=head3 CP_FILE_A .. CP_FILE_H

0-based numbers of all files ("a" to "h").

=head3 CP_RANK_1 .. CP_RANK_8

0-based numbers of all ranks ("1" to "8").

=head3 CP_A1 .. CP_H8

Shifts for all squares of the chess board.

=head2 Magic Moves Resp. Magic Bitboard Constants (:magicmoves)

These are all large data tables that are used internally for the magic
bitboards that generate the attack masks for the sliding pieces (queens,
bishops, and rooks).  See the source if you are curious.  Otherwise just import
them if you want to use the macros C<cp_mm_bmagic()> and C<cp_mm_rmagic()>
from L<Chess::Plisco::Macro>.

=head3 CP_MAGICMOVES_B_MAGICS

Internal.

=head3 CP_MAGICMOVES_R_MAGICS

Internal.

=head3 CP_MAGICMOVES_B_MASK

Internal.

=head3 CP_MAGICMOVES_R_MASK

Internal.

=head3 CP_MAGICMOVESBDB

Internal.

=head3 CP_MAGICMOVESRDB

Internal.

=head2 Game State Constants (:game)

This tag has been added in version 0.7.

=head3 CP_GAME_OVER

Bit mask for game state "game over".

=head3 CP_GAME_WHITE_WINS

Bit mask for game state where white has won.

=head3 CP_GAME_BLACK_WINS

Bit mask for game state where black has won.

=head3 CP_GAME_STALEMATE

Bit mask for game state stalemate.

=head3 CP_GAME_FIFTY_MOVES

Bit mask for draw because of the 50-move-rule.

=head3 CP_GAME_THREEFOLD_REPETITION

Bit mask for draw because of threefold repetition.

=head3 CP_GAME_INSUFFICIENT_MATERIAL

Bit mask for draw because of threefold repetition.

=head2 Auxiliary Constants (:aux)

=head3 CP_INT_SIZE

The size in bits of an integer.  Should be at least 64.

=head3 CP_CHAR_BITS

The number of bits in a char.  Should be 8.

=head3 CP_RANDOM_SEED

A pretty arbitrary value used to initialize the pseudo-random number
generator L</RNG>.

=head1 FAQ

=head2 Is It Colour or Color?

That does not have to be decided. You can use either spelling in this library.

=head2 What Does Plisco Mean?

I originally wrote a chess engine in C and named it "tate", just because I
liked the name. But then I found out about Emory Andrew Tate Jr., an
international master of chess. As it turned out, Tate hated chess computers
and never used them. I therefore decided that the name "tate" was inappropriate.

The chess engine was then renamed to "lisco" (in Bulgarian: лиско) which means
fox in Bulgarian. The name of the engine had changed but its countless bugs
remained. I decided that it would be easier to debug the engine in Perl
but all available chess libraries were either too buggy or too slow or both
for using them. So I decided to write a library that was well tested and
fast enough, and that library is now B<Chess::Plisco>. The first letter
P stands for Perl.

=head1 COPYRIGHT

Copyright (C) 2021-2026 Guido Flohr <guido.flohr@cantanea.com>.

=head1 SEE ALSO

L<Chess::Plisco::Macro>, perl(1)