chess
chess copied to clipboard
A rust library to manage chess move generation
A Fast Chess Library In Rust
This library handles the process of move generation within a chess engine or chess UI.
This library follows semver for version numbering in the format MAJOR.MINOR.PATCH. That means:
- Any change to the API that breaks existing code will involve a MAJOR version number change.
- Any added functionality or features that do not break existing applications will involve a MINOR version number change.
- Any bug fixes or performance improvements that do not affect users will involve a PATCH version change.
Requires Rust 1.31 or Greater
This library requires rust version 1.27 or greater in order to check for the BMI2 instruction-set at compile-time. Additionally, this build is compatible with rust 2018 which, I believe, requires rust 1.31.
Note: bmi2 has been disabled due to horrible performance on AMD architectures. I have instead opted to expose the two relevant functions publicly if on a bmi2 CPU.
Examples
Incremental Move Generation With Capture/Non-Capture Sorting
Here we iterate over all moves with incremental move generation. The iterator below will generate moves as you are going through the list, which is ideal for situations where not all moves will be looked at (such as in an engine search function).
use chess::MoveGen;
use chess::Board;
use chess::EMPTY;
// create a board with the initial position
let board = Board::default();
// create an iterable
let mut iterable = MoveGen::new_legal(&board);
// make sure .len() works.
assert_eq!(iterable.len(), 20); // the .len() function does *not* consume the iterator
// lets iterate over targets.
let targets = board.color_combined(!board.side_to_move());
iterable.set_iterator_mask(targets);
// count the number of targets
let mut count = 0;
for _ in &mut iterable {
count += 1;
// This move captures one of my opponents pieces (with the exception of en passant)
}
// now, iterate over the rest of the moves
iterable.set_iterator_mask(!EMPTY);
for _ in &mut iterable {
count += 1;
// This move does not capture anything
}
// make sure it works
assert_eq!(count, 20);
Setting up a position
The Board
structure tries to keep the position legal at all times. This can be annoying when setting up a board, for example via user input.
To deal with this, the BoardBuilder
structure was introduced in 3.1.0. BoardBuilder
structure follows a non-consuming builder pattern and can be converted to a Result<Board, Error>
via Board::try_from(...)
or board_builder.try_into()
.
use chess::{Board, BoardBuilder, Piece, Square, Color};
use std::convert::TryInto;
let mut board_builder = BoardBuilder::new();
board_builder.piece(Square::A1, Piece::King, Color::White)
.piece(Square::A8, Piece::Rook, Color::Black)
.piece(Square::D1, Piece::King, Color::Black);
let board: Board = board_builder.try_into()?;
Making a Move
Here we make a move on the chess board. The board is a copy-on-make structure, meaning every time you make a move, you create a new chess board. You can use board.make_move()
to update the current position, but you cannot unmake the move. The board structure is optimized for size to reduce copy-time.
use chess::{Board, ChessMove, Square, Color};
let m = ChessMove::new(Square::D2, Square::D4, None);
let board = Board::default();
assert_eq!(board.make_move_new(m).side_to_move(), Color::Black);
Representing a Full Game
There is more to chess than just what is on the board. The Game
object keeps track of the history of the game to allow draw offers, resignations, draw by 50 move rule, draw by repetition, and in general anything that needs the history of the game.
use chess::{Game, Square, ChessMove};
let b1c3 = ChessMove::new(Square::B1, Square::C3, None);
let c3b1 = ChessMove::new(Square::C3, Square::B1, None);
let b8c6 = ChessMove::new(Square::B8, Square::C6, None);
let c6b8 = ChessMove::new(Square::C6, Square::B8, None);
let mut game = Game::new();
assert_eq!(game.can_declare_draw(), false);
game.make_move(b1c3);
game.make_move(b8c6);
game.make_move(c3b1);
game.make_move(c6b8);
assert_eq!(game.can_declare_draw(), false); // position has shown up twice
game.make_move(b1c3);
game.make_move(b8c6);
game.make_move(c3b1);
game.make_move(c6b8);
assert_eq!(game.can_declare_draw(), true); // position has shown up three times
FEN Strings
BoardBuilder
, Board
, and Game
all implement FromStr
to allow you to convert an FEN string into the object. Additionally, BoardBuilder
and Board
implement std::fmt::Display
to convert them into an FEN string.
use chess::Board;
use std::str::FromStr;
assert_eq!(
Board::from_str("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1")
.expect("Valid Position"),
Board::default()
);
Compile-time Options
When compiling, I definitely recommend using RUSTFLAGS="-C target-cpu=native", specifically to gain access to the popcnt and ctzl instruction available on almost all modern CPUs. This is used internally to figure out how many pieces are on a bitboard, and what square a piece is on respectively. Because of the type system used here, these tasks become literally a single instruction. Additionally, BMI2 is enabled on machines with the instructions by using this flag.
BMI2
As of version 1.0.3 of this library, the BMI2 instruction-set is used on machines that support it. This speeds up the logic in two ways:
- It uses built-in instructions to do the same logic that magic bitboards do.
- It reduces cache load by storing moves in a u16 rather than a u64, which can be decompressed to a u64 with a single instruction.
On targets without BMI2, the library falls back on magic bitboards. This is checked at compile-time.
Shakmaty
Another rust chess library is in the 'shakmaty' crate. This is a great library, with many more features than this one. It supports various chess variants, as well as the UCI protocol. However, those features come at a cost, and this library performs consistently faster in all test cases I can throw at it. To compare the two, I have added 'shakmaty' support to the 'chess_perft' application, and moved a bunch of benchmarks to that crate. You can view the results at https://github.com/jordanbray/chess_perft.
What It Does
This library allows you to create a chess board from a FEN-formatted string, list all legal moves for the chess board and make moves.
This library also allows you to view various pieces of board-state information such as castle rights.
This library has very fast move generation (the primary purposes of its existance), which will be optimized more. All the tricks to make chess move generation fast are used.
What It Does Not Do
This is not a chess engine, just the move generator. This is not a chess UI, just the move generator. This is not a chess PGN parser, database, UCI communicator, XBOARD/WinBoard protocol, website or grandmaster. Just a humble move generator.
API Documentation
... is available at https://jordanbray.github.io/chess/chess/.
Anything Else
Nope. Have fun.