Crate cozy_chess
source ·Expand description
§cozy-chess
§Rust Chess and Chess960 move generation library
cozy-chess
is a Chess and Chess960 (Fischer Random Chess) move generation library written in Rust that aims to provide competitive move generation performance. It is largely inspired by Jordan Bray’s neat chess
library. cozy-chess
aims to be a safer alternative to chess
that maintains correctness while providing similar performance.
§Overview
no_std
compatible- Supports Chess, Chess960/FRC, and Double Chess960/DFRC
- Strongly-typed API that makes heavy use of newtypes to avoid errors
- Performant legal move generation suitable for use in a chess engine
- Implements fixed shift fancy black magic bitboards
- Optionally implements PEXT bitboards based on the BMI2 intrinsic
- Flexible API produces moves in bulk for optional bulk filtering
- Efficient bitboard-based board representation
- Incrementally updated zobrist hash for quickly obtaining a hash of a board
§Crate features
std
: Enable features that requirestd
. Currently only used for theError
trait.pext
: Enable PEXT bitboards.
§A note on CPU features and performance
By default, Rust binaries target a baseline CPU to ensure maximum compatibility at the cost of performance. cozy-chess
benefits significantly from features present in modern CPUs. For maximum performance, the target CPU can instead be set to native
to use features supported by the machine running the build. Alternatively, the target CPU can be set to x86-64-v3
, which will produce binaries that run on most modern CPUs. The target CPU may be changed by adding -C target-cpu=<CPU>
to RUSTFLAGS
.
PEXT bitboards are a faster variant of the magic bitboard algorithm used by cozy-chess
. PEXT bitboards rely on an intrinsic introduced in the BMI2 CPU extension. However, it is not enabled by default, as PEXT bitboards are slower on AMD CPUs prior to Zen 3, which implement PEXT with microcode. PEXT bitboards can be enabled through the pext
feature.
§A note on UCI parsing
In order to support Chess960, cozy-chess
uses a king-captures-rook castling notation incompatible with the standard castling representation used by the UCI protocol. This is a common use case, so the cozy_chess::util
module provides helpers that automatically parse and convert between the formats.
§Examples
§Basic example
// Start position
let board = Board::default();
let mut move_list = Vec::new();
board.generate_moves(|moves| {
// Unpack dense move set into move list
move_list.extend(moves);
false
});
assert_eq!(move_list.len(), 20);
§Get capture moves in bulk
// Parse position from FEN
let board = "r3k2r/p1ppqpb1/bn2pnp1/3PN3/1p2P3/2N2Q1p/PPPBBPPP/R3K2R w KQkq - 0 1"
.parse::<Board>()
.unwrap();
let mut total_moves = 0;
let mut total_captures = 0;
let enemy_pieces = board.colors(!board.side_to_move());
board.generate_moves(|moves| {
let mut captures = moves.clone();
// Bitmask to efficiently get all captures set-wise.
// Excluding en passant square for convenience.
captures.to &= enemy_pieces;
total_moves += moves.len();
total_captures += captures.len();
false
});
assert_eq!(total_moves, 48);
assert_eq!(total_captures, 8);
§Perft example
A perft implementation exists in examples/perft.rs
:
$ cargo run --release --example perft -- 7
Compiling cozy-chess v0.3.0
Finished release [optimized] target(s) in 6.37s
Running `target\release\examples\perft.exe 7`
3195901860 nodes in 10.05s (318045465 nps)
§Changelog
§v0.3.4
§Added
- Added helper methods for handling UCI moves.
- Added
Square::relative_to
to get a square relative to some color.
§v0.3.3
§Added
- Added setters for the halfmove clock and fullmove number fields.
§Fixed
- Fixed checkmate not taking precedence over 50 move rule draw.
- Fixed possible overflows on halfmove clock and fullmove number.
§v0.3.2
§Fixed
- Fixed bug where en passant was not correctly validated when parsing and building
Board
s.
§v0.3.1
§Fixed
- Fixed bug where
Board::is_legal
said castles while in check were legal.
§v0.3.0
§Added
- Added methods for obtaining Chess960 start positions from their Scharnagl number.
- Added PEXT bitboards using the BMI2 PEXT intrinsic. Potentially faster than the default algorithm. Enable using the
pext
feature. - Added
Board::hash_without_ep
method for fast equivalence checks excluding the en passant square. - Added
Board::same_position
to check if two boards are equivalent under FIDE rules. - Added
Board::colored_pieces
, a shorthand forboard.colors(color) & board.pieces(piece)
. - Added
BitBoard::is_subset
,BitBoard::is_superset
, andBitBoard::is_disjoint
.
§Changed (breaking)
BitBoard
s now operate in a more set-wise manner instead of acting like au64
. Bit operators changed to match set operators.BitBoard::popcnt
renamed toBitBoard::len
for consistency with other data structures.BoardBuilder
’sfullmove_number
field changed to au16
for usability reasons.Board
’sFromStr
implementation now parses both FEN and Shredder FEN.
§Removed (breaking)
BitBoard
no longer implementsIterator
directly.- Sliding move functions are no longer
const
by default; Use theconst
variants if required. - Unnecessary “try” variants on
Board
removed; The risk of panicking is accepted when*_unchecked
methods are called.
§Fixed
- Overflow bug in
Square::try_offset
fixed. FenParseError
is no longer unnameable.- Fixed incorrect errors being returned in FEN parsing.
- Fixed some errors not being produced in FEN parsing.
Modules§
- Additional common utilities
Macros§
BitBoard
literal macro.
Structs§
- A bitboard. A bitboard is an ordered set of squares.
- An iterator over the squares of a bitboard.
- An iterator over the subsets of a bitboard.
- A chessboard.
- A board builder to manipulate arbitrary boards.
- Castling rights.
- The value was not a valid
Color
. - The value was not a valid
File
. - An error returned when the move played was illegal.
- A chess move.
- The value was not a valid
Move
. - A compact structure representing multiple moves for a piece on the board. Iterate it to unpack its moves.
- Iterator over the moves in a
PieceMoves
instance. - The value was not a valid
Piece
. - The value was not a valid
Rank
. - The value was not a valid
Square
.
Enums§
- An error while building a board.
- A side to move.
- An error while parsing the FEN.
- A file on a chessboard.
- The current state of the game.
- A chess piece. Pieces are ordered by approximate material value.
- A rank on a chessboard.
- A square on a chessboard. Squares are ordered in rank-major order (A1, B1, C1, … H8).
Functions§
- Get all squares between two squares, if reachable via a ray.
- Get the moves for a bishop on some square. See
get_bishop_moves_const
for a significantly slowerconst
variant. - Significantly slower
const
version ofget_bishop_moves
. - Get the rays for a bishop on some square.
- Get the king moves for a king on some square.
- Get the knight moves for a knight on some square.
- Get a ray on the board that passes through both squares, if it exists.
- Get the pawn attacks for a pawn on some square.
- Get the pawn forward moves/non-captures for a pawn of some color on some square.
- Get the moves for a rook on some square. See
get_rook_moves_const
for a significantly slowerconst
variant. - Significantly slower
const
version ofget_rook_moves
. - Get the rays for a rook on some square.