Enum tyche::dice::modifier::Modifier

source ·

#[non_exhaustive]pub enum Modifier {
    Reroll {
        cond: Condition,
        recurse: bool,
    },
    Explode {
        cond: Option<Condition>,
        recurse: bool,
    },
    KeepHigh(u8),
    KeepLow(u8),
    Min(u8),
    Max(u8),
}

Expand description

Routines that can be applied to Dice to automatically manipulate resulting Rolled dice sets from them as part of their rolling process.

Variants (Non-exhaustive)§

This enum is marked as non-exhaustive

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

§

Reroll

Fields

§cond: Condition

Condition that rolls must pass in order to be rerolled

§recurse: bool

Whether the reroll should be done repeatedly until the rerolled die no longer meets the condition

Rerolls (drops original and adds a newly-rolled die) dice that meet a condition.

§Examples

§Reroll recursively (`rr`)

use tyche::dice::{modifier::{Condition, Modifier}, roller::{Iter as IterRoller, Roller}, Dice, Rolled};

// Build the 4d6rr1 dice set and create a roller that has predetermined values for the dice rolls
let dice = Dice::builder().count(4).sides(6).reroll(Condition::Eq(1), true).build();
let premade_rolls = [3, 6, 1, 2, 1, 4];
let mut rng = IterRoller::new(premade_rolls);

// Roll the dice, but don't have it automatically apply its modifiers (passing `false` as the second `roll()` param).
// Only the first four predetermined values will be used for the dice rolls since there are only four dice to roll.
let mut rolled = rng.roll(&dice, false)?;

// Explicitly create and apply an rr1 modifier. This is usually not necessary since the dice has its own instance of
// it from the builder and will automatically apply it when passing `true` to `roll()`, but we do it this way here
// for demonstration purposes.
let rr1_mod = Modifier::Reroll {
	cond: Condition::Eq(1),
	recurse: true,
};
rr1_mod.apply(&mut rolled, &mut rng)?;

// Upon being applied, the modifier will drop the 1 roll, roll a new 1 from the predetermined RNG, drop that too,
// then roll a new 4 from the RNG.
// Final expected rolled dice set, after rr1 modifier: 4d6rr1[3, 6, 1 (d), 2, 1 (d), 4]
let mut expected = Rolled::from_dice_and_rolls(&dice, premade_rolls);
expected.rolls[2].drop(rr1_mod);
expected.rolls[4].add(rr1_mod);
expected.rolls[4].drop(rr1_mod);
expected.rolls[5].add(rr1_mod);
assert_eq!(rolled, expected);

§Reroll once (`r`)

use tyche::dice::{modifier::{Condition, Modifier}, roller::{Iter as IterRoller, Roller}, Dice, Rolled};

// Build the 4d6r1 dice set and create a roller that has predetermined values for the dice rolls
let dice = Dice::builder().count(4).sides(6).reroll(Condition::Eq(1), false).build();
let premade_rolls = [3, 6, 1, 2, 1];
let mut rng = IterRoller::new(premade_rolls);

// Roll the dice, but don't have it automatically apply its modifiers (passing `false` as the second `roll()` param).
// Only the first four predetermined values will be used for the dice rolls since there are only four dice to roll.
let mut rolled = rng.roll(&dice, false)?;

// Explicitly create and apply an r1 modifier. This is usually not necessary since the dice has its own instance of
// it from the builder and will automatically apply it when passing `true` to `roll()`, but we do it this way here
// for demonstration purposes.
let r1_mod = Modifier::Reroll {
	cond: Condition::Eq(1),
	recurse: false,
};
r1_mod.apply(&mut rolled, &mut rng)?;

// Upon being applied, the modifier will drop the 1 roll and roll a new 1 from the predetermined RNG.
// Final expected rolled dice set, after r1 modifier: 4d6r1[3, 6, 1 (d), 2, 1]
let mut expected = Rolled::from_dice_and_rolls(&dice, premade_rolls);
expected.rolls[2].drop(r1_mod);
expected.rolls[4].add(r1_mod);
assert_eq!(rolled, expected);

§

Explode

Fields

§cond: Option<Condition>

Condition that rolls must pass in order to explode. If None, the roll values must be equal to the number of sides of the dice being rolled.

§recurse: bool

Whether the explosion should be done repeatedly for any additional rolls that also meet the condition

Explodes (keeps original and adds an additional newly-rolled die) dice that meet a condition.

§Examples

§Explode recursively (`x`)

use tyche::dice::{modifier::{Condition, Modifier}, roller::{Iter as IterRoller, Roller}, Dice, Rolled};

// Build the 4d6x dice set and create a roller that has predetermined values for the dice rolls
let dice = Dice::builder().count(4).sides(6).explode(None, true).build();
let premade_rolls = [3, 6, 1, 2, 6, 4];
let mut rng = IterRoller::new(premade_rolls);

// Roll the dice, but don't have it automatically apply its modifiers (passing `false` as the second `roll()` param).
// Only the first four predetermined values will be used for the dice rolls since there are only four dice to roll.
let mut rolled = rng.roll(&dice, false)?;

// Explicitly create and apply an x modifier. This is usually not necessary since the dice has its own instance of
// it from the builder and will automatically apply it when passing `true` to `roll()`, but we do it this way here
// for demonstration purposes.
let x_mod = Modifier::Explode {
	cond: None,
	recurse: true,
};
x_mod.apply(&mut rolled, &mut rng)?;

// Upon being applied, the modifier will see that a 6 (the max die value) was rolled, roll a new additional 6, see
// that is also the max die value, then roll a new 4 as well.
// Final expected rolled dice set, after x modifier: 4d6x[3, 6, 1, 2, 6, 4]
let mut expected = Rolled::from_dice_and_rolls(&dice, premade_rolls);
expected.rolls[4].add(x_mod);
expected.rolls[5].add(x_mod);
assert_eq!(rolled, expected);

§Explode once (`xo`)

use tyche::dice::{modifier::{Condition, Modifier}, roller::{Iter as IterRoller, Roller}, Dice, Rolled};

// Build the 4d6xo dice set and create a roller that has predetermined values for the dice rolls
let dice = Dice::builder().count(4).sides(6).explode(None, false).build();
let premade_rolls = [3, 6, 1, 2, 6];
let mut rng = IterRoller::new(premade_rolls);

// Roll the dice, but don't have it automatically apply its modifiers (passing `false` as the second `roll()` param).
// Only the first four predetermined values will be used for the dice rolls since there are only four dice to roll.
let mut rolled = rng.roll(&dice, false)?;

// Explicitly create and apply an xo modifier. This is usually not necessary since the dice has its own instance of
// it from the builder and will automatically apply it when passing `true` to `roll()`, but we do it this way here
// for demonstration purposes.
let xo_mod = Modifier::Explode {
	cond: None,
	recurse: false,
};
xo_mod.apply(&mut rolled, &mut rng)?;

// Upon being applied, the modifier will see that a 6 (the max die value) was rolled and roll a new additional 6.
// Final expected rolled dice set, after xo modifier: 4d6xo[3, 6, 1, 2, 6]
let mut expected = Rolled::from_dice_and_rolls(&dice, premade_rolls);
expected.rolls[4].add(xo_mod);
assert_eq!(rolled, expected);

§

KeepHigh(u8)

Keeps only the highest x dice, dropping the rest.

§Examples

§Keep highest die (`kh`)

use tyche::dice::{modifier::{Condition, Modifier}, roller::{Iter as IterRoller, Roller}, Dice, Rolled};

// Build the 4d6kh dice set and create a roller that has predetermined values for the dice rolls
let dice = Dice::builder().count(4).sides(6).keep_high(1).build();
let premade_rolls = [3, 6, 1, 2];
let mut rng = IterRoller::new(premade_rolls);

// Roll the dice, but don't have it automatically apply its modifiers (passing `false` as the second `roll()` param).
let mut rolled = rng.roll(&dice, false)?;

// Explicitly create and apply a kh modifier. This is usually not necessary since the dice has its own instance of
// it from the builder and will automatically apply it when passing `true` to `roll()`, but we do it this way here
// for demonstration purposes.
let kh_mod = Modifier::KeepHigh(1);
kh_mod.apply(&mut rolled, &mut rng)?;

// Upon being applied, the modifier will drop all rolls except the highest one, so 3, 1, and 2 will be dropped.
// Final expected rolled dice set, after kh modifier: 4d6kh[3 (d), 6, 1 (d), 2 (d)]
let mut expected = Rolled::from_dice_and_rolls(&dice, premade_rolls);
expected.rolls[0].drop(kh_mod);
expected.rolls[2].drop(kh_mod);
expected.rolls[3].drop(kh_mod);
assert_eq!(rolled, expected);

§Keep highest 2 dice (`kh2`)

use tyche::dice::{modifier::{Condition, Modifier}, roller::{Iter as IterRoller, Roller}, Dice, Rolled};

// Build the 4d6kh2 dice set and create a roller that has predetermined values for the dice rolls
let dice = Dice::builder().count(4).sides(6).keep_high(2).build();
let premade_rolls = [3, 6, 1, 2];
let mut rng = IterRoller::new(premade_rolls);

// Roll the dice, but don't have it automatically apply its modifiers (passing `false` as the second `roll()` param).
let mut rolled = rng.roll(&dice, false)?;

// Explicitly create and apply a kh2 modifier. This is usually not necessary since the dice has its own instance of
// it from the builder and will automatically apply it when passing `true` to `roll()`, but we do it this way here
// for demonstration purposes.
let kh2_mod = Modifier::KeepHigh(2);
kh2_mod.apply(&mut rolled, &mut rng)?;

// Upon being applied, the modifier will drop all rolls except the two highest, so 1 and 2 will be dropped.
// Final expected rolled dice set, after kh2 modifier: 4d6kh2[3, 6, 1 (d), 2 (d)]
let mut expected = Rolled::from_dice_and_rolls(&dice, premade_rolls);
expected.rolls[2].drop(kh2_mod);
expected.rolls[3].drop(kh2_mod);
assert_eq!(rolled, expected);

§

KeepLow(u8)

Keeps only the lowest x dice, dropping the rest.

§Examples

§Keep lowest die (`kl`)

use tyche::dice::{modifier::{Condition, Modifier}, roller::{Iter as IterRoller, Roller}, Dice, Rolled};

// Build the 4d6kl dice set and create a roller that has predetermined values for the dice rolls
let dice = Dice::builder().count(4).sides(6).keep_low(1).build();
let premade_rolls = [3, 6, 1, 2];
let mut rng = IterRoller::new(premade_rolls);

// Roll the dice, but don't have it automatically apply its modifiers (passing `false` as the second `roll()` param).
let mut rolled = rng.roll(&dice, false)?;

// Explicitly create and apply a kl modifier. This is usually not necessary since the dice has its own instance of
// it from the builder and will automatically apply it when passing `true` to `roll()`, but we do it this way here
// for demonstration purposes.
let kl_mod = Modifier::KeepLow(1);
kl_mod.apply(&mut rolled, &mut rng)?;

// Upon being applied, the modifier will drop all rolls except the lowest one, so 3, 6, and 2 will be dropped.
// Final expected rolled dice set, after kl modifier: 4d6kl[3 (d), 6 (d), 1, 2 (d)]
let mut expected = Rolled::from_dice_and_rolls(&dice, premade_rolls);
expected.rolls[0].drop(kl_mod);
expected.rolls[1].drop(kl_mod);
expected.rolls[3].drop(kl_mod);
assert_eq!(rolled, expected);

§Keep lowest 2 dice (`kl2`)

use tyche::dice::{modifier::{Condition, Modifier}, roller::{Iter as IterRoller, Roller}, Dice, Rolled};

// Build the 4d6kl2 dice set and create a roller that has predetermined values for the dice rolls
let dice = Dice::builder().count(4).sides(6).keep_low(2).build();
let premade_rolls = [3, 6, 1, 2];
let mut rng = IterRoller::new(premade_rolls);

// Roll the dice, but don't have it automatically apply its modifiers (passing `false` as the second `roll()` param).
let mut rolled = rng.roll(&dice, false)?;

// Explicitly create and apply a kl2 modifier. This is usually not necessary since the dice has its own instance of
// it from the builder and will automatically apply it when passing `true` to `roll()`, but we do it this way here
// for demonstration purposes.
let kl2_mod = Modifier::KeepLow(2);
kl2_mod.apply(&mut rolled, &mut rng)?;

// Upon being applied, the modifier will drop all rolls except the two lowest, so 3 and 6 will be dropped.
// Final expected rolled dice set, after kl2 modifier: 4d6kl2[3 (d), 6 (d), 1, 2]
let mut expected = Rolled::from_dice_and_rolls(&dice, premade_rolls);
expected.rolls[0].drop(kl2_mod);
expected.rolls[1].drop(kl2_mod);
assert_eq!(rolled, expected);

§

Min(u8)

Replaces values of rolls lower than a minimum with the minimum.

§Examples

use tyche::dice::{modifier::{Condition, Modifier}, roller::{Iter as IterRoller, Roller}, Dice, Rolled};

// Build the 4d6min3 dice set and create a roller that has predetermined values for the dice rolls
let dice = Dice::builder().count(4).sides(6).min(3).build();
let premade_rolls = [3, 6, 1, 2];
let mut rng = IterRoller::new(premade_rolls);

// Roll the dice, but don't have it automatically apply its modifiers (passing `false` as the second `roll()` param).
let mut rolled = rng.roll(&dice, false)?;

// Explicitly create and apply a min3 modifier. This is usually not necessary since the dice has its own instance of
// it from the builder and will automatically apply it when passing `true` to `roll()`, but we do it this way here
// for demonstration purposes.
let min3_mod = Modifier::Min(3);
min3_mod.apply(&mut rolled, &mut rng)?;

// Upon being applied, the modifier will replace the values of all rolls less than 3 with 3, so 1 and 2 will
// both become 3.
// Final expected rolled dice set, after min3 modifier: 4d6min3[3, 6, 3 (m), 3 (m)]
let mut expected = Rolled::from_dice_and_rolls(&dice, premade_rolls);
expected.rolls[2].change(min3_mod, 3);
expected.rolls[3].change(min3_mod, 3);
assert_eq!(rolled, expected);

§

Max(u8)

Replaces values of rolls higher than a maximum with the maximum.

§Examples

use tyche::dice::{modifier::{Condition, Modifier}, roller::{Iter as IterRoller, Roller}, Dice, Rolled};

// Build the 4d6max3 dice set and create a roller that has predetermined values for the dice rolls
let dice = Dice::builder().count(4).sides(6).max(3).build();
let premade_rolls = [3, 6, 1, 2];
let mut rng = IterRoller::new(premade_rolls);

// Roll the dice, but don't have it automatically apply its modifiers (passing `false` as the second `roll()` param).
let mut rolled = rng.roll(&dice, false)?;

// Explicitly create and apply a max3 modifier. This is usually not necessary since the dice has its own instance of
// it from the builder and will automatically apply it when passing `true` to `roll()`, but we do it this way here
// for demonstration purposes.
let max3_mod = Modifier::Max(3);
max3_mod.apply(&mut rolled, &mut rng)?;

// Upon being applied, the modifier will replace the values of all rolls greater than 3 with 3, so 6 will become 3.
// Final expected rolled dice set, after max3 modifier: 4d6max3[3, 3 (m), 1, 2]
let mut expected = Rolled::from_dice_and_rolls(&dice, premade_rolls);
expected.rolls[1].change(max3_mod, 3);
assert_eq!(rolled, expected);