Package: d7
d7A 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 expression1d6means"roll one six-sided die"while2d4+1is"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.UsageUsing d7 is very simple. Simply install the package:pip install d7Then import as usual, using theDiceExpressionclass from thedice_expressionmodule:>>> from d7 import dice_expression as d7
>>> expression = d7.DiceExpression("1d6+2")
>>> expression.roll()
5NotationUsing the different notations below, on top of the traditionalXdY, 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->+|-|*|/|/^ModifiersIn 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-rollingYou can use therrorronotation to re-roll dice, depending on a specified condition. Therrnotation translates to "re-roll" while theromeans "re-roll once".For instance, the expression1d6rr2translates to "roll one six-sided die, re-rolling the value two" while1d6ro2is "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).MinimumThrough the use of theminotation, 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 expression3d6mi2means"roll three size-sided dice for which the minimum roll value is 2".KeepUsing thekhorklnotations, you can keep the specified highest or lowest, respectively, dice roll values. For instance, the expression4d6kh3translates 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.ExplodeRolling 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 expression1d6!means"roll one six-sided die, exploding on 6"and1d6!3is"roll one six-sided die, exploding on 3".OutputAfter rolling a dice expression, using thetoJSON()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
}