Chess::Plisco - A comprehensive chess library for Perl
use Chess::Plisco(:all); $pos = Chess::Plisco->new; $pos = Chess::Plisco->new('k7/8/8/8/8/8/8/7K w - - 0 1');
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 library features:
For a gentler introduction, please see 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 Chess::Plisco::Macro which documents macros resp. inline functions that speed up tasks that can be done with 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.
An instance of a 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 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.
For the sake of brevity, this document uses the following terms without further explanation:
A square is a square of the chess board as a string like "e4" or "f7".
Coordinates are a pair of a file (0-7) and a rank (0-7).
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".
A bitboard is an unsigned 64-bit integer. Each bit stands for one square of the chess board.
A mask is a bitboard with exactly one bit set. The mask representing "e4" is a 1 shifted left 28 bits, because the shift for "e4" is 28.
When an argument is called "move", it is really an integer representing a chess move.
When an argument is called "notation", it is a supported notation of a chess move, either Standard-Algebraic Notation SAN or coordinate notation.
Chess::Plisco requires 64-bit support for Perl. It will not run on 32-bit Perls.
Chess::Rep and Chess::Play provide similar functionality. Both compile a lot faster than Chess::Plisco but once compiled, a perft test of Chess::Plisco runs more than 30 times faster than one of Chess::Play and more than 100 times faster than one of Chess::Rep.
At the time of this writing, Chess::Plisco also outperforms python-chess by about 50 %.
Creates a new Chess::Plisco instance that represents the starting position of standard chess.
If an argument is passed to the constructor, it is interpreted as a position in Forsyth-Edwards Notation (FEN). This has the same effect as using the constructor newFromFEN.
newFromFEN
Creates a new Chess::Plisco instance from a string containing the Forsyth-Edwards Notation (FEN) of a chess position. The only difference to new() is that the string argument is required.
new()
This constructor may throw an exception if the described position does not meet the requirements of the library.
All legal chess positions meet the requirements of the library. But positions that are not legal and may cause the library to malfunction, are rejected.
Clones POSITION.
In string context, the position is encoded in Forsyth-Edwards Notation. No other operators are overloaded.
Note that the Forsyth-Edwards Notation does not cover all aspects of a chess position, especially the history of moves. String-wise equality of two instances of a Chess::Plisco does therefore not imply that the two positions are identical. Use the method "equal" for a strict equality check.
Renders the position to Forsyth-Edwards Notation. Alternatively, you can just use the object as a string:
$position = Chess::Plisco->new; say $position->toFEN; say "$position"; # Does the same as above.
Returns a list of legal moves for the current position. A move is just an integer.
Generates all pseudo-legal moves for the current position.
Pseudo-legal are all moves that can be executed by the pieces on the side to move ignoring whether the side to move is in check after the move.
Only the lower 15 bits of the move are set, that means the start and destination square, and a possible promotion piece.
If you also need the captured piece and the color, you either have to call "legalMoves" or you must use the state information returned from "doMove" to retrieve the enriched move. The first element of the state array is the enriched move.
Like "pseudoLegalMoves" but only returns "interesting" moves. Interesting moves are captures, promotions, and moves directly giving check. Discovered checks are not generated. This has performance reasons.
You will want to call this method for generating moves in a quiescence search. Since quiescence search is imperfect anyway, it is assumed that ignoring discovered checks does not have a negative impact.
Future versions of this library may include discovered checks.
Returns true if the current position is equivalent to POSITION.
Returns the bitboard of all white pieces.
Returns the bitboard of all black pieces.
Returns the bitboard of all squares that are occupied by any piece.
Returns the bitboard of all squares that are not occupied by any piece.
Returns the bitboard of all kings (black and white).
Returns the bitboard of all queens (black and white).
Returns the bitboard of all rooks (black and white).
Returns the bitboard of all bishops (black and white).
Returns the bitboard of all knights (black and white).
Returns the bitboard of all pawns (black and white).
Returns the side to move, either "CP_BLACK" or "CP_WHITE".
Returns the number of half-moves made. Initially, this is 0. After white has made their first move, it is 1. After black has made their first move, it is 2, and so on.
Returns the number of reversible moves immediately leading to the current position. The following moves are irreversible:
Reason: A pawn cannot move backwards.
Reason: Captured pieces are gone for good.
Reason: The side to move loses the castling rights.
Reason: The side to move loses at least one of their castling rights.
Reason: The side to move loses the castling rights. This is also implied by the fact that they are necessarily the first king move.
The half-move-clock is important because both players can claim a draw, when the half-move clock has reached 50.
Returns a 64-bit Zobrist key (aka 64-bit integer) that identifies the position. Properties taken into account are:
Note that hash collisions albeit unlikely, may occur because 64 bit are, of course, not sufficient to uniquely identify a chess position.
The signature computed for a certain position is guaranteed not to change for one release of Chess::Plisco. In order to compute different signatures, you have to override either the pseudo-random number generator "RNG" or its seed "CP_RANDOM_SEED". If you turn the constant "CP_RANDOM_SEED" into a non-constant subroutine, you can also get different signatures, whenever you re-load the library.
Returns false if the side to move is not in check, a truthy value otherwise. The truthy value returned is a bitboard of all pieces giving check.
If the side to move is in check, returns the required check evasion strategy:
The king must move. This is the case, when multiple pieces give check.
Either the king must move or the piece giving check must be captured.
Either the king must move, the piece giving check must be captured, or another piece must be moved between the king and the attacking piece.
If a check can be evaded by moving a piece between the king and the attacking piece of the opponent, this bitboard gives all squares where the check can be blocked. These are all squares between the king and the attacking piece, including the square where the attacker is standing.
If en-passant is possible, returns the shift of the square where the capturing pawn has to move. If en-passant is not possible, 0 is returned. 0 happens to be the shift of "a1" but "a1" is not a valid en-passant square. It is therefore safe to use this method in boolean context.
Gives the material balance from the perspective of the white player. That means that all white pieces have a positive value, and all black pieces have a negative value.
The values are:
These constants can be overridden by inheriting from Chess::Plisco.
Note: Kings do not count!
Returns a truthy value if white still has the right to castle king-side ("O-O"), false otherwise.
Returns a truthy value if white still has the right to castle queen-side, ("O-O-O"), false otherwise.
Returns a truthy value if black still has the right to castle king-side ("O-O"), false otherwise.
Returns a truthy value if black still has the right to castle queen-side, ("O-O-O"), false otherwise.
Returns a bitmap of castling rights for the current position:
Return the shift of the square of the king of the side to move. This information is needed internally.
Returns an integer encoding various other aspects of the position. You do not need this because there are dedicated methods available for all these properties.
Parses the string NOTATION into an integer representing the move or returns false, if the NOTATION cannot be parsed or is an illegal move.
NOTATION can either be a move in Standard Algebraic Notation (SAN) or in coordinate notation. Coordinate notation is the format used by most chess engines and is the concatenation of the start and destination square and a possible promotion piece, for example "e2e4" or "f2f1q".
Renders the integer MOVE into Standard-Algebraic Notation SAN, for example "e4", "Bxc4", "O-O", or "fxe1=Q".
Renders the integer MOVE into coordinate notation, for example "e2e4" or "f2f1q".
Returns the Long Algebraic Notation LAN of the move. This is an alias for "moveCoordinateNotation".
Returns true if the significant parts of MOVE1 and MOVE2 are equivalent. This is the case, when the start and destination square, and a possible promotion piece are equal.
Although, this is technically a class method you should keep in mind that the redundant parts of the moves depend on the current position.
Extracts the shift (0-63) of the starting square.
Sets the shift (0-63) of the starting square in MOVE to FROM and returns the move.
Extracts the shift (0-63) of the destination square.
Sets the shift (0-63) of the destination square in MOVE to TO and returns the move.
Extracts the piece that a pawn is promoted to if the move is a promotion. Returns either "CP_QUEEN", "CP_ROOK", "CP_BISHOP", or "CP_KNIGHT".
Sets the piece to promote to in MOVE to PROMOTE and returns the move. The piece should be one of "CP_QUEEN", "CP_ROOK", "CP_BISHOP", or "CP_KNIGHT".
Extracts the piece that does the move. Returns one of "CP_KING", "CP_QUEEN", "CP_ROOK", "CP_BISHOP", "CP_KNIGHT", or "CP_PAWN".
Sets the piece that moves in MOVE to PIECE and returns the move. The piece should be one of "CP_KING", "CP_QUEEN", "CP_ROOK", "CP_BISHOP", "CP_KNIGHT", or "CP_PAWN".
Extracts the piece that gets captured if any. Returns one of "CP_QUEEN", "CP_ROOK", "CP_BISHOP", "CP_KNIGHT", "CP_PAWN", "CP_NO_PIECE".
Sets the piece that gets captured in MOVE to PIECE and returns the move. The piece should be one of "CP_QUEEN", "CP_ROOK", "CP_BISHOP", "CP_KNIGHT", "CP_PAWN", "CP_NO_PIECE".
Extracts the color that does the move.
Sets the color in MOVE to COLOR and returns the move.
Returns a truthy value, when the argument is a valid and legal move. The move can be given either as an integer returned by "parseMove" or as a string that is accepted by "parseMove".
Parses the move given in NOTATION and applies it to the position if the move is valid and legal. Otherwise false is returned. You can also pass the move as an integer as returned by "parseMove".
The method returns state information that can later be used to undo the move and reset the position to the state it had before the move was applied.
Engines should use the method "doMove" instead because it is faster.
If STATE is state information returned by "applyMove", takes back the move that was given as an argument to "applyMove".
Engines should use the method "undoMove" instead because it is faster.
Applies the move represented by the integer(!) MOVE to the position. If the move is legal, the method returns state information that can be used to undo the move with "undoMove".
The method returns false, if the move is illegal. Note that this is not a complete legality check but works only for those moves that "pseudoLegalMoves" has returned for the current position.
This method is fast and is the one that should be used by engines.
The state information returned is an array of various bits of information. The first one is the move itself but the captured piece is set in that move.
If STATE is state information returned by "doMove", takes back the move that was given as an argument to "doMove".
Does a static exchange evaluation SEE for move MOVE. MOVE must be a capture, a promotion, a move giving check, or any combination of it. It returns the raw material balance expected from the move.
The routine assumes, that after MOVE had been made, all moves that re-capture on the target field of MOVE will be executed, starting with the least valuable attacker of each side proceeding to the most valuable attacker. As soon as a re-capture becomes disadvantageous, the sequence stops, and the balance up to that point is returned.
Disadvantageous means that advancing to the "next round" would make the result worse. For example a bishop would not normally capture a pawn that is protected.
If you assign different values to bishops and knights by overriding "CP_KNIGHT_VALUE" and "CP_BISHOP_VALUE" you may receive small values by this routine, if the exchange of bishops and knights is involved. Depending on your preferences you may ignore absolute values under a certain threshold, for example 100 centipawns.
It should also be noted that the routine assumes that the values of pieces follows this relation:
pawn < knight <= bishop < rook < queen (< king)
Converts SQUARE to a shift.
This is a class method.
Converts SQUARE to coordinates. It returns a list, not a an array reference. Be sure to call it in array context!
Converts SHIFT to a square.
Converts a shift to coordinates. It returns a list, not a an array reference. Be sure to call it in array context!
Converts coordinates to a square.
Converts coordinates to a shift.
The following methods answer the question which piece of which color occupies a particular location on the chess board.
In array context returns a pair of a piece and a color. In scalar context, only the piece is returned. The piece is one of "CP_PAWN", "CP_KNIGHT", "CP_BISHOP", "CP_ROOK", "CP_QUEEN", "CP_KING", or "CP_NO_PIECE" if the square is empty.
The color is one of "CP_BLACK" or "CP_WHITE". If the square is empty, undef is returned instead of a color.
undef
This method is relatively expensive!
These methods can be used to analyze features of the current position.
Returns true if the ssquare indicated by SHIFT is attacked by a piece of the opponent.
Returns true if when executing MOVE, the moving piece would be attacked by a piece of the opponent. A typical usage example would be to check if the king moving from FROM to TO would move into check.
You can give the move either as an integer or in one of the supported move notations.
Returns true if a piece doing MOVE is pinned. A piece is pinned if it would leave the king in check when doing the move. Exposing other pieces to an opponent attack is not considered a pin by this method.
Returns a bitboard of all squares that a rook can reach from SHIFT. OCCUPANCY is a bitboard of all squares that are occupied by pieces. The first piece that the sliding piece would reach is considered a potential captured of a capture and is a valid target square.
See "Understanding rMagic and bMagic" in Chess::Plisco::Tutorial for more information.
rMagic
bMagic
Returns a bitboard of all squares that a bishop can reach from SHIFT. OCCUPANCY is a bitboard of all squares that are occupied by pieces. The first piece that the sliding piece would reach is considered a potential captured of a capture and is a valid target square.
Counts and returns the bits sets in BITBOARD.
This does the same as the builtin function __builtin_popcountll of the C compilers llvm and gcc.
__builtin_popcountll
Clears the least signicant bit that is set in BITBOARD.
Clears all set bits in BITBOARD except for the least significant one that is set.
Counts all trailing zero bits, that is all bits that are not set starting with the least significant bit (bit number 0).
Counts all trailing zero bits, that is all bits that are not set starting with the least significant bit (bit number 0). In other words, this method gives you the shift of the set bit in BITBOARD. It only works if exactlye one bit is set in BITBOARD, otherwise the behavior is undefined.
This does the same as the builtin function __builtin_ctzll of the C compilers llvm and gcc.
__builtin_ctzll
A "perft" (PERFormance Test) is a standard test for measuring the performance of the move generator. Starting from the current position, it generates all legal moves up to the specified depth. It is also important for testing the correct functioning of the move generator because the number of leave nodes for certain positions are well known.
Internally, each legal move is applied to the position, then the next level is computed from the resulting position, and finally the move is undone.
Does a performance test for the current position to depth DEPTH. Returns the number of leaf nodes found.
Instead of calling "undoMove" the moves found are applied to a copy of the current position that is discarded later. This is currently slightly faster than undoing the move programatically with "undoMove".
Moves are undone programmatically with "undoMove". This is currently slightly slower than just copying the position, see "perftByCopy".
Does the the same as perftByCopy but prints out all top-level moves found with the number of subnodes for each move. The time needed is measured with "gettimeofday" in Time::HiRes 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.
Does the the same as perftByUndo but prints out all top-level moves found with the number of subnodes for each move. The time needed is measured with "gettimeofday" in Time::HiRes and reported at the end as well as the number of nodes found.
Does an extensive consistency check on the position and throws an exception if any inconsistency is encountered.
Generate a string representation of BITBOARD in ASCII art.
Generates a string representation of all bitboards in ASCII art plus some additional information.
Returns a string with the decoded position information as retured by "info".
Takes an array of moves (as integers) and converts it into an array of moves in coordinate notation.
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 "CP_RANDOM_SEED".
You can access individual properties either by using index constants or by using accessor macros from Chess::Plisco::Macro. All accessor macros can be assigned to; they are L-values. But you are strongly advised to modify properties of a 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 Chess::Plisco::Macro, see there for more information.
All elements of the position array are documented below under "Accessor Indexes (:accessors)".
The module exports only constants, all prefixed with "CP_".
Note that (lowercase) macros "cp_" are defined by using Chess::Plisco::Macro.
You can import all constants with the export tag ":all".
The array indices were carefully so that the following conditions are met:
The bitboard for the pieces of the side to move is therefore always at the location CP_POS_WHITE_PIECES + $pos-toMove>. Or in other words, the constants CP_POS_PAWNS and CP_PAWN (likewise for the other piece types) are guaranteed to be the same and to point to the corresponding piece bitboard.
CP_POS_WHITE_PIECES + $pos-
CP_POS_PAWNS
CP_PAWN
A bitboard of all white pieces on the board. See also "whitePieces".
A bitboard of all black pieces on the board. See also "blackPieces".
A bitboard of all kings (black and white) on the board. See also "kings".
A bitboard of all rooks (black and white) on the board. See also "queens".
A bitboard of all rooks (black and white) on the board. See also "rooks".
A bitboard of all bishops (black and white) on the board. See also "bishops".
A bitboard of all knights (black and white) on the board. See also "knights".
A bitboard of all pawns (black and white) on the board. See also "pawns".
The number of half-moves made. See also "halfMoves".
The current value of the half-move clock. See also "halfMoveClock".
Bitmask of pieces giving check. See also "inCheck".
Bitboard of squares where a check can be blocked. See also "evasionSquares".
Same as "signature".
Additional properties of the position. See also "info".
Symbolic constant for white pieces, side to move, and so on.
Symbolic constant for black pieces, side to move, and so on. Actually, usage of this constant is avoided internally so that any truthy value can be used. Most of the time, this is simply the else branch of a conditional.
Symbolic constant for no piece.
Symbolic constant for a pawn.
Symbolic constant for a knight.
Symbolic constant for a bishop.
Symbolic constant for a rook.
Symbolic constant for a queen.
Symbolic constant for a king.
Value of a pawn in centipawns. Feel free to override this constant in derived classes.
Value of a knight in centipawns. Feel free to override this constant in derived classes.
Value of a bishop in centipawns. Feel free to override this constant in derived classes.
Value of a rook in centipawns. Feel free to override this constant in derived classes.
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.
An array of arrays that maps numeric piece constants (CP_PAWN, 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.
CP_KNIGHT
Example to get the character for a black knight:
$char = CP_PIECE_CHARS->[CP_BLACK]->[CP_KNIGHT];
These are bitboards of all files ("a" to "h") of the chess board.
These are bitboards of all ranks ("1" to "8") of the chess board.
0-based numbers of all files ("a" to "h").
0-based numbers of all ranks ("1" to "8").
Shifts for all squares of the chess board.
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 cp_mm_bmagic() and cp_mm_rmagic() from Chess::Plisco::Macro.
cp_mm_bmagic()
cp_mm_rmagic()
Internal.
The size in bits of an integer. Should be at least 64.
The number of bits in a char. Should be 8.
A pretty arbitrary value used to initialize the pseudo-random number generator "RNG".
Copyright (C) 2021 Guido Flohr <guido.flohr@cantanea.com>.
Chess::Plisco::Macro, perl(1)
To install Chess::Plisco, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Chess::Plisco
CPAN shell
perl -MCPAN -e shell install Chess::Plisco
For more information on module installation, please visit the detailed CPAN module installation guide.