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>.

• diceroll rolls 3d6 (specified as roll_dice(1,6)) 10 times and prints the results.
• dicestring rolls 3d6 (specified as roll_str("3d6")) 10 times and prints the results.
• distribution rolls 3d6, 200,000 times and plots the distribution of each cumulative result.
• next obtains the next 10 u64 random numbers and prints them.
• rand obtains the next 10 f64 random numbers and prints them. This demonstrates how the rand function can take any type that the underlying random library considers sufficiently numeric.
• range obtains the next 10 random numbers in the range 100.200 and prints them.
• slice_index randomly picks a slice index, prints it - and the contents of the array that was sliced.
• slice randomly picks a slice entry and prints it.
• die_iterator uses the (new and in need of work) DiceIterator function to roll 10d6 in a compact manner.