board_game/lib.rs
1#![warn(missing_debug_implementations)]
2#![allow(clippy::too_many_arguments)]
3#![allow(clippy::unusual_byte_groupings)]
4#![allow(clippy::derived_hash_with_manual_eq)]
5#![allow(clippy::assertions_on_constants)]
6#![allow(clippy::new_without_default)]
7
8//! A [Board](crate::board::Board) abstraction for deterministic two player games.
9//! This allows for code to be generic over the actual game, so it only needs to written once.
10//!
11//! # Features
12//!
13//! Currently, the implemented games are:
14//! * [Chess](https://en.wikipedia.org/wiki/Chess) as [ChessBoard](crate::games::chess::ChessBoard),
15//! implemented as a simple wrapper around the [chess](https://crates.io/crates/chess) crate.
16//! * [Go/Baduk](https://en.wikipedia.org/wiki/Go_(game))
17//! as [GoBoard](crate::games::go::board::GoBoard).
18//! * [Super/Ultimate tic-tac-toe](https://en.wikipedia.org/wiki/Ultimate_tic-tac-toe)
19//! as [STTTBoard](crate::games::sttt::STTTBoard).
20//! * [Ataxx](https://en.wikipedia.org/wiki/Ataxx)
21//! as [AtaxxBoard](crate::games::ataxx::board::AtaxxBoard).
22//! * [Oware](https://en.wikipedia.org/wiki/Oware) as [OwareBoard](crate::games::oware::OwareBoard).
23//! * [Connect4](https://en.wikipedia.org/wiki/Connect_Four) as [Connect4](crate::games::connect4::Connect4).
24//! * [Tic Tac Toe](https://en.wikipedia.org/wiki/Tic-tac-toe) as [TTTBoard](crate::games::ttt::TTTBoard).
25//!
26//! Most game implementations are heavily optimized, using bitboards or other techniques where appropriate.
27//!
28//! There are also some utility boards:
29//! * [MaxMovesBoard](crate::games::max_length::MaxMovesBoard)
30//! wraps another board and sets the outcome to a draw after move limit has been reached.
31//! * [DummyGame](crate::games::dummy::DummyGame)
32//! is a board that is constructed from an explicit game tree, useful for debugging.
33//!
34//! Utilities in this crate that work for any [Board](crate::board::Board):
35//! * Game-playing algorithms, specifically:
36//! * [RandomBot](crate::ai::simple::RandomBot),
37//! which simply picks a random move.
38//! * [RolloutBot](crate::ai::simple::RolloutBot),
39//! which simulates a fixed number of random games for each possible move and picks the one with the best win probability.
40//! * [MinimaxBot](crate::ai::minimax::MiniMaxBot),
41//! which picks the best move as evaluated by a customizable heuristic at a fixed depth. (implemented as alpha-beta negamax).
42//! * [MCTSBot](crate::ai::mcts::MCTSBot),
43//! which picks the best move as found by [Monte Carlo Tree Search](https://en.wikipedia.org/wiki/Monte_Carlo_tree_search).
44//! * Random board generation functions, see [board_gen](crate::util::board_gen).
45//! * A bot vs bot game runner to compare playing strength, see [bot_game](crate::util::bot_game).
46//! * Simple game statistics (perft, random game length) which can be used to test board implementations.
47//!
48//! This crate is also used as the foundation for [kZero](https://github.com/KarelPeeters/kZero),
49//! a general AlphaZero implementation.
50//!
51//! # Examples
52//!
53//! ## List the available moves on a board and play a random one.
54//!
55//! ```
56//! # use board_game::games::ataxx::AtaxxBoard;
57//! # use board_game::board::{BoardMoves, Board};
58//! # use internal_iterator::InternalIterator;
59//! # let mut rng = rand::thread_rng();
60//! let mut board = AtaxxBoard::default();
61//! println!("{}", board);
62//!
63//! board.available_moves().unwrap().for_each(|mv| {
64//! println!("{:?}", mv)
65//! });
66//!
67//! let mv = board.random_available_move(&mut rng).unwrap();
68//! println!("Picked move {:?}", mv);
69//! board.play(mv).unwrap();
70//! println!("{}", board);
71//! ```
72//!
73//! ## Get the best move according to MCTS
74//!
75//! ```
76//! # use board_game::ai::mcts::MCTSBot;
77//! # use board_game::games::ataxx::AtaxxBoard;
78//! # use board_game::ai::Bot;
79//! # use rand::thread_rng;
80//! let board = AtaxxBoard::default();
81//! println!("{}", board);
82//!
83//! let mut bot = MCTSBot::new(1000, 2.0, thread_rng());
84//! println!("{:?}", bot.select_move(&board))
85//! ```
86
87// export used game crates
88pub use arimaa_engine_step;
89pub use chess;
90
91pub mod board;
92pub mod symmetry;
93
94pub mod pov;
95pub mod wdl;
96
97pub mod ai;
98pub mod games;
99pub mod heuristic;
100
101pub mod util;
102
103pub mod interface;