An engine to parse and evaluate D&D-inspired roll expressions

DnDice

This package deals with roll expressions, which are inspired by the syntax D&D uses. At the most basic, there are expressions like 1d20 which means "roll one 20-sided die". D&D stops around when modifiers are added, like 1d6+2. This package runs with it and introduces these dice expressions to an entire arithmetic framework. You can add, subtract, multiply, even exponentiate rolls together, not to mention all of the roll-specific operations like taking the highest or lowest rolls or rerolling given a condition. As these are mathematical expressions just like normal ones, note that they can get arbitrarily complicated. The only limit is how much resources Python can bring to bear calculating your (9^9^9^9^9)d10000 or similar ridiculous expression.

The full specification of what operators are supported and what they do is below.

Operator Format Meaning
! x! Calculate the factorial of x.
d xdy Take a y-sided die and roll x of them. y can be an integer, and works just as you would expect. It can also be a list of arbitrary numbers (delineated by [] and separated with commas), in which case it works as a die with one side labeled with each number in the list.
da xday Take a y-sided die and return the average as if x of them had been rolled. This returns an unrounded number.
dc xdcy Roll a critical hit, where the number of dice rolled is doubled.
dm xdmy Roll the maximum on every die rolled.
h ROLLhn After making a roll, discard all but the highest n of the rolls. Hint: 2d20h1 is advantage.
l ROLLln After making a roll, discard all but the lowest n of the rolls. Hint: 2d20l1 is disadvantage.
f ROLLfn After making a roll, treat any value that is less than n as n.
c ROLLcn After making a roll, treat any value that is greater than n as n.
r or ro ROLLron After making a roll, look at all of them and reroll any that are equal to n, reroll those, and take the result.
R or Ro ROLLRon After making a roll, look at all of them and reroll any that are equal to n and reroll those. If that number comes up again, continue rerolling until you get something different.
r> or rh ROLLrhn After making a roll, look at all of them and reroll any that are strictly greater than n, reroll those, and take the result.
R> or Rh ROLLRhn After making a roll, look at all of them and reroll any that are greater than n and reroll those. If a number greater than n comes up again, continue rerolling until you get something different.
r< or rl ROLLrln After making a roll, look at all of them and reroll any that are strictly less than n, reroll those, and take the result.
R< or Rl ROLLRln After making a roll, look at all of them and reroll any that are less than n and reroll those. If a number less than n comes up again, continue rerolling until you get something different.
t ROLLtn After making the roll, count the number of rolls that were at least n.
T ROLLTn After making the roll, count the number of rolls that were at most n.
^ x^y Raise x to the y power. This operation is right-associative, meaning that the right side of the expression is evaluated before the left. This really only comes up when chained, for example in 2^3^2. This would not be (2^3)^2=8^2=64, but rather 2^(3^2)=2^9=512.
* x*y x times y.
/ x/y x divided by y. This returns an unrounded number.
% x%y x modulo y. That is, the remainder after x is divided by y.
+ x+y x plus y.
- x-y x minus y.
> or gt x>y Check if x is greater than y. Returns a 1 for yes and 0 for no.
>= or ge x>=y Check if x is greater than or equal to y. Returns a 1 for yes and 0 for no.
< or lt x<y Check if x is less than y. Returns a 1 for yes and 0 for no.
<= or le x<=y Check if x is less than or equal to y. Returns a 1 for yes and 0 for no.
= x=y Check if x is equal to y. Returns a 1 for yes and 0 for no.
& x&y Check if x and y are both nonzero.
| x|y Check if at least one of x or y is nonzero.

Using this package

As a user or player

Installing this package from PyPI will also install the script roll to your path. This is a simple command-line script that allows you to exercise all the powers of this package. For a GUI that does the same, check out my repository DnD which is a larger project focused around D&D 5e, allowing you to track your characters and monsters.

As a developer

If you just want to use this in an application, install it through PyPI and import it as dndice. The main function you want is basic, which will simply evaluate an expression and return the final number. verbose is useful for giving a more detailed look at what was actually rolled, targeted at direct display to a user. compile can be used to precompile expressions for quick evaluation of the same expression many times. For a complete view, see the docs.

To modify this package, first install poetry for dependency management. There are no runtime dependencies, and the only development dependencies are sphinx for documentation and nose2 for testing. You probably also want GNU make because I have a number of tasks scripted in the Makefile at the project root.

Project details

Uploaded source
Uploaded py3