Skip to main content

A library for evaluating tabletop dice roll expressions

Project description

PyHedrals Build Status

A library for evaluating tabletop dice roll expressions.

Used in the Mastodon bot DiceCat, and the IRC bot DesertBot

Usage Overview

Sample usage: 5d6!>4 + (5d(2d10)dl - d10) * (d20 / 2) # for an unnecessarily complicated roll

Sample output: 84 for an unnecessarily complicated roll

There is also a verbose mode that outputs every individual die roll, that output looks like this: [2d10: 2,5 (7) | 5d7: -1-,6,2,4,5 (17) | 1d10: 3 (3) | 1d20: 9 (9) | 5d6: 2,2,3,*5*,*5*,2,*5*,4 (28)] 84 for an unnecessarily complicated roll

Supported Operators

  • Arithmetic: + - * / % ^ () (addition, subtraction, multiplication, division, modulus, exponent, parentheses)
  • Dice: #d# (eg, 3d6, d20)
    • Rolls the left number of dice with the right number of sides. 3d6 rolls 3 six-sided dice
    • The first number is optional and defaults to 1 if omitted
  • Dice modifiers:
    • Keep/Drop Highest/Lowest: kh# kl# dh# dl#
      • Keeps/Drops only the # highest/lowest dice rolls. Any that are either not kept or dropped are removed from the total
      • The number is optional and defaults to 1 if omitted
    • Exploding: ! !# !># !>=# !<# !<=#
      • Each die that rolls maximum (!), or a specific number (!#), or over/under a threshold (!># !>=# !<# !<=#), adds an additional die to the pool
        • This repeats for each die added to the pool
    • Reroll: r r# r># r>=# r<# r<=#
      • Drops and rerolls each die that rolls minimum (r), or a specific number (r#), or over/under a threshold (r># r>=# r<# r<=#)
        • This repeats for each die rerolled. You can make it only reroll each die once with ro instead of r
    • Count: c c# c># c>=# c<# c<=#
      • Counts the number of dice that roll maximum (c), or a specific number (c#), or over/under a threshold (c># c>=# c<# c<=#)
    • Sorting: s sa sd
      • Sorts the dice rolls in ascending (s sa) or descending (sd) order
      • This still applies in non-verbose mode but you won't see any visible effect
  • Comments: # your comment here
    • Adds a comment to the end of the output, so you can describe what the roll is for. eg: d20+5 # for initiative
    • The # is a literal hash, not a number this time :)

If you have more ideas for operators, suggestions and pull requests are welcome!

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pyhedrals, version 0.2.0
Filename, size File type Python version Upload date Hashes
Filename, size pyhedrals-0.2.0-py3-none-any.whl (7.4 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size pyhedrals-0.2.0.tar.gz (6.3 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page