bracket-random

Part of the bracket-lib family, bracket-random is focused on providing dice-oriented random numbers. It also (optionally) includes parsing of RPG-style dice strings (e.g. 3d6+12). It is targeted at games, particularly RPGs. It uses the high-performance XorShift algorithm for random number generation.

Using bracket-random

To obtain bracket-random, include the following in your Cargo.toml file:

[dependencies]

bracket-random = "0.8.2"

It will be available as a crate very soon.

You can use bracket-random by including the prelude and instantiating RandomNumberGenerator:

use bracket_random::prelude::*;
let mut rng = RandomNumberGenerator::new();

You can also seed the RNG with RandomNumberGenerator::seeded(1234).

Obtaining Randomness

There are a number of random options available:

rng.roll_dice(1, 6) rolls a six-sided die once.
rng.roll_dice(3, 6) rolls three six-sided die, and adds them up.
rng.roll_str("3d6+12") rolls three six-sided die, adds them up, and adds twelve to the result.
rng.next_u64 provides a random u64, anywhere within the u64 range.
rng.rand::<TYPE>() tries to provide a random number of type TYPE.
rng.range(min, max) tries to provide a random number within the specified range.
rng.slice_index(&slice) returns an Option with None if there are no options, or the index of a randomly selected slice entry. This is handy for treasure tables.
rng.slice(&slice) returns an Option with None for empty slices, or the contents of a randomly selected slice entry.

Parsing RPG-style dice strings

The bracket-random library includes a dice string parser. You can try to parse a string as follows:

use bracket_random::prelude::*;
let dice_type = parse_dice_string("3d6-4");

This returns a Result, which will either be Ok or a parsing error. If unwrapped, it provides a DiceType structure, breaking out the details of the requested die roll.

It supports 1d6, 3d6+1, and 5d6-1 formats. If you turn off the parsing feature flag, this feature is excluded - but your project won't be bloated by regular expression libraries and lazy_static.

Feature Flags

parsing enables parsing of dice types as strings.
serde makes the DiceType structure serializable.
If you are compiling for wasm32-unknown-unknown, it automatically includes wasm-bindgen.

Examples

Execute examples with cargo run --example <name>.