xdice

xdice is a lightweight python library for managing dice, scores, and dice-notation patterns.

• Parse almost any Dice Notation pattern: '1d6+1', 'd20', '3d%', '1d20//2 - 2*(6d6+2)', 'max(1d4+1,1d6)', '3D6L2', 'R3(1d6+1)', '3dF'...etc.
• API help you to easily manipulate dices, patterns, and scores as objects
• A command line tool for convenience

Python Versions

xdice has been tested with python 3.9+

Documentation

For more, see the Documentation

Examples:

import dice

# Roll simple dices with rolldice()
# eg: 2d6

score = rolldice(6, amount=2)

# manipulates the score as an integer

print(score)
>> 11
print(score * 2)
>> 22
print(score == 11)
>> True

# Or iterates over the results

for result in score:
    print(result)
>> 5
>> 6

# Parse patterns with roll() and get a PatternScore object

ps = roll("2d6+18")

print(ps)
>> 28
print(ps.format())
>> '[5,6]+18'

# Use special notations, as selective dice
ps = roll("6D%L2")

print(ps)
>> 315
print(ps.format(verbose=True))
>> '6D%L2(scores:[80, 70, 76, 89], dropped:[2, 49])'

CLI

Run python roll.py [options] <expr>

usage: roll [-h] [-V] [-n] [-v] expression [expression ...]

Command Line Interface for the xdice library

positional arguments:
  expression      mathematical expression(s) containing dice <n>d<s> patterns

optional arguments:
  -h, --help      show this help message and exit
  -V, --version   print the xdice version string and exit
  -n, --num_only  print numeric result only
  -v, --verbose   print a verbose result

CONTRIBUTION

Any opinion / contribution is welcome, please contact us.

TO INSTALL

pip install xdice

License

xdice is under GNU License

Author

Olivier Massot, 2017-2026

Tags

dice roll d20 game random parser dices role board