#roguelike #gamedev #random #xorshift #dice

bracket-random

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.

4 releases (2 breaking)

0.8.2 Feb 10, 2021
0.8.0 Apr 8, 2020
0.7.0 Feb 22, 2020
0.1.0 Feb 21, 2020

#89 in Game dev

Download history 201/week @ 2020-11-07 217/week @ 2020-11-14 302/week @ 2020-11-21 238/week @ 2020-11-28 221/week @ 2020-12-05 176/week @ 2020-12-12 142/week @ 2020-12-19 106/week @ 2020-12-26 233/week @ 2021-01-02 335/week @ 2021-01-09 266/week @ 2021-01-16 227/week @ 2021-01-23 227/week @ 2021-01-30 356/week @ 2021-02-06 290/week @ 2021-02-13 334/week @ 2021-02-20

988 downloads per month
Used in 8 crates (4 directly)

MIT license

17KB
322 lines

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.

Dependencies

~56–540KB
~12K SLoC