Crate seeded_dice_roller
source ·Expand description
Seeded Dice Roller
SeededDiceRoller is, as its name implies, a dice roller using a seed to give pseudo-random deterministic results.
In other words, it returns “random” results, which will always be the same if you use the same seed and call the same methods in the same order.
How does it work
You generate a Dice Roller using a seed, then you can use it to make dice rolls, generate random numbers or booleans, or select a specific result in an array of possible choices using either a predefined dice roll, a gaussian distribution or a simple pick at random.
It is also possible to give weight to the various choices in order to multiply their chances to be selected.
Seed
The seed is split into two parts, the seed proper and a “step”. The seed represents something like the “session” of the run, while the step represents the name of the task currently at hand. The idea is to keep seeded generation consistent between versions of your program.
For example, if we want to generate a dungeon using the player-inputted seed “water temple”, we might create three specific instances of SeededDiceRoller using “map_gen_shape”, “map_gen_walls” and “map_gen_treasures” values for the step in order to always get the same results for those specific tasks, no matter how many other tasks you might add or remove before them in the future.
Examples
Dice rolls
let mut rng = SeededDiceRoller::new("seed", "step");
assert_eq!(rng.roll(1, 6, 0), 6);
assert_eq!(rng.roll(3, 6, -5), 1);
assert_eq!(rng.roll(3, 6, -5), 8);
Random picks
Picks a result using a predefined roll type
let mut rng = seeded_dice_roller::SeededDiceRoller::new("seed", "step");
let possible_results = SeededDiceRoller::to_copyable_possible_results(vec![
"a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k"
]);
let result = rng.get_result(&CopyableRollToProcess {
possible_results: possible_results.clone(),
roll_method: RollMethod::PreparedRoll(PreparedRoll {
dice: 2,
die_type: 6,
modifier: 0
}),
}).unwrap();
assert_eq!(result, "g");
Picks a result with higher chances to get one from the middle of the array
let mut rng = seeded_dice_roller::SeededDiceRoller::new("seed", "step");
let possible_results = SeededDiceRoller::to_copyable_possible_results(vec![
"a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k"
]);
let result = rng.get_result(&CopyableRollToProcess {
possible_results: possible_results.clone(),
roll_method: RollMethod::GaussianRoll(5),
}).unwrap();
assert_eq!(result, "e");
Picks a result randomly, each choice has an equal chance to be selected
let mut rng = seeded_dice_roller::SeededDiceRoller::new("seed", "step");
let possible_results = SeededDiceRoller::to_copyable_possible_results(vec![
"a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k"
]);
let result = rng.get_result(&CopyableRollToProcess {
possible_results: possible_results.clone(),
roll_method: RollMethod::SimpleRoll,
}).unwrap();
assert_eq!(result, "c");
Picks a result randomly, “a” is 5 times more likely to be selected than “b” or “c”
let mut rng = seeded_dice_roller::SeededDiceRoller::new("seed", "step");
let weighted_set = vec![
CopyableWeightedResult { result: "a", weight: 5 },
CopyableWeightedResult { result: "b", weight: 1 },
CopyableWeightedResult { result: "c", weight: 1 },
];
let result = rng.get_result(&CopyableRollToProcess {
possible_results: weighted_set,
roll_method: RollMethod::SimpleRoll,
}).unwrap();
assert_eq!(result, "c");
Structs
- Data allowing to pick a result at random in a list of possible results. The results must be copyable.
- A result able to be picked at random in a list of possible results. The weight is used to determine the chances of this result to be picked against all other possible choices. The result must be copyable.
- Data allowing to roll dice times a die_type sided die and add an eventual modifier.
- Data allowing to pick a result at random in a list of possible results.
- Uses a Random Number Generator fed with a seed to generate dice roll results, booleans and numbers in a deterministic way.
- A result able to be picked at random in a list of possible results. The weight is used to determine the chances of this result to be picked against all other possible choices.
Enums
- Enum used to know how to determine the result of a random pick in a list of possible results.