Struct Solver 

pub struct Solver { /* private fields */ }

An exact expectimax solver over the full game.

The value table is keyed by State::index and filled by backward induction: a state’s expected further score is the mean over the turn’s roll/keep/roll/keep/roll/score lattice of the best reward plus the value of the resulting state. From the empty card this comes to an optimal solo expectation of 254.5877 points under the official forced-joker rules this crate implements. The widely cited 254.5896 (Verhoeff, 1999) uses a laxer convention — an extra Yahtzee may be scored in any open box, with joker values gated on the matching upper box being filled — which this engine reproduces exactly when the forcing in State::legal_categories is lifted.

Construction is cheap; values are computed on demand. Querying a mid-game state solves only the states reachable from it, so “what is best here” costs a fraction of a full solve. All queries break ties deterministically (first category in card order, then first keep in canonical order), so replays are stable.

Implementations

impl Solver

pub fn new() -> Self

Builds the dice tables; no states are solved yet.

pub fn is_solved(&self, state: State) -> bool

Whether value for this state is already computed.

pub fn solve_tier(&mut self, filled: u32)

Solves every state with exactly filled categories scored.

Tiers must be solved from 13 down to 0; solve does exactly that. Exposed so incremental front ends can report progress between tiers. With the parallel feature the tier is solved across threads, bit-identical to the serial build.

Panics

Panics if filled > 13, or if the tiers above filled have not been solved yet — solving out of order would silently poison the table otherwise.

pub fn solve(&mut self)

Solves the whole game, all reachable states, bottom-up.

Takes seconds in a release build (use the parallel feature to spread it across cores); afterwards every query is a table lookup plus one turn evaluation.

pub fn value(&mut self, state: State) -> f64

The expected further score from the start of a turn in state, under optimal play.

Solves lazily: only states reachable from state are computed, so early queries from a part-filled card are much cheaper than a full solve.

pub fn category_ev( &mut self, state: State, dice: Dice, category: Category, ) -> Option<f64>

The expected further score of scoring dice in category now and playing on optimally: the write, its bonuses, and everything after — points already on the card are not included.

Returns None if the category is illegal here; see State::legal_categories.

pub fn keep_ev( &mut self, state: State, dice: Dice, keep: Keep, rolls_left: u8, ) -> Option<f64>

The expected further score of holding keep and rerolling the rest, with rolls_left rolls remaining (clamped to the turn’s two rerolls).

Returns None if the card is full, no rolls remain, or keep is not part of dice.

pub fn best_category(&mut self, state: State, dice: Dice) -> Category

The best category for dice when the turn must end now.

Panics

Panics if the card is already full.

pub fn best_action( &mut self, state: State, dice: Dice, rolls_left: u8, ) -> TurnAction

The optimal action for dice with rolls_left rolls remaining (clamped to the turn’s two rerolls). Scoring wins ties against rerolling.

Panics

Panics if the card is already full.

Trait Implementations

impl Clone for Solver

fn clone(&self) -> Solver

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Solver

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Solver

fn default() -> Self

Returns the “default value” for a type.