public class Dice
extends java.lang.Object
implements java.io.Serializable
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."
Constructor and Description |
---|
Dice()
Creates a new dice roller that uses a random RNG seed for an RNG that it owns.
|
Dice(IRNG rng)
Creates a new dice roller that uses the given IRNG, which can be seeded before it's given here.
|
Dice(long seed)
Creates a new dice roller that will use its own RNG, seeded with the given seed.
|
Dice(java.lang.String seed)
Creates a new dice roller that will use its own RNG, seeded with the given seed.
|
Modifier and Type | Method and Description |
---|---|
int |
bestOf(int n,
int dice,
java.lang.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.
|
IntVLA |
parseRollRule(java.lang.CharSequence rollCode)
Parses the given dice roll notation in
rollCode and returns the data needed to perform that roll, as an
IntVLA called a roll rule here. |
IntVLA |
parseRollRuleInto(IntVLA into,
java.lang.CharSequence rollCode)
Parses the given dice roll notation in
rollCode and puts out the data needed to perform that roll into
into , where into is usually an empty IntVLA, and is called a roll rule here. |
int |
roll(java.lang.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.
|
int |
runRollRule(IntVLA rollRule)
Attempts to run the given roll rule stored in the given IntVLA, returning the result as if rolling the dice as it
describes.
|
void |
setRandom(IRNG rng)
Sets the random number generator to be used.
|
int |
worstOf(int n,
int dice,
java.lang.String group)
Find the worst n totals from the provided number of dice rolled according
to the roll group string.
|
public Dice()
public Dice(IRNG rng)
public Dice(long seed)
seed
- a long to use as a seed for a new RNG (can also be an int, short, or byte)public Dice(java.lang.String seed)
seed
- a String to use as a seed for a new RNGpublic void setRandom(IRNG rng)
rng
- the source of randomnesspublic int bestOf(int n, int dice, java.lang.String group)
n
- number of roll groups to totaldice
- number of roll groups to rollgroup
- string encoded roll groupingpublic int worstOf(int n, int dice, java.lang.String group)
n
- number of roll groups to totaldice
- number of roll groups to rollgroup
- string encoded roll groupingpublic int rollDice(int n, int sides)
n
- number of dice to sumsides
- positive integer; number of sides on the rolled dicepublic int rollExplodingDice(int n, int sides)
n
- number of dice to sumsides
- number of sides on the rollDice; should be greater than 1public IntVLA independentRolls(int n, int sides)
n
- number of dice usedsides
- positive integer; number of sides on each diepublic int roll(java.lang.String rollCode)
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.
42
: simple absolute string; can start with -
to make it negative3d6
: sum of 3 6-sided diced6
: synonym for 1d6
3>4d6
: best 3 of 4 6-sided dice3:4d6
: gets a random value between 3 and a roll of 4d6
; this syntax has changed2<5d6
: worst 2 of 5 6-sided dice10: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
+4
: add 4 to the value-3
: subtract 3 from the value*100
: multiply value by 100/8
: integer-divide value by 8rollCode
- dice string using the above notationpublic IntVLA parseRollRule(java.lang.CharSequence rollCode)
rollCode
and returns the data needed to perform that roll, as an
IntVLA called a roll rule here. You can roll such a roll rule with runRollRule(IntVLA)
, any number of
times, and get different results on different rolls even with the same rule. This saves time spent and garbage
produced parsing the roll code for each roll with roll(String)
.rollCode
- a String or other CharSequence holding dice roll notation, like "3d8+5" (see roll(String)
)into
, after the roll rule has been appendedpublic IntVLA parseRollRuleInto(IntVLA into, java.lang.CharSequence rollCode)
rollCode
and puts out the data needed to perform that roll into
into
, where into
is usually an empty IntVLA, and is called a roll rule here. You can roll such a
roll rule with runRollRule(IntVLA)
, any number of times, and get different results on different rolls
even with the same rule. This saves time spent and garbage produced parsing the roll code for each roll with
roll(String)
.into
- a usually-empty IntVLA that will have a roll rule appended to its contentsrollCode
- a String or other CharSequence holding dice roll notation, like "3d8+5" (see roll(String)
)into
, after the roll rule has been appendedpublic int runRollRule(IntVLA rollRule)
parseRollRule(CharSequence)
or parseRollRuleInto(IntVLA, CharSequence)
to get such a roll rule.rollRule
- an IntVLA as returned by parseRollRule(CharSequence)
or parseRollRuleInto(IntVLA, CharSequence)
Copyright © Eben Howard 2012–2022. All rights reserved.