#random #dice #string-parser #dice-rolling #rogue-like #gamedev #xorshift

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.

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

#1050 in Game dev

Download history 1048/week @ 2024-06-18 1219/week @ 2024-06-25 273/week @ 2024-07-02 894/week @ 2024-07-09 1229/week @ 2024-07-16 1174/week @ 2024-07-23 1077/week @ 2024-07-30 1588/week @ 2024-08-06 1719/week @ 2024-08-13 1259/week @ 2024-08-20 1539/week @ 2024-08-27 1430/week @ 2024-09-03 1070/week @ 2024-09-10 1197/week @ 2024-09-17 1426/week @ 2024-09-24 866/week @ 2024-10-01

4,712 downloads per month
Used in 11 crates (5 directly)

MIT license

30KB
525 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

~0.2–1.3MB
~22K SLoC