### 3 unstable releases

0.2.0 | May 22, 2024 |
---|---|

0.1.2 | Oct 12, 2023 |

0.1.0 | Oct 12, 2023 |

#**5** in #dice-notation

**21** downloads per month

**LGPL-3.0-only**

13KB

350 lines

# Dice-Bag (Rust Lib)

This library uses standard RPG notation for generating dice rolls producing a total but also a break down of all the rolls should they be needed.

To import it use:

`//` Cargo.toml
`[`dependencies`]`
dice`-`bag `=` `"`0.2`"`

It has a main entry point of:

`use` `dice``::`dice`;`
`dice``::`roll`(``"`3d10+1`"``)`

produces a structure:

`AllRollResults ``{`
`pub` total`:` `isize``,`
`pub` rolled`:` `Vec``<`RollResult`>``,`
`}`
RollResult `{`
`pub` total`:` `isize``,`
`pub` rolled`:` DiceRolls`,`
`pub` selected_rolls`:` DiceRolls`,`
`pub` sides`:` `usize``,`
`pub` num_dice`:` `usize``,`
`pub` modifier`:` `isize``,`
`}`

e.g. for 3d10+1 rolling 6,5,2

`{`
total`:` `14``,`
rolled`:` `[`
`{`
total`:` `14`
rolled`:` `[` `6``,` `5``,` `2``]`
selected_rolls`:` `[` `6``,` `5``,` `2``]`
sides`:` `6`
num_dice`:` `3`
modifier`:` `1`
`}`
`]`
`}`

Dice can also be chained together:

`dice``::`roll`(``"`2d8 4d4+8`"``)`

where a result might look like this:

`{`
total`:` `25``,`
rolled`:` `[`
`{`
total`:` `9`
rolled`:` `[` `8``,` `1``]`
selected_rolls`:` `[` `8``,` `1``]`
sides`:` `8`
num_dice`:` `2`
modifier`:` `0`
`}``,`
`{`
total`:` `16`
rolled`:` `[` `3``,` `2``,` `2``,` `1``]`
selected_rolls`:` `[` `3``,` `2``,` `2``,` `1``]`
sides`:` `4`
num_dice`:` `4`
modifier`:` `8`
`}`
`]`
`}`

You can directly use the roll method:

`dice``::``Dice``::`roll`(``3``,` `6``,` `-``2``)``;`

which produces a single

, for example:`Result``<`RollResult, `String``>`

`Ok``(` RollResult `{`
total`:` `6`
rolled`:` `[` `5``,` `2``,` `1` `]`
selected_rolls`:` `[` `5``,` `2``,` `1` `]`
sides`:` `6`
num_dice`:` `3`
modifier`:` `-``2`
`}` `)`

Dice roll results are all sorted highest to lowest.

Finally the

for the results is overwritten to produce a parsable slug:`Display`

`dice``::`roll`(``"`3d6-2 2d4+1`"``)`)`.``to_string``(``)``;`

could produce:

`3d6``-``2``,`2d4`+``1``:``[``4``,``2``,``1``]``,``[``4``,``3``]``:``13`

`dice``::`roll`(``"`2d10+3`"``)`)`.``to_string``(``)``;`

could produce:

`2d10``+``3``:``[``10``,``1``]``:``14`

#### Dependencies

~2.3–3.5MB

~59K SLoC