dndice 2.8.1

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.