diff --git a/crates/games/src/chomp/README.md b/crates/games/src/chomp/README.md new file mode 100644 index 0000000..ba4357d --- /dev/null +++ b/crates/games/src/chomp/README.md @@ -0,0 +1,12 @@ +Chomp is a two-player game played on a rectangular grid of squares. +The bottom right square is poisoned, and the players take turns eating squares. +Every square they eat, every square to the right and above it is also eaten (inclusively) + +This is a flipped version of the traditional [Chomp](https://en.wikipedia.org/wiki/Chomp) game. + +This is not the best example for analysis via a combinatorial game, as not only is it +impartial (making it analyzable via the Sprague-Grundy theorem), but it is also trivially +solved via the strategy-stealing argument. + +However, it serves as a great test for the transposition table, as it is a game that commonly +repeats positions (as it only has nxm - 1 positions). diff --git a/crates/games/src/chomp/cli.rs b/crates/games/src/chomp/cli.rs index dfc0648..54f4b56 100644 --- a/crates/games/src/chomp/cli.rs +++ b/crates/games/src/chomp/cli.rs @@ -7,6 +7,9 @@ use crate::chomp::Chomp; use super::ChompMove; +/// Analyzes Chomp. +/// +#[doc = include_str!("./README.md")] #[derive(Args)] pub struct ChompArgs { /// The width of the game diff --git a/crates/games/src/chomp/mod.rs b/crates/games/src/chomp/mod.rs index 2a2ccd3..117673e 100644 --- a/crates/games/src/chomp/mod.rs +++ b/crates/games/src/chomp/mod.rs @@ -1,15 +1,4 @@ -//! Chomp is a two-player game played on a rectangular grid of squares. -//! The bottom right square is poisoned, and the players take turns eating squares. -//! Every square they eat, every square to the right and above it is also eaten (inclusively) -//! -//! This is a flipped version of the traditional [Chomp](https://en.wikipedia.org/wiki/Chomp) game. -//! -//! This is not the best example for analysis via a combinatorial game, as not only is it -//! impartial (making it analyzable via the Sprague-Grundy theorem), but it is also trivially -//! solved via the strategy-stealing argument. -//! -//! However, it serves as a great test for the transposition table, as it is a game that commonly -//! repeats positions (as it only has nxm - 1 positions). +#[doc = include_str!("./README.md")] pub mod cli; diff --git a/crates/games/src/domineering/README.md b/crates/games/src/domineering/README.md new file mode 100644 index 0000000..640f963 --- /dev/null +++ b/crates/games/src/domineering/README.md @@ -0,0 +1,5 @@ +Connect 4 is a two-player game played on a 7x6 grid. Players take turns placing pieces on the +bottom row, and the pieces fall to the lowest available square in the column. +The first player to get 4 in a row (horizontally, vertically, or diagonally) wins. + +Learn more: diff --git a/crates/games/src/domineering/cli.rs b/crates/games/src/domineering/cli.rs index f7ec2ff..6971c98 100644 --- a/crates/games/src/domineering/cli.rs +++ b/crates/games/src/domineering/cli.rs @@ -1,3 +1,5 @@ +#[doc = include_str!("./README.md")] + use std::{ collections::HashMap, fmt::{Display, Formatter}, @@ -26,6 +28,9 @@ impl Display for Domineering, diff --git a/crates/games/src/domineering/mod.rs b/crates/games/src/domineering/mod.rs index 0211827..c19fcb9 100644 --- a/crates/games/src/domineering/mod.rs +++ b/crates/games/src/domineering/mod.rs @@ -1,9 +1,3 @@ -//! Connect 4 is a two-player game played on a 7x6 grid. Players take turns placing pieces on the -//! bottom row, and the pieces fall to the lowest available square in the column. -//! The first player to get 4 in a row (horizontally, vertically, or diagonally) wins. -//! -//! Learn more: https://en.wikipedia.org/wiki/Connect_Four - pub mod cli; use array2d::Array2D; diff --git a/crates/games/src/nim/README.md b/crates/games/src/nim/README.md new file mode 100644 index 0000000..d69b7d6 --- /dev/null +++ b/crates/games/src/nim/README.md @@ -0,0 +1,6 @@ +Nim is the heart of impartial combinatorial game theory. +Its a game about removing objects from heaps. +Despite its ability to be rigidly analyzed, +it still makes a great example as an implementation of the `Game` trait. + +Learn more about Nim here: diff --git a/crates/games/src/nim/cli.rs b/crates/games/src/nim/cli.rs index a8f1a9b..d986ab9 100644 --- a/crates/games/src/nim/cli.rs +++ b/crates/games/src/nim/cli.rs @@ -17,6 +17,9 @@ impl Display for Nim { } } +/// Analyzes Nim. +/// +#[doc = include_str!("./README.md")] #[derive(Args)] pub struct NimArgs { /// The configuration of the game. For example, 3,5,7 diff --git a/crates/games/src/nim/mod.rs b/crates/games/src/nim/mod.rs index c5748b8..5dff526 100644 --- a/crates/games/src/nim/mod.rs +++ b/crates/games/src/nim/mod.rs @@ -1,9 +1,4 @@ -//! Nim is the heart of impartial combinatorial game theory. -//! Its a game about removing objects from heaps. -//! Despite its ability to be rigidly analyzed, -//! it still makes a great example as an implementation of the `Game` trait. -//! -//! Learn more about Nim here: +#[doc = include_str!("./README.md")] pub mod cli; diff --git a/crates/games/src/order_and_chaos/README.md b/crates/games/src/order_and_chaos/README.md new file mode 100644 index 0000000..5baf29d --- /dev/null +++ b/crates/games/src/order_and_chaos/README.md @@ -0,0 +1,7 @@ +Order and Chaos is a Tic Tac Toe variant that plays on a 6x6 square board. + +The game is played by two players, order and chaos. Order plays first, and places Xs and Os on the board. Chaos also plays Xs and Os, but Chaos's goal is to make Order tie the game. + +5 in a row wins the game for Order - otherwise, Chaos wins. This serves as an exemplary example for the simplicity in implementation, showing how trivial it is to implement a new game. + +Learn more: diff --git a/crates/games/src/order_and_chaos/cli.rs b/crates/games/src/order_and_chaos/cli.rs index 830b8cc..0e88763 100644 --- a/crates/games/src/order_and_chaos/cli.rs +++ b/crates/games/src/order_and_chaos/cli.rs @@ -3,6 +3,9 @@ use game_solver::{game::Game, par_move_scores}; use crate::order_and_chaos::{CellType, OrderAndChaos}; +/// Analyzes Order and Chaos. +/// +#[doc = include_str!("./README.md")] #[derive(Args)] pub struct OrderAndChaosArgs { moves: Vec, diff --git a/crates/games/src/order_and_chaos/mod.rs b/crates/games/src/order_and_chaos/mod.rs index f325ef1..bf43b61 100644 --- a/crates/games/src/order_and_chaos/mod.rs +++ b/crates/games/src/order_and_chaos/mod.rs @@ -1,17 +1,4 @@ -//! Order and chaos is a tic tac toe variant -//! that plays on a 6x6 square board. -//! -//! The game is played by two players, order and chaos. -//! Order plays first, and places Xs and Os on the board. -//! Chaos also plays Xs and Os, but Chaos's goal is to -//! make Order tie the game. -//! -//! 5 in a row wins the game for Order - otherwise, Chaos wins. -//! This serves as an exemplary example -//! for the simplicity in implementation, -//! showing how trivial it is to implement a new game. -//! -//! Learn more: +#[doc = include_str!("./README.md")] pub mod cli; diff --git a/crates/games/src/reversi/README.md b/crates/games/src/reversi/README.md new file mode 100644 index 0000000..2eadee7 --- /dev/null +++ b/crates/games/src/reversi/README.md @@ -0,0 +1,5 @@ +Reversi is a two-player game played on a rectangular grid of squares. + +The grid is usually 8x8, but any size can be used. + +More information: diff --git a/crates/games/src/reversi/cli.rs b/crates/games/src/reversi/cli.rs index 85217b5..8bbd58d 100644 --- a/crates/games/src/reversi/cli.rs +++ b/crates/games/src/reversi/cli.rs @@ -12,6 +12,9 @@ use game_solver::{ use super::{HEIGHT, WIDTH}; +/// Analyzes Reversi. +/// +#[doc = include_str!("./README.md")] #[derive(Args)] pub struct ReversiArgs { /// Reversi moves, ordered as x1-y1 x2-y2 ... diff --git a/crates/games/src/reversi/mod.rs b/crates/games/src/reversi/mod.rs index 5df39cd..3f6a0ab 100644 --- a/crates/games/src/reversi/mod.rs +++ b/crates/games/src/reversi/mod.rs @@ -1,7 +1,4 @@ -//! Reversi is a two-player game played on a rectangular grid of squares. -//! The grid is usually 8x8, but any size can be used. -//! -//! More information: +#[doc = include_str!("./README.md")] pub mod cli; diff --git a/crates/games/src/tic_tac_toe/README.md b/crates/games/src/tic_tac_toe/README.md new file mode 100644 index 0000000..29cb3d0 --- /dev/null +++ b/crates/games/src/tic_tac_toe/README.md @@ -0,0 +1,5 @@ +Tic Tac Toe is a traditional two-player game played on a 3x3 grid. +For the sake of complexity, this allows simulating any n-dimensional 3-in-a-row game +with the same bounds as the traditional game. + +This is a variant of the . diff --git a/crates/games/src/tic_tac_toe/cli.rs b/crates/games/src/tic_tac_toe/cli.rs index 17422d1..b59071e 100644 --- a/crates/games/src/tic_tac_toe/cli.rs +++ b/crates/games/src/tic_tac_toe/cli.rs @@ -4,6 +4,9 @@ use ndarray::IntoDimension; use crate::tic_tac_toe::{format_dim, TicTacToe}; +/// Analyzes Tic Tac Toe. +/// +#[doc = include_str!("./README.md")] #[derive(Args)] pub struct TicTacToeArgs { /// The amount of dimensions in the game. diff --git a/crates/games/src/tic_tac_toe/mod.rs b/crates/games/src/tic_tac_toe/mod.rs index ebb9ebc..133e900 100644 --- a/crates/games/src/tic_tac_toe/mod.rs +++ b/crates/games/src/tic_tac_toe/mod.rs @@ -1,6 +1,4 @@ -//! Tic Tac Toe is a traditional two-player game played on a 3x3 grid. -//! For the sake of complexity, this allows simulating any n-dimensional 3-in-a-row game -//! with the same bounds as the traditional game. +#[doc = include_str!("./README.md")] pub mod cli;