Struct DiceEngine 

pub struct DiceEngine { /* private fields */ }

In-memory dice and tray engine.

A new engine starts with the built-in dice and no trays. Custom dice and trays are held in memory; callers that need persistence should serialize the data structures exposed by this crate.

Implementations

impl DiceEngine

pub fn new() -> Self

Creates a new engine with the built-in dice loaded.

pub fn set_custom_dice(&mut self, custom: Vec<Die>)

Replaces all custom dice while preserving the built-in dice.

Each supplied die is normalized to DieKind::Custom and receives CUSTOM_PREFIX if it does not already have it.

pub fn set_trays(&mut self, trays: Vec<Tray>)

Replaces the engine’s trays.

pub fn custom_dice(&self) -> Vec<&Die>

Returns all custom dice.

pub fn trays(&self) -> &[Tray]

Returns all trays.

pub fn list_dice(&self) -> &[Die]

Returns all dice known to the engine.

Built-in dice are listed before custom dice.

pub fn list_trays(&self) -> &[Tray]

Returns all trays known to the engine.

pub fn get_tray(&self, name: &str) -> Option<&Tray>

Returns a tray by exact name.

pub fn resolve_die_name(&self, name: &str) -> Option<String>

Resolves a user-provided die name to its canonical engine name.

The lookup first tries an exact match, then a case-insensitive match, and finally the custom-die form with CUSTOM_PREFIX.

pub fn create_die(&mut self, name: &str, faces: Vec<FaceValue>) -> Result<&Die>

Creates a custom die and returns the stored die.

The supplied name must be non-empty and contain no whitespace. Names are normalized with CUSTOM_PREFIX.

Errors

Returns DiceError::InvalidName for invalid names, DiceError::InvalidFaceCount for empty faces, and DiceError::DieAlreadyExists when the normalized name is already in use.

pub fn modify_die(&mut self, name: &str, faces: Vec<FaceValue>) -> Result<&Die>

Replaces the faces of a custom die and returns the stored die.

Errors

Returns DiceError::InvalidFaceCount for empty faces, DiceError::CannotModifyBuiltin for built-in dice, DiceError::InvalidName for invalid custom names, and DiceError::DieNotFound when the die does not exist.

pub fn delete_die(&mut self, name: &str) -> Result<()>

Deletes a custom die.

Errors

Returns DiceError::CannotModifyBuiltin for built-in dice, DiceError::InvalidName for invalid custom names, DiceError::DieNotFound when the die does not exist, and DiceError::CannotDeleteInUse when any tray still references the die.

pub fn create_tray(&mut self, name: &str) -> Result<&Tray>

Creates an empty tray and returns it.

Errors

Returns DiceError::InvalidName for empty names or names containing whitespace, and DiceError::TrayAlreadyExists when the name is already in use.

pub fn delete_tray(&mut self, name: &str) -> Result<()>

Deletes a tray by exact name.

Errors

Returns DiceError::TrayNotFound when the tray does not exist.

pub fn rename_tray(&mut self, old_name: &str, new_name: &str) -> Result<&Tray>

Renames a tray and returns it.

Errors

Returns DiceError::TrayNotFound when old_name does not exist, DiceError::InvalidName when new_name is invalid, and DiceError::TrayAlreadyExists when new_name belongs to another tray.

pub fn add_die_to_tray( &mut self, die_name: &str, tray_name: &str, ) -> Result<u32>

Adds a die to a tray and returns the assigned slot identifier.

The die name is resolved through Self::resolve_die_name. Slot identifiers are assigned by the tray and are not reused after removal.

Errors

Returns DiceError::DieNotFound when the die cannot be resolved and DiceError::TrayNotFound when the tray does not exist.

pub fn remove_slot(&mut self, tray_name: &str, slot_id: u32) -> Result<()>

Removes a slot from a tray.

Errors

Returns DiceError::TrayNotFound when the tray does not exist and DiceError::SlotNotFound when the slot does not exist in that tray.

pub fn lock_slot(&mut self, tray_name: &str, slot_id: u32) -> Result<()>

Locks a tray slot so future tray rolls preserve its current value.

Errors

Returns DiceError::TrayNotFound when the tray does not exist and DiceError::SlotNotFound when the slot does not exist in that tray.

pub fn unlock_slot(&mut self, tray_name: &str, slot_id: u32) -> Result<()>

Unlocks a tray slot so future tray rolls can update its current value.

Errors

Returns DiceError::TrayNotFound when the tray does not exist and DiceError::SlotNotFound when the slot does not exist in that tray.

pub fn roll_die(&self, die_name: &str) -> Result<DieRoll>

Rolls one die.

Numeric names such as d13 are supported even when the die is not stored in the engine.

Errors

Returns DiceError::InvalidNumericDie for numeric dice with fewer than two faces and DiceError::DieNotFound for unresolved named dice.

pub fn roll_dice(&self, die_names: &[String]) -> Result<RollBatchResult>

Rolls multiple dice in order.

The returned roll identifiers start at 1 and follow the input order.

Errors

Returns the first error encountered while resolving or rolling a die.

pub fn analyze_roll( &self, die_names: &[String], modifiers: &[i64], ) -> Result<RollAnalysis>

Computes expected value and inclusive point range without rolling.

Integer faces contribute their value. Text faces contribute zero points. Modifiers are added to both expected value and range.

Errors

Returns the first error encountered while resolving or analyzing a die.

pub fn roll_tray(&mut self, tray_name: &str) -> Result<&Tray>

Rolls every unlocked slot in a tray and returns the updated tray.

Locked slots keep their existing current_value.

Errors

Returns DiceError::TrayNotFound when the tray does not exist and DiceError::DieNotFound when a tray slot references a missing die.

pub fn show_tray(&self, tray_name: &str) -> Result<TrayResult>

Returns a snapshot of a tray and its current slot values.

Errors

Returns DiceError::TrayNotFound when the tray does not exist.

Trait Implementations

impl Clone for DiceEngine

fn clone(&self) -> DiceEngine

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for DiceEngine

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

Formats the value using the given formatter.

impl Default for DiceEngine

fn default() -> Self

Returns the “default value” for a type.