Package squidpony.squidmath

Class Dice

java.lang.Object
squidpony.squidmath.Dice
All Implemented Interfaces:
Serializable
public class Dice
extends Object
implements Serializable
Class for emulating various traditional RPG-style dice rolls. Supports rolling multiple virtual dice of arbitrary size, summing all, the highest n, or the lowest n dice, treating dice as "exploding" as in some tabletop games (where the max result is rolled again and added), getting value from inside a range, and applying simple arithmetic modifiers to the result (like adding a number). Typically you'll want to use the roll(String) method if you have a String like "2d8+6", or the various other methods if you have int variables for things like "number of dice to roll" and "sides on each die."
Based on code from the Blacken library.
Author:
yam655, Eben Howard - http://squidpony.com - howard@squidpony.com, Tommy Ettinger
See Also:
Serialized Form

  • Constructor Summary

    Constructors 
    Constructor Description
    Dice()
    Creates a new dice roller that uses a random RNG seed for an RNG that it owns.
    Dice​(long seed)
    Creates a new dice roller that will use its own RNG, seeded with the given seed.
    Dice​(String seed)
    Creates a new dice roller that will use its own RNG, seeded with the given seed.
    Dice​(IRNG rng)
    Creates a new dice roller that uses the given IRNG, which can be seeded before it's given here.

  • Method Summary

    Modifier and Type Method Description
    int bestOf​(int n, int dice, String group)
    Find the best n totals from the provided number of dice rolled according to the roll group string.
    IntVLA independentRolls​(int n, int sides)
    Get a list of the independent results of n rolls of dice with the given number of sides.
    int roll​(String rollCode)
    Evaluate the String rollCode as dice roll notation and roll to get a random result of that dice roll.
    int rollDice​(int n, int sides)
    Emulate a dice roll and return the sum.
    int rollExplodingDice​(int n, int sides)
    Emulate an exploding dice roll and return the sum.
    void setRandom​(IRNG rng)
    Sets the random number generator to be used.
    int worstOf​(int n, int dice, String group)
    Find the worst n totals from the provided number of dice rolled according to the roll group string.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Dice

      public Dice()
      Creates a new dice roller that uses a random RNG seed for an RNG that it owns.

    • Dice

      public Dice​(IRNG rng)
      Creates a new dice roller that uses the given IRNG, which can be seeded before it's given here. The IRNG will be shared, not copied, so requesting a random number from the same IRNG in another place may change the value of the next die roll this makes, and dice rolls this makes will change the state of the shared IRNG.
      Parameters:
      rng - an IRNG, such as RNG or GWTRNG; will be shared (dice rolls will change the IRNG state outside here)

    • Dice

      public Dice​(long seed)
      Creates a new dice roller that will use its own RNG, seeded with the given seed.
      Parameters:
      seed - a long to use as a seed for a new RNG (can also be an int, short, or byte)

    • Dice

      public Dice​(String seed)
      Creates a new dice roller that will use its own RNG, seeded with the given seed.
      Parameters:
      seed - a String to use as a seed for a new RNG

  • Method Details

    • setRandom

      public void setRandom​(IRNG rng)
      Sets the random number generator to be used. This method does not need to be called before using the methods of this class.
      Parameters:
      rng - the source of randomness

    • bestOf

      public int bestOf​(int n, int dice, String group)
      Find the best n totals from the provided number of dice rolled according to the roll group string.
      Parameters:
      n - number of roll groups to total
      dice - number of roll groups to roll
      group - string encoded roll grouping
      Returns:
      the sum

    • worstOf

      public int worstOf​(int n, int dice, String group)
      Find the worst n totals from the provided number of dice rolled according to the roll group string.
      Parameters:
      n - number of roll groups to total
      dice - number of roll groups to roll
      group - string encoded roll grouping
      Returns:
      the sum

    • rollDice

      public int rollDice​(int n, int sides)
      Emulate a dice roll and return the sum.
      Parameters:
      n - number of dice to sum
      sides - positive integer; number of sides on the rolled dice
      Returns:
      sum of rolled dice

    • rollExplodingDice

      public int rollExplodingDice​(int n, int sides)
      Emulate an exploding dice roll and return the sum.
      Parameters:
      n - number of dice to sum
      sides - number of sides on the rollDice; should be greater than 1
      Returns:
      sum of rollDice

    • independentRolls

      public IntVLA independentRolls​(int n, int sides)
      Get a list of the independent results of n rolls of dice with the given number of sides.
      Parameters:
      n - number of dice used
      sides - positive integer; number of sides on each die
      Returns:
      list of results

    • roll

      public int roll​(String rollCode)
      Evaluate the String rollCode as dice roll notation and roll to get a random result of that dice roll. This is the main way of using the Dice class. This effectively allows rolling one or more dice and performing certain operations on the dice and their result. One of the more frequent uses is rolling some amount of dice and summing their values, which can be done with e.g. "4d10" to roll four ten-sided dice and add up their results. You can choose to sum only some of the dice, either the "n highest" or "n lowest" values in a group, with "3>4d6" to sum the three greatest-value dice in four rolls of six-sided dice, or "2<3d8" to sum the two lowest-value dice in three rolls of eight-sided dice. You can apply modifiers to these results, such as "1d20+7" to roll one twenty-sided die and add 7 to its result. These modifiers can be other dice, such as "1d10-1d6", and while multiplication and division are supported, order of operations isn't, so it just rolls dice from left to right and applies operators it find along the way. You can get a random value in an inclusive range with "50:100", which is equivalent to "1d51+49" but is easier to read and understand. You can treat dice as "exploding," where any dice that get the maximum result are rolled again and added to the total along with the previous maximum result. As an example, if two exploding six-sided dice are rolled, and their results are 3 and 6, then because 6 is the maximum value it is rolled again and added to the earlier rolls; if the additional roll is a 5, then the sum is 3 + 6 + 5 (for a total of 14), but if the additional roll was a 6, then it would be rolled again and added again, potentially many times if 6 is rolled continually. Some players may be familiar with this game mechanic from various tabletop games, but many potential players might not be, so it should be explained if you show the kinds of dice being rolled to players. The syntax used for exploding dice replaced the "d" in "3d6" for normal dice with "!", making "3!6" for exploding dice. Inclusive ranges are not supported with best-of and worst-of notation, but exploding dice are. If using a range, the upper bound can be random, decided by dice rolls such as with "1:6d6" (which rolls six 6-sided dice and uses that as the upper bound of the range) or by other ranges such as with "10:100:200", which gets a random number between 100 and 200, then returns a random number between 10 and that. While it is technically allowed to end a dice string with an operator, the partial operator will be ignored. If you start a dice string with an operator, its left-hand-side will always be 0. If you have two operators in a row, only the last will be used, unless one is '-' and can be treated as part of a negative number (this allows "1d20 * -3" to work). Whitespace is allowed between most parts of a dice string.
      The following notation is supported:
      • 42 : simple absolute string; can start with - to make it negative
      • 3d6 : sum of 3 6-sided dice
      • d6 : synonym for 1d6
      • 3>4d6 : best 3 of 4 6-sided dice
      • 3:4d6 : gets a random value between 3 and a roll of 4d6; this syntax has changed
      • 2<5d6 : worst 2 of 5 6-sided dice
      • 10:20 : simple random range (inclusive between 10 and 20)
      • :20 : synonym for 0:20
      • 3!6 : sum of 3 "exploding" 6-sided dice; see above for the semantics of "exploding" dice
      • !6 : synonym for 1!6
      The following types of operators are supported:
      • +4 : add 4 to the value
      • -3 : subtract 3 from the value
      • *100 : multiply value by 100
      • /8 : divide value by 8
      Parameters:
      rollCode - dice string using the above notation
      Returns:
      a random number that is possible with the given dice string