### 1 unstable release

0.1.0 | Nov 10, 2022 |
---|

#**906** in Game dev

**MIT**license

9KB

118 lines

# Diceroll

A simple dice rolling lib for RPG purposes in Rust.

## Usage

Install the package by adding it to Cargo.toml:

`[``dependencies``]`
`diceroll ``=` `"`0.1.0`"`

The basic way you use the library is creating a diceroll using

, configuring it with the builder pattern with the parameters you want. Then you pass said configuration to the `DiceRoll ::`new

`(`

`)`

`roll``(``)`

function, giving you a `RollResult`

struct containing an i32 `total`

and a Vec of individual `rolls`

. It is also possible to pass the configured diceroll to `roll_with_advantage`

or to `roll_with_disadvantage`

, which will return an array of two roll results with index 0 always containing the "winning" roll (with disadvantage this means the lowest result, with advantage this means the highest), and with index 1 always containing the discarded roll.The following parameters are supported:

- dice [i32] (mandatory): The amount of dice to roll.
- sides [i32] (mandatory): How many sides each die should have.
- target [i32]: Off by default. If this parameter is set, instead of the total containing the sum of the dicerolls, the total will show how many individual dice yielded a result higher than or equal to the target number. This is useful for any RPG that uses dicepool rolling, such as World of Darkness and Shadowrun.
- ones_subtract [bool]: Off by default. If a target number is set, enabling this will remove a success for every die that turns up 1.
- explode_on [i32]: Off by default. Will record the result and then reroll any dice that rolls higher than or equal to the explode_on number.
- modifier [i32]: Off by default. Will add itself to (or subtract from, if the number is negative) the total sum of the roll. Has no effect on rolls that use a target number.

## Examples

### A basic roll:

`use` `diceroll``::``*``;`
`fn` `main``(``)`` ``{`
`let` amount_of_dice `=` `2``;`
`let` sides `=` `6``;`
`let` modifier `=` `2``;`
`let` result `=` `roll``(``DiceRoll``::`new`(``)`
`.``dice``(`amount_of_dice`)`
`.``sides``(`sides`)`
`.``modifier``(`modifier`)``)`
`println!``(``"`We rolled `{}`d`{}`+`{}`, which yielded a total of `{}`.`"``,` amount_of_dice`,` sides`,` modifier`,` result`.`total`)``;`
`}`

This will give an output looking something like this:

`We rolled 2d6``+``2``,` which yielded a total of `9.`

### Roll with advantage

Note that we are using the itertools crate for joining the roll results in this example.

`use` `itertools``::`Itertools`;`
`use` `diceroll``::``*``;`
`fn` `main``(``)`` ``{`
`let` amount_of_dice `=` `1``;`
`let` sides `=` `20``;`
`let` modifier `=` `2``;`
`let` result `=` `roll_with_advantage``(``DiceRoll``::`new`(``)`
`.``dice``(`amount_of_dice`)`
`.``sides``(`sides`)`
`.``modifier``(`modifier`)``)``;`
`println!``(``"`We rolled `{}`d`{}`+`{}` with advantage`"``,` amount_of_dice`,` sides`,` modifier`)``;`
`println!``(``"`--- The winning roll (`{}`) yielded a total of `{}``"``,` `Itertools``::`join`(``&``mut` result`[``0``]``.`rolls`.``iter``(``)``,` `"`,`"``)``,` result`[``0``]``.`total`)``;`
`println!``(``"`--- The discarded roll (`{}`) yielded a total of `{}``"``,` `Itertools``::`join`(``&``mut` result`[``1``]``.`rolls`.``iter``(``)``,` `"`,`"``)``,` result`[``1``]``.`total`)``;`
`}`

### New World of Darkness/Chronicles of Darkness dice pool roll

Note that we are using the itertools crate for joining the roll results in this example.

`use` `itertools``::`Itertools`;`
`use` `diceroll``::``*``;`
`fn` `main``(``)`` ``{`
`let` amount_of_dice `=` `5``;`
`let` sides `=` `10``;`
`let` target `=` `8``;`
`let` explode_on `=` `10``;`
`let` result `=` `roll``(``DiceRoll``::`new`(``)`
`.``dice``(`amount_of_dice`)`
`.``sides``(`sides`)`
`.``target``(`target`)`
`.``explode_on``(`explode_on`)``)``;`
`println!``(``"`We rolled a dice pool of `{}`d`{}` with a target number of `{}` and exploding successes on `{}``"``,` amount_of_dice`,` sides`,` target`,` explode_on`)``;`
`println!``(``"`--- The result of the rolls (`{}`) yielded a total of `{}``"``,` `Itertools``::`join`(``&``mut` result`[``0``]``.`rolls`.``iter``(``)``,` `"`,`"``)``,` result`.`total`)``;`
`}`

#### Dependencies

~310KB