Dice Rolling

The GoRogue.DiceNotation interface provides functions capable of parsing and rolling dice via full Dice Notation syntax.

Code Examples

Code examples in this section show only code in the Main function. The code provided assumes that the following "using" statements are at the top of the code file:

using GoRogue.DiceNotation;
using GoRogue.Random;

Basic Dice Rolling

Basic dice rolls are easy to perform with the Dice.Roll function. This function takes the dice notation expression to parse and (optionally) a random number generator (see Random Number Generation for details):

// Rolls 1 6-sided die.  When no RNG is specified, SingletonRandom.DefaultRNG is used.
int result = Dice.Roll("1d6");
// Also rolls 1 6-sided die; we can omit the number of dice to roll if it should be 1.
int result2 = Dice.Roll("d6");

// Custom RNG; see Random Number Generation docs for usage details
IRandom customRNG = new DotNetRandom(); 
// Rolls 2d6 and adds 3 to the sum of the result.  We also specify a custom RNG to use for rolling:
int result3 = Dice.Roll("2d6+3", customRNG);

// We can also do multiplication and division in the expression

// Rolls 2d6, multiplies the sum by 3, adds 2, and returns the result
int result4 = Dice.Roll("2d6x3+2);
// Rolls 2d6, divides the sum by 3, subtracts 2, and returns the result 
int result5 = Dice.Roll("2d6/3-2);

// GoRogue also supports "keep" expressions
int result5 = Dice.Roll("3d6k2"); // Rolls 3 d6, adds only the highest 2 together, and returns the result

See general information on Dice Notation syntax for details.

Expressions Used Multiple Times

In the case where a single or similar dice expressions are used multiple times, the Dice.Parse function may prove useful. It can generate a DiceExpression object that can later be used to roll the expression one or more times:

DiceExpression expr = Dice.Parse("2d6+2");

// Note the return type of the Roll function is not int, but DiceResult.  This type is discussed below.
DiceResult result1 = Dice.Roll(); // Rolls 2d6+2 with the default RNG
IRandom rng = new DotNetRandom();
DiceResult result2 = Dice.Roll(rng); // Rolls 2d6+2, using the RNG specified.

Dice Expression

The DiceExpression class returned by the Parse function "caches" the result of parsing the dice expression it is given, thus speeding up the process of rolling it. The actual parsing, as opposed to the roll itself, can be somewhat computationally expensive, and as a result caching the parsing result by using DiceExpression can be valuable in the event that you intend to roll a dice expression or similar dice expression multiple times.

Manual Creation of a Dice Expression

While one typically retrieves a DiceExpression instance via the Dice.Parse function, it is possible to manually create them from a list of terms. Typically this might be necessary if creating a custom parser, or creating a dice expression not consistent with standard dice notation (see Advanced Usage below).

Modifying a DiceExpression After Creation

While a DiceExpression instance cannot be directly modified in terms of the expression it rolls, DiceExpression does provide various functions that can be used to generate a new DiceExpression that is effectively a copy of the original but with additional expressions added. These can be used to prevent full re-parsing of an expression when a dice expression is similar but not the same across rolls.

Adding a Constant Term

The Constant function can be used to add a constant term:

DiceExpression expr1 = Dice.Parse("2d6x2");
DiceExpression expr2 = expr1.Constant(5); // expr2 rolls "2d6x2+5"

Adding Dice Terms

We can use the Dice function to add dice terms to an existing expression:

DiceExpression expr1 = Dice.Parse("2d6+2");

// Adds 2d4 to the original expression; expr2 rolls (2d6+2)+(2d4)
DiceExpression expr2 = expr1.Dice(2, 4);
// Adds 3*2d4 to the original expression; expr2 now rolls (2d6+2)+(3*2d4)
expr2 = expr1.Dice(2, 4, 3);
// Adds 1*4d4k3, eg. simply 4d4k3, to the original expression; expr2 now rolls (2d6+2)+(4d4k3)
expr2 = expr1.Dice(2, 4, 1, 3) 

In the event that we are only adding a term with only a single die, we can use the Die function as a shortcut:

DiceExpression expr1 = Dice.Parse("2d6+2");

// Adds 1d4 to the original expression; expr2 rolls (2d6+2)+(1d4)
expr2 = expr1.Die(4);
// Adds 2*1d4 to the original expression; expr2 now rolls (2d6+2)+(3*1d4)
expr2 = expr1.Die(4, 3);

Rolling a DiceExpression

In addition to the standard Roll function, DiceExpression also provides MaxRoll and MinRoll functions that allow retrieval of the maximum possible and minimum possible values that could be rolled, respectively:

DiceExpression expr = Dice.Parse("2d6+2");

DiceResult normalResult = expr.Roll(); // Gets the result
(TBC)