# backgammon
[](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:
* Beaver
* Raccoon
* 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
```rust
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
| 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:
```rust
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`):
```rust
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.
```rust
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.
License: BSD-2-Clause