dice

The opend6_tools.dice module is a small DSL for dice specifications. This is shared by the opend6_tools.magic and opend6_tools.character modules.

A class definition implements operators to support n *D and D+ n, where n is a number. It will also support more complex operations like 3*D + 4*D + 2.

The global object D is the essential ingredient here. It permits an expression like:

DamageEffect("Attack", 3*D+2)

Additionally, this module also offers a command-line interface: an dice command.

(opend6-tools) % dice --help

 Usage: dice [OPTIONS] [EXPR]

 Roll the handful of dice described by a dice expression. Use the --count
 option to roll multiple times.

 ? is a critical failure showing a total with the largest die value excluded, and, in ()'s, the total of all dice.

 ! is a critical success followed by the number of re-rolls.

╭─ Arguments ───────────────────────────────────────────────────────────────╮
│   expr      [EXPR]  Dice expression, example: '2*D6+3' (quotes are        │
│                     *required*)                                           │
╰───────────────────────────────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────────────────────────────╮
│ --count               -c      INTEGER  number of times to roll            │
│                                        [default: 1]                       │
│ --install-completion                   Install completion for the current │
│                                        shell.                             │
│ --show-completion                      Show completion for the current    │
│                                        shell, to copy it or customize the │
│                                        installation.                      │
│ --help                                 Show this message and exit.        │
╰───────────────────────────────────────────────────────────────────────────╯

Implementation

A DSL for dice definitions.

The most important global object is D, which is the basis for the DieCode DSL.

Example:

>>> from opend6_tools.dice import D
>>> 3*D + 2
3*D+2

class opend6_tools.dice.DieCode(n: int | Decimal = 1, adj: int | Decimal = 0)

Specifications for collections of dice. Computes the overall measure, \(3 \times d + p\).

>>> from opend6_tools.dice import *

>>> r = 3*D+2
>>> r.measure
Decimal('11')
>>> repr(r)
'3*D+2'

Can also parse a text specification.

>>> t = DieCode.parse_str("3D+2")
>>> t.measure
Decimal('11')
>>> repr(t)
'3*D+2'

A degenerate case of only pips, not clear why someone might need this.

>>> DieCode.parse_str("2")
0*D+2
>>> 0*D + 2
0*D+2

>>> from random import seed
>>> seed(42)
>>> physique = 4*D
>>> [str(physique.roll()) for _ in range(12)]
['17!', '13!', '12? (18)', '6? (11)', '10', '13', '23', '15', '16!', '10', '9', '12']

__init__(n: int | Decimal = 1, adj: int | Decimal = 0) → None

Create a working DieCode instance, usually the global D.

n

Number of dice

adj

Additional pips

__repr__() → str

Return repr(self).

__str__() → str

Return str(self).

__mul__(other: Any) → DieCode

Implement the * operator for D and a number.

__rmul__(other: Any) → DieCode

Implement the * operator for D and a number.

__add__(other: Any) → DieCode

Implement the + operator for D and a number.

__radd__(other: Any) → DieCode

Implement the + operator for D and a number.

__eq__(other: Any) → bool

Return self==value.

property d: int

Legacy attribute reference, now a property.

classmethod from_pips(pips: int | Decimal) → DieCode

Converts number of pips to Die + Pips.

Parameters:

pips – pips value

Returns:

DieCode

property measure: Decimal

The overall measure associated with this DieCode.

classmethod parse_str(text: str) → DieCode

Parse a string representation of a DieCode object, example: "3D+2".

The syntax has three closely-related forms: [+]n[*]D+n | [+]n[*]D | +n

Pragmatically, + and * are essentially whitespace. The meaningful tokens are strings of digits and D. The three interesting forms are nDn, nD, and n.

roll() → Roll

The “Wild Die” roll algorithm.

This returns several things:

1. Ordinary result: a Roll instance.

2. Critical Success, wild die was 6.

   A CriticalSuccess instance.

3. Critical Failure, wild die was 1.

   Two totals (with and without the highest die value.) A CriticalFailure instance.

__weakref__

list of weak references to the object

class opend6_tools.dice.Roll(die: list[int], pips: int, rolls: int)

A single roll of the dice.

die: list[int]

The die values

fail: ClassVar[bool] = False

pips: int

Additional pips to add

rolls: int

Number of rolls (>1 for Critical Success)

success: ClassVar[bool] = False

property total: int

Total of Die plus bonus pips

class opend6_tools.dice.CriticalSuccess(die: list[int], pips: int, rolls: int)

Bases: Roll

A single roll that was a Critical Success – Wild Die was 6.

class opend6_tools.dice.CriticalFailure(die: list[int], pips: int, rolls: int)

Bases: Roll

A single roll that was a Critical Failure – Wild Die was 1.

This includes the dice_app CLI.

opend6_tools.dice.main(expr: ~typing.Annotated[~opend6_tools.dice.DieCode, <typer.models.ArgumentInfo object at 0x10a8f4ec0>], count: ~typing.Annotated[int, <typer.models.OptionInfo object at 0x10a846210>] = 1)

Roll the handful of dice described by a dice expression. Use the –count option to roll multiple times.

? is a critical failure showing a total with the largest die value excluded, and, in ()’s, the total of all dice.

! is a critical success followed by the number of re-rolls.