#roguelike #gamedev #random #xorshift #dice


Random number generator (xorshift based), focused on dice rolling. Optionally includes parsing of RPG-style dice strings (e.g. "3d6+12"). Part of the bracket-lib family.

5 unstable releases

0.8.7 Oct 4, 2022
0.8.2 Feb 10, 2021
0.8.0 Apr 8, 2020
0.7.0 Feb 22, 2020
0.1.0 Feb 21, 2020

#396 in Game dev

Download history 338/week @ 2023-06-07 924/week @ 2023-06-14 1330/week @ 2023-06-21 912/week @ 2023-06-28 1148/week @ 2023-07-05 869/week @ 2023-07-12 1190/week @ 2023-07-19 1496/week @ 2023-07-26 734/week @ 2023-08-02 1019/week @ 2023-08-09 1102/week @ 2023-08-16 735/week @ 2023-08-23 727/week @ 2023-08-30 1119/week @ 2023-09-06 1045/week @ 2023-09-13 501/week @ 2023-09-20

3,607 downloads per month
Used in 9 crates (5 directly)

MIT license

525 lines


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:

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.


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.


~20K SLoC