backgammon 0.18.0

/*
 * BSD 2-Clause License
 *
 * Copyright (c) 2020-2026, Carlo Strub <cs@carlostrub.ch>
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice, this
 *    list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

//! [![status-badge](https://ci.codeberg.org/api/badges/15563/status.svg)](https://ci.codeberg.org/repos/15563)
//!
//! # Backgammon: The Oldest Board Game in the World
//! This crate provides a pure, canonical implementation of the game
//! [*Backgammon.*](https://en.wikipedia.org/wiki/Backgammon)
//!
//! <img src="https://upload.wikimedia.org/wikipedia/commons/3/30/Backgammon_lg.png" height="100">
//!
//! ## Supported Doubling Cube Rules
//! The following doubling cube [`rules`](`crate::rules::Rules`) are supported:
//!
//! * Murphy
//! * Jacobi
//! * Crawford
//! * Holland
//!
//! ## Recommended Use for AI Agents
//! For a correct and tournament-legal implementation, AI agents should interact with the `Match`
//! struct rather than the `Game` struct directly.
//! use backgammon::prelude::*;
//!
//! AI Agent Setup: Always define the match context first
//! ```
//! use backgammon::prelude::*;
//!
//! fn setup_agent_environment() -> Match {
//! let mut m = Match::new();
//! m.set_points(13).unwrap();
//! m.set_crawford(true).unwrap();
//! m
//! }
//! ```
//!
//! - **Why `Match`?**: It manages the Doubling Cube, Match Points, and rules like Jacoby or
//!   Crawford which are essential for calculating "Match Equity" (the probability of winning the
//!   whole match).
//! - **Statelessness**: This crate is stateless. Agents must persist the `Match` object between
//!   turns.
//!
//! ### Difference between Game and Match Structs
//! | Feature | Game Struct | Match Struct |
//! |---------|-------------|--------------|
//! | Checker Movement | Yes | Yes (via current game) |
//! | Dice Rolling | Yes | Yes |
//! | Doubling Cube | No | Yes |
//! | Match Score | No | Yes |
//! | Tournament Rules | No | Yes (Crawford, etc.) |
//!
//! ## Examples
//! ### Creating a Match
//! To create a new backgammon match, load the prelude module and define a mutable match:
//! ```
//! use backgammon::prelude::*;
//!
//! let mut m = Match::new();
//!
//! ```
//! Depending on the style of tournament, it is possible to set any number of
//! [`rules`](`crate::rules::Rules`):
//! ```
//! use backgammon::prelude::*;
//!
//! fn play_match() -> Result<(), Error> {
//!
//! let mut m = Match::new();
//! m.set_points(13)?;
//! m.set_jacobi(true)?;
//!
//! Ok(())
//! }
//! ```
//! ### The first roll
//! In a physical game, both players roll with one die. Then, the higher roll defines the first
//! player.
//! ```
//! use backgammon::prelude::*;
//!
//! fn play_match() -> Result<(), Error> {
//!
//! let mut m = Match::new();
//! m.roll(Player::Nobody)?;
//!
//! Ok(())
//! }
//! ```
//!
//! ### Playing an Example Backgammon Match
//! To see this library in action, run the included example:
//! ```console
//! cargo run --example backgammon_tui
//! ```
//! For more examples, have a look at the [examples](https://codeberg.org/Backgammon/backgammon/src/branch/main/examples)
//! directory.
//!
//! ## Design Philosophy
//! This library is designed to provide stateless Backgammon gameplay functionality. Because it does
//! not track or store game states itself, you can easily implement wrappers that use this library
//! along with an external database to manage and persist game states.
//!
//! ## Discussions and Support
//! Remember that the APIs are not stable yet. Any support is very welcome. Please open an
//! [Issue](https://codeberg.org/Backgammon/backgammon/issues) to discuss features or ask for help.

#![warn(future_incompatible)]
#![deny(
    rustdoc::broken_intra_doc_links,
    rustdoc::invalid_codeblock_attributes,
    rustdoc::invalid_html_tags,
    rustdoc::missing_crate_level_docs,
    missing_debug_implementations,
    missing_docs,
    rustdoc::private_intra_doc_links,
    single_use_lifetimes,
    trivial_casts,
    trivial_numeric_casts,
    unreachable_pub,
    unsafe_code,
    unused_extern_crates,
    unused_import_braces,
    unused_qualifications,
    unused_results,
    unused_variables,
    variant_size_differences
)] // be tough on code quality

pub use error::Error;
pub use game::Game;
pub use r#match::{Match, MatchState};

/// Implements all possible Backgammon errors.
pub mod error;
/// Implements a Backgammon game.
pub mod game;
/// Implements a Backgammon match.
pub mod r#match;
/// Implements the board, the dice, the cube, and all other Backgammon rules.
///
/// _Caveat:_ Unless you know what you are doing, you should not use this module directly. Only
/// use the [Match struct](./struct.Match.html) in your implementation.
pub mod rules;
/// Implements statistics.
pub mod stats;

/// Implements the AI Agent API. Useful for training neural networks.
pub mod ai;

/// Implements the FIBS rating algorithm.
pub mod rating;

/// Provides commonly used types and structures for ease of use in external modules. It is
/// recommended to always use the prelude module for convenience.
pub mod prelude {
    pub use crate::game::GameOutcome;
    pub use crate::game::GameState;
    pub use crate::rules::prelude::*;
    pub use crate::stats::Stats;
    pub use crate::{Error, Game, Match, MatchState};
}