“Roll with confidence — from tabletop RPGs to stats simulations.”

DiceRoller

Overview

DiceRoller is a lightweight, test-driven library plus CLI for evaluating standard dice expressions such as 3d6+2. It targets tabletop gamers, game masters, and developers who need predictable dice simulations in scripts or services. The single engine validates expressions, rolls dice, and exposes details (rolls, modifier, total) through DiceRollerData.

The CLI mirrors the API, so you can invoke it on the command line or embed the core logic in your own Python code without duplicating grammar rules.

Installation

Download a release wheel from the GitHub Releases page and install it via pip install path/to/diceroller.whl. Alternatively, clone this repo and install in editable mode:

          $ git clone https://github.com/retromatey/diceroller.git
          $ cd diceroller
          $ pip install -e .
        

Editable installs are ideal when hacking on the CLI or trying new content without rebuilding the wheel for every change.

Quick Start Examples

CLI Example

Roll a typical D&D expression:

              $ diceroller --verbose 3d6+2
              12 ( 4 3 5 +2 )
            

The CLI supports --verbose and --json for rich output.

Python API

              from diceroller.core import DiceRoller, CustomRandom
              roller = DiceRoller(custom_rng=CustomRandom(seed=42))
              roller.validate("2d8-1")
              total = roller.roll("2d8-1")
              print(roller.data.rolls)
            

Inject CustomRandom for deterministic values in tests.

Features

Strict grammar for expressions like <count>d<sides>[±modifier].
Cross-platform CLI with verbose, JSON, and seeded output.
Simple, inspectable DiceRollerData model for rolls/modifiers.
Extensible random source via CustomRandom so tests stay deterministic.
Validates input before rolling to catch malformed expressions early.

Detailed Usage

Expressions must consist of a positive number of dice and sides; use modifiers to adjust totals. Examples include 01d06, 4D10+3, and 2d20-5. Avoid internal whitespace — the CLI trims only leading/trailing spaces.

To integrate DiceRoller into another project, import the core module and rely on the public methods: validate() returns the parsed components, roll() executes the dice, and data exposes the breakdown.

When deterministic sequences are desired, call the CLI with --seed or instantiate CustomRandom(seed=<n>). Seeds allow reproducible gameplay or automated testing scenarios.

Testing & Coverage

Run pytest locally to ensure the validation helpers, modifiers, and multi-dice rolls behave as expected. The suite targets 100% coverage, giving you confidence before releasing a new version.

Changelog & Releases

Releases are tracked via Git tags on GitHub. Each release corresponds to an immutable package, so pin versions in your requirements.txt or GitHub Actions workflow. Visit the Releases page before migrating to a newer version to view the release notes.