trinistr/dicey

Purpose and Delivery

Dicey is a Ruby gem for modeling dice, rolling them, and calculating complete outcome weight/probability distributions. It is primarily a library with command-line delivery; the referenced online UI is external to this repository.

Gem/library root: lib/dicey.rb; package metadata: dicey.gemspec. CLI executables: exe/dicey and exe/dicey-to-gnuplot.

Entry Points and CLI Orchestration

Dicey::CLI is the command boundary: it parses arguments/options, builds dice, selects calculation or roll mode, and directs output formatting. Dicey::CLI::CalculatorRunner and Dicey::CLI::Roller separate distribution calculation from random-roll execution. The GNUplot executable supports a pipeline from Dicey’s graph-oriented output to a PNG-producing external tool.

Paths: lib/dicey/cli.rb, lib/dicey/cli/options.rb, lib/dicey/cli/calculator_runner.rb, lib/dicey/cli/roller.rb, lib/dicey/cli/blender.rb.

Dice Domain Model

AbstractDie is the permissive core representation: a sequence of sides plus mutable current-roll state and shared randomness. NumericDie constrains sides to numeric values; RegularDie expands a side count into the standard 1..N range. This hierarchy is the boundary between input construction and both rolling/calculation algorithms.

Paths: lib/dicey/abstract_die.rb, lib/dicey/numeric_die.rb, lib/dicey/regular_die.rb.

Input Compilation: DieFoundry

DieFoundry parses CLI-style string definitions—counts, ranges, numeric lists, arbitrary/symbolic lists—and produces one die or repeated dice. CLI input is therefore normalized to arrays of domain die objects before operation dispatch. It also enables the same compact notation through the Ruby API.

Path: lib/dicey/die_foundry.rb.

Distribution Calculation Pipeline

Calculators implement a common contract through BaseCalculator: validate dice, estimate complexity, then return an outcome-to-weight or probability hash. AutoSelector chooses a usable algorithm according to die type and expected cost. Algorithm boundaries are important: polynomial convolution accepts integer dice; multinomial targets repeated arithmetic dice; binomial targets equal two-sided dice; iterative and empirical cover generic/abstract cases; trivial shortcuts simple inputs.

Paths: lib/dicey/distribution_calculators/base_calculator.rb, lib/dicey/distribution_calculators/auto_selector.rb, lib/dicey/distribution_calculators/polynomial_convolution.rb, lib/dicey/distribution_calculators/multinomial_coefficients.rb, lib/dicey/distribution_calculators/iterative.rb, lib/dicey/distribution_calculators/binomial.rb, lib/dicey/distribution_calculators/empirical.rb.

Result Interpretation and Presentation

Distribution hashes can feed DistributionPropertiesCalculator for descriptive statistics such as modes, moments, and spread. CLI formatters serialize the calculation/roll result into lists, JSON, YAML, null output, or GNUplot-compatible data. Formatting is deliberately downstream of calculation, preserving a library-friendly Hash result.

Paths: lib/dicey/distribution_properties_calculator.rb, lib/dicey/cli/formatters/json_formatter.rb, lib/dicey/cli/formatters/yaml_formatter.rb, lib/dicey/cli/formatters/gnuplot_formatter.rb.

Runtime, Dependencies, and Operations

The runtime is Ruby, tested across CRuby 3.0+, JRuby, and TruffleRuby, with CI workflows per implementation. vector_number supports summable symbolic outcomes; JSON/YAML output depends on their Ruby libraries. GNUplot is an optional external executable used only by the graph pipeline. API signatures are maintained in sig/dicey.rbs; documentation deployment is handled by GitHub Actions.

Paths: .github/workflows/CI.yaml, .github/workflows/jruby.yaml, .github/workflows/truffle_ruby.yaml, sig/dicey.rbs.