Skip to main content

A comprehensive Python-based dice notation interpreter and roller

Project description

PyPI

d7

A comprehensive, simple-to-use, Python-based dice notation interpreter and roller.

Dice notation is a system used to represent different combinations of dice. It is often used in tabletop role-playing games (TTRPGs) where the number and size of the dice are represented in simple, math-like expressions.

For instance, the expression 1d6 means "roll one six-sided die" while 2d4+1 is "roll two four-sided dice and add one to the result".

d7 goes beyond the traditional, simple rolls and interprets more complex rolling expressions normally used in various TTRPGs.

Usage

Using d7 is very simple. Simply install the package:

pip install d7

Then import as usual, using the DiceExpression class from the dice_expression module:

>>> from d7 import dice_expression as d7
>>> expression = d7.DiceExpression("1d6+2")
>>> expression.roll()
5

Notation

Using the different notations below, on top of the traditional XdY, you can form both simple or complex dice-rolling expressions. For example:

  • 1d6+2 - roll one six-sided die, adding two to the result;
  • 2d4rr1+1 - roll two, four-sided dice, re-rolling the value one, adding one to the result;
  • 3d6ro<2kh2 - roll three, six-sided dice, re-rolling the value two at most once, keeping the highest two rolls;
  • 6d8rr1mi3kh3!+4 - roll six exploding, eight-sided dice, whose minimum value is three, re-rolling the value one, keeping the highest three, and adding four to the result.

There is a hierarchy between the different notations where the "least" changing ones are executed first. As such, d7 uses the following sequence when resolving dice expressions: roll -> rr|ro -> ! -> mi -> kh|hl -> +|-|*|/|/^

Modifiers

In addition to the + (e.g. 1d6+1) and - (e.g. 1d6-1) notation which adds or subtracts, respectively, a value from the total sum of the rolls, you can also use the * (e.g. 1d6*2), / (e.g. 2d6/2), and /^ (e.g. 3d8/^2) to multiply, divide (rounded down) or divide (rounded up), respectively.

The modifier is usually the last part of a dice expression.

Re-rolling

You can use the rr or ro notation to re-roll dice, depending on a specified condition. The rr notation translates to "re-roll" while the ro means "re-roll once".

For instance, the expression 1d6rr2 translates to "roll one six-sided die, re-rolling the value two" while 1d6ro2 is "roll one six-sided die, re-rolling the value two at most once".

Each of these two notations can be paired with the "<" or ">", thus indicating if it should re-roll on lower or higher values (e.g. 1d6rr<3).

Minimum

Through the use of the mi notation, you can establish a minimum value for the roll of each dice. As such, each die whose result is lower than the defined value will be changed to that value.

For example, the expression 3d6mi2 means "roll three size-sided dice for which the minimum roll value is 2".

Keep

Using the kh or kl notations, you can keep the specified highest or lowest, respectively, dice roll values. For instance, the expression 4d6kh3 translates to "roll four six-sided dice, keeping the highest three".

This notation can also be seen as dropping results instead of keeping them. For example, keeping the highest three in a roll of four dice is the same as dropping the lowest one. Similarly, keeping the lowest roll in a roll of four dice is the same as dropping the highest three.

Explode

Rolling exploding dice is similar to rolling regular dice, with the added fact that whenever a specified value, usually the highest possible, is rolled, the die is rolled again.

Using the ! notation, you can roll exploding dice. By omitting a value afterwards, d7 will use the highest possible die value as the exploding one.

For example, the expression 1d6! means "roll one six-sided die, exploding on 6" and 1d6!3 is "roll one six-sided die, exploding on 3".

Output

After rolling a dice expression, using the toJSON() method you can obtain the JSON formatted string representation of the dice expression.

{
  "args": {                 # The different arguments of the given dice expression
    "diceSize": 6,          # The size of the dice
    "explode": null,        # Whether the dice are exploding dice or not
    "explodeValue": null,   # The exploding value
    "keep": null,           # Whether it was a keep highest or keep lowest (or neither) expression
    "keepValue": null,      # The keeping value
    "min": null,            # Whether the dice had a minimum value or not
    "minValue": null,       # The minimum value
    "mod": null,            # The modifier applied to the expression
    "modValue": null,       # The value of the modifier
    "nDice": 1,             # The number of dice
    "reroll": null,         # Whether it was a re-roll once or re-roll (or neither) expression
    "rerollValue": null     # The re-roll value
  },
  "dice": [                 # The rolled dice
    {
      "exploded": false,    # Whether or not the dice was created from an explosion
      "history": [          # The history of rolls for the dice
        1
      ],
      "keep": true,         # Whether the dice was used in the result calculation
      "size": 6             # The size of the dice
    }
  ],
  "expression": "1d6",      # The initial expression
  "maxReroll": 5,           # The maximum number of times a dice can be re-rolled
  "total": 1                # The result of the roll
}

Project details


Download files

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

Source Distribution

d7-1.0.1.tar.gz (6.6 kB view details)

Uploaded Source

Built Distribution

d7-1.0.1-py3-none-any.whl (6.6 kB view details)

Uploaded Python 3

File details

Details for the file d7-1.0.1.tar.gz.

File metadata

  • Download URL: d7-1.0.1.tar.gz
  • Upload date:
  • Size: 6.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.10.8

File hashes

Hashes for d7-1.0.1.tar.gz
Algorithm Hash digest
SHA256 eb3deca003d549b02396aaeb7e6a8c3d3f60dd218d74ea026b09f73d76b9888d
MD5 d7ef0363bcb83bd3d9b9f734ffe1a53a
BLAKE2b-256 475eb1538624cc06883aeacf77d7900d3c700c1f27879476722ee70ccd79fd38

See more details on using hashes here.

File details

Details for the file d7-1.0.1-py3-none-any.whl.

File metadata

  • Download URL: d7-1.0.1-py3-none-any.whl
  • Upload date:
  • Size: 6.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.10.8

File hashes

Hashes for d7-1.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 f40032fc8291b33791c9022e1818489eb21429e6a5036f40cbbf1c552f1e977d
MD5 9f73df2046c1f95ff674cfa3bbef7657
BLAKE2b-256 f85b1d824d497d0e9880728fb99c19a8943a30e63b09cea58edb44f1bf23e8f7

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page