ndice
A dice rolling library for games.
ndice is a package for rolling dice expressions like d6+2 or 3d6-3x10
with a compact API.
>>> from ndice import d6, d8, d20, d100, plus, minus, times, rng, roll
>>> if roll(rng, d100) <= 25:
... copper = roll(rng, d6, times(1000))
>>> str_mod = minus(1)
>>> magic_sword_mod = plus(2)
>>> ac = 13
>>> if roll(rng, d20, str_mod, magic_sword_mod) >= ac:
... damage = roll(rng, d8)
Operations (Op)
The Op enum defines the three operations used in dice expressions: Op.PLUS
(+), Op.MINUS (-) and Op.TIMES (x).
Dice
A Dice object represents a single term in a dice expression like 2d6 or
-2. The Dice object contains three attributes: number, sides and op.
The values for number and sides must be zero or greater. If not specified,
op defaults to Op.PLUS.
Rolling zero dice with any number of sides always returns 0. Rolling any number of zero-sided dice also always returns 0.
Constant modifiers ("mods") like -2 or x10 are defined as Dice
instances where number is the mod value and sides is 1.
ndice contains predefined common dice like d6, d20 and three_d6. A single
die type can be defined with the d() function, an alias for Dice.die().
>>> from ndice import d
>>> d5 = d(5)
A number of dice can be defined with the nd() function, an alias for
Dice.n_dice().
>>> from ndice import nd
>>> three_d8 = nd(3, 8)
Instances of Dice are immutable and cached, so d(6) will return the same Dice
instance that d6 refers to.
>>> from ndice import d, d6
>>> d(6) is d6 # always true
True
Individual Dice instances are ordered according to (number, sides, op),
where Op.PLUS comes first and Op.TIMES last.
>>> from ndice import d6, two_d6, three_d6, minus, times
>>> assert d6 < minus(d6) < times(d6) < two_d6 < three_d6
A Dice object is hashable and can be used in sets or as keys in dicts.
Random Number Generators (RNG)
Rolling dice requires a "random" number generator. A number generator is a
function or callable object that takes an int with the max die roll (i.e. the
number of sides) and returns an int value in the range [1, sides]. The type
alias RNG can be used to annotate number generator variables.
The rng generator produces actual random numbers. The PRNG() constructor
function creates random number generator functions that return deterministic
pseudo-random number sequences based on a given seed value.
>>> from ndice import PRNG, roll, three_d6
>>> prng1 = PRNG(1122334455)
>>> roll(prng1, three_d6)
10
# restart the same pseudo-random sequence
>>> prng2 = PRNG(1122334455)
>>> roll(prng2, three_d6)
10
Fake generators high and low always roll the highest or lowest values
respectively. The mid generator always rolls the middle value or lower of the
two middle values: when rolling a three-sided die, mid returns 2; when rolling
a six-sided die with middle values of 3 and 4, mid returns 3.
AscendingRNG(), FixedRNG() and SequenceRNG create other fake generators.
Creating a custom fake generator can be as simple as creating a function or
lambda.
>>> from ndice import d100, RNG
>>> always_2: RNG = lambda sides: 2
>>> roll(always_2, d100)
2
Rolls
The roll() function takes a number generator and zero or more Dice instances
making up a dice expression. It returns the total of the dice expression.
>>> from ndice import minus, PRNG, roll, two_d6
>>> prng = PRNG(1122334455)
>>> roll(prng, two_d6, minus(2))
6
If no dice are given, roll() returns zero.
>>> from ndice import roll, d6, minus, times, rng, high
>>> roll(rng)
0
>>> dice_expression = []
>>> # oops, forgot to add terms to the dice expression ...
>>> roll(rng, *dice_expression)
0
Note that dice expressions are always evaluated from left to right; times() or
Op.TIMES does not have higher precedence than plus or minus. This is
different than the equivalent Python numeric expression, where * and / are
evaluated before + and -.
>>> total = roll(high, d6, minus(1), times(10))
>>> total
50
>>> assert 6 - 1 * 10 != total
>>> assert (6 - 1) * 10 == total
The min_roll() and max_roll() functions are equivalent to roll(low, ...)
and roll(high, ...) respectively.
Individual Die Rolls
Sometimes you need the individual die rolls rather than the total. The
roll_each_die() function returns the individual die rolls of a Dice object
as a list.
>>> from ndice import four_d6, PRNG, roll_each_die
>>> prng = PRNG(1122334455)
>>> roll_each_die(prng, four_d6)
[4, 4, 2, 6]
Metadata
Release files for ndice 0.1.11
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ndice-0.1.11.tar.gz | 9.3 kB | Without provenance | Details for ndice-0.1.11.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ndice-0.1.11-py3-none-any.whl | Python 3 | none | any | Details for ndice-0.1.11-py3-none-any.whl |
Total release size: 21.3 kB
Release files / ndice-0.1.11.tar.gz
| Download URL | ndice-0.1.11.tar.gz |
|---|---|
| Size | 9.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d841136bf34278545d01e57414ccdc49add3ebf2a79663f9205be82ebc5abbba
|
|
BLAKE2b-256 checksum How to use checksums |
daf47b9d971b5bc14f6cc70c6bdfb4d2beef1e7b6acc823d4b329b579ceeafef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.11 {"installer":{"name":"uv","version":"0.9.11"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / ndice-0.1.11-py3-none-any.whl
| Download URL | ndice-0.1.11-py3-none-any.whl |
|---|---|
| Size | 12.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
38cc512c46e14a88b78af43ae8cc6f46ec8055d853644881a29d11e7b4aebe75
|
|
BLAKE2b-256 checksum How to use checksums |
b34041578c270aafa52c3429981f05010ce1ce4525f39d7336aa9ed912a5cf24
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.11 {"installer":{"name":"uv","version":"0.9.11"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for ndice 0.1.11
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.