brianbruggeman / dice

A DSL for rolling dice build in python

dice

A DSL for dice notation built in python using Lark.

Motivation

I wanted a chance to build a meaningful DSL using a library (Lark) that I haven't tried previously.

Usage

CLI

The following represents how to run the parser from the command-line interface:

$ roll 6x4d6M3
--------------------------------------------------
 Formula: 6x4d6M3
--------------------------------------------------
 10
 10
 12
 8
 10
 11
--------------------------------------------------
 Sum: 61
 Ave: 10
--------------------------------------------------

API

The following represents an example usage of using this package's programmatic API:

#!/usr/bin/env python3
from dice import parse


def roll(formula, seed=10):
    """Rolls dice based on formula

    Args:
        formula (str): formula to roll [e.g. 3d6]
        seed (int): random number generator seed

    Returns:
        List[int]: values rolled

    """
    values = [value for value in parse(formula=formula, seed=seed)]
    return values

Installation

This can be installed directly into a virtual environment using pip:

pip install -e git://github.com/brianbruggeman/dice.git@main#egg=dice

Dice Notation Rules

There's a nice wiki page on dice notation.

The current grammar (in case this document doesn't get updated well) can be found under dice/dice.lark.

Math

Basic math operations are as follows

Rule	Notation	Example	Description
dice	d	3d6	Rolls a dice (e.g. 6) a specific number of times (e.g. 3)
percent	d%	d%	Rolls a 100-sided die
plus	+	1 + 2	Simple add
minus	-	1 - 2	Simple subtraction
multiply	*	1 * 2	Simple multiplication
division	/	2 / 2	Simple division

Filtering

Additionally, the following provides a mechanism for filtering data

Rule	Notation	Example	Description
maximum	M	4d6M3	Pick the highest rolls from formula (e.g. best 3 rolls out of 4)
minimum	m	4d6m3	Pick the lowest rolls from formula (e.g. worst 3 rolls out of 4)
over	>	4d6>3	Pick only the rolls over a threshold from formula
under	<	4d6<4	Pick only the rolls under a threshold from formula
equal	==	4d6==5	Pick only the rolls that equal a value from formula
notequal	!=	4d6!=5	Pick only the rolls that don't equal a value from formula
overequal	>	4d6>=3	Pick only the rolls over or equal to a threshold from formula
underequal	<=	4d6<=3	Pick only the rolls under or equal to a threshold from formula

Control

Finally, there are ways of controlling output

Rule	Notation	Example	Description
iteration	x	6x4d6M3	Repeat the formula multiple times (e.g. create 6 values using 4d6M3 )

Testing

This package uses pytest.

Testing Setup

To setup, simply clone the repo and run:

pip install -e .[all]

Running tests

To run the tests, at the top of the repo run:

pytest