Dice Roller & Parser

This dice roller is a string parser that returns an object containing the component parts of the dice roll. It supports the full Roll20 Dice Specification. It uses a pegjs grammar to create a representation of the dice roll format. This can then be converted into a simple number value, or to a complex object used to display the full roll details.

Quickstart

Install the library using:

npm install dice-roller-parser

Once installed, simply load the library, either in the browser:

<script src="node_modules/dice-roller-parser/dist/index.js"></script>

Or in node:

import { DiceRoller } from "dice-roller-parser";

Then create a new instance of the DiceRoller class, and use it to perform some dice rolls.

const diceRoller = new DiceRoller();

//	Returns the total rolled value
const roll = diceRoller.rollValue("2d20kh1");
console.log(roll);

//	Returns an object representing the dice roll, use to display the component parts of the roll
const rollObject = diceRoller.roll("2d20kh1");
console.log(rollObject.value);

Usage

This library exposes two classes, a DiceRoller and a DiscordRollRenderer.

DiceRoller

The DiceRoller class manages parsing of a dice string and performing rolls based upon the result.

//	Creates a new instance of the DiceRoller class
const roller = new DiceRoller();

Constructor options

The default constructor uses Math.random and applies a maximum number of rolls per die of 1000. These can be specified using the following constructor overloads.

DiceRoller(GeneratorFunction)

You can specify a function to be used as the random number generator by the dice roller. This function should be of the type () => number and return a number between 0 and 1. By default, it uses the built-in Math.random method.

//	Default constructor using Math.random
const roller = new DiceRoller();

//	Uses a custom random generator that always returns 0.5
const roller = new DiceRoller(() => 0.5);

This can be read or modified using the randFunction property.

roller.randFunction = () => 0.5;

DiceRoller(GeneratorFunction, MaxRollsPerDie)

To prevent attempting to parse very large numbers of die rolls, a maximum number of rolls for a die can be specified. The default value is set to 1000.

//	Uses the default constructor with a limit of 100 rolls per die
const roller = new DiceRoller(null, 100);

//	Uses a custom random generator that always returns 0.5, and a limit of 10 rolls per die
const roller = new DiceRoller(() => 0.5, 10);

This can be read or modified using the maxRollCount property.

roller.maxRollCount = 75;

Class Usage

Once the DiceRoller class has been constructed, there are three options for performing a dice roll:

• Getting a roll result directly
• Generate an object to represent the dice roll
• Just parse the input and add your own rolling logic

Getting a direct roll result

The rollValue method takes a dice string input, parses it, performs a roll and returns the calculated number value result.

//	Rolls 2 d20 dice and keeps the value of the highest
const roll = roller.rollValue("2d20kh1");

//	Prints out the numeric value result
console.log(roll);

Generate an object representing the dice roll

The roll method takes a dice string input, parses it, performs a roll and then returns an object that represents the roll. Using the roll objects, you can build your own roll display functionality, rather than just outputting the final value.

//	Rolls 2 d20 dice and keeps the value of the highest
const roll = roller.roll("2d20kh1");

//	Print out the full roll breakdown
printDiceRoll(roll);
//	Prints out the numeric value result
console.log(`Final roll value: ${roll.Value}`);

See the roll result output in the output types section below for more details on the returned object.

Just parse the value

The parse method takes a dice string input, parses it and returns a representation of the parsed input. This can either be used to perform a dice roll or re-construct the original input. The rollParsed method takes this parsed result as an input, performs the roll and returns the same output as from the roll method.

//	Rolls 2 d20 dice and keeps the value of the highest
const parsedInput = roller.parse("2d20kh1");

//	Print out a re-constructed input string
printParsedInput(parsedInput);

//	Run the roller on the parsed object
const roll = roller.rollParsed(parsedInput);

//	Print out the full roll breakdown
printDiceRoll(roll);
//	Print out the numeric value result
console.log(`Final roll value: ${roll.Value}`);

See the parsed roll output in the output types section below for more details on the returned object.

DiscordRollRenderer

The DiscordRollRenderer class is an example renderer class that takes a rolled input represented by a RollBase object and renders it to a string in a markdown format, compatible with Discord.

//	Creates a new instance of the DiceRoller class
const renderer = new DiscordRollRenderer();

Class Usage

The DiscordRollRenderer exposes a single render method with a single parameter, the RollBase object to render, and returns the rendered string.

//	Rolls 2 d20 dice and keeps the value of the highest
const roll = roller.rollValue("2d20kh1");

//	Get the formatted string
const render = renderer.render(roll);
console.log(render);

Development

To develop this library, simply clone the repository, run an install:

npm install

Then do a build:

npm run build

This does four things:

# Clean any existing builds
npm run clean

# Build the dice grammer
npx pegjs src/diceroll.pegjs

# Run tslint against the project
tslint -c tslint.json --project tsconfig.json

# Then run webpack to build and package everything up nicely
webpack

To run the test suite, use:

npm run test

That's all there is to it!

Output Types

The following object types are output from the DiceRoller class, and are available as interfaces for typescript users.

Roll Result Output

The object returned by a roll result is made up of the following types.

RollBase

The base class for all die rolls, extended based upon the type property.

| Property | Type | Description | | -------- | ----------------------- | ------------------------------------------------------------------- | | success | boolean | Was the roll a success, for target number rolls. Example: 3d6 > 3 | | type | RollType | The type of roll that this object represents. | | valid | boolean | Is the roll still valid, and included in calculations. | | value | number | The rolled or calculated value of this roll. | | label | string | The display label for this roll. This property is optional. | | order | number | A property used to maintain ordering of dice rolls within groups. |

RollType

An enum of the valid types of roll. The possible values are:

• "number"
• "diceexpressionroll"
• "expressionroll"
• "mathfunction"
• "grouproll"
• "fate"
• "die"
• "roll"
• "fateroll"

GroupedRoll

An intermediate interface extended for groups of dice. This interface extends RollBase.

| Property | Type | Description | | -------- | ---------------------------------- | ----------------------------------------- | | dice | Array<RollBase> | The rolls included as part of this group. |

DiceExpressionRoll

A representation of a dice expression. This interface extends GroupedRoll.

Example

2d20 + 6d6

| Property | Type | Description | | -------- | -------------------------------------------------------------- | --------------------------------------------- | | type | "diceexpressionroll" | The type of roll that this object represents. | | ops | Array<DiceGroupMathOperation> | The operations to perform on the rolls. |

ExpressionRoll

A representation of a mathematic expression. This interface extends GroupedRoll.

Example

20 * 17

| Property | Type | Description | | -------- | -------------------------------------------- | --------------------------------------------- | | type | "expressionroll" | The type of roll that this object represents. | | ops | Array<MathOperation> | The operations to perform on the rolls. |

MathFunctionRoll

A representation of a mathematic function. This interface extends RollBase.

Example

floor(20 / 17)

| Property | Type | Description | | -------- | ------------------------------- | ------------------------------------------------- | | type | "expressionfunc" | The type of roll that this object represents. | | op | MathFunction | The operations to perform on the rolls. | | expr | RollBase | The expression that the function is applied upon. |

GroupRoll

A representation of a group of rolls

Example

{4d6,3d6}. This interface extends GroupedRoll.

| Property | Type | Description | | -------- | ------------- | --------------------------------------------- | | type | "grouproll" | The type of roll that this object represents. |

DiceRollResult

The rolled result of a group of dice. This interface extends RollBase.

Example

6d20

| Property | Type | Description | | -------- | ------------------------------- | --------------------------------------------- | | die | RollBase | The die this result represents. | | type | "die" | The type of roll that this object represents. | | rolls | DieRollBase[] | Each roll of the die. | | count | RollBase | The number of rolls of the die. | | matched | boolean | Whether this is a match result. |

DieRollBase

An intermediate interface extended for individual die rolls (see below). This interface extends RollBase.

| Property | Type | Description | | -------- | --------- | ----------------------------- | | roll | number | The rolled result of the die. | | matched | boolean | Whether this roll is a match. |

DieRoll

A roll on a regular die. This interface extends DieRollBase.

Example

d20

| Property | Type | Description | | -------- | ------------------------------- | -------------------------------------------------------------- | | die | number | The die number to be rolled. | | type | "roll" | The type of roll that this object represents. | | critical | CriticalType | If this role is a critical success or failure (for rendering). |

FateDieRoll

A roll on a fate die. This interface extends DieRollBase.

Example

dF

| Property | Type | Description | | -------- | ------------ | --------------------------------------------- | | type | "fateroll" | The type of roll that this object represents. |

Parsed Roll Output

The following interfaces are exposed by the library as a reresentation of the parsed input string. The response from the parse method is a RootType object and could be any of the interfaces that extend it.

ParsedObjectType

An enum of the valid types of roll. The possible values are:

• "number"
• "inline"
• "success"
• "failure"
• "crit"
• "critfail"
• "match"
• "keep"
• "drop"
• "group"
• "diceExpression"
• "sort"
• "explode"
• "compound"
• "penetrate"
• "reroll"
• "rerollOnce"
• "target"
• "die"
• "fate"
• "expression"
• "math"
• "mathfunction"

ParsedType

This is the base interface for all parsed types.

| Property | Type | Description | | -------- | -------- | ----------------------------------------------- | | type | string | The type of parsed item this object represents. |

RootType

This is the base interface for a subset of parsed types, only those that can be the root type. This object extends the ParsedType interface.

| Property | Type | Description | | -------- | --------- | ----------------------------------------------------------------- | | label? | string | The text label attached to this roll. This property is optional. | | root | boolean | A boolean flag to indicate if this is the root of the parse tree. |

NumberType

This object represents a single number in the input. This object extends the RootType interface.

| Property | Type | Description | | -------- | ---------- | ----------------------------------------------- | | type | "number" | The type of parsed item this object represents. | | value | number | The value of the number. |

InlineExpression

This object represents an inline dice expression within a string, wrapped in double square brackets. This object extends the RootType interface.

Example

I want to roll [[2d20]] dice

| Property | Type | Description | | -------- | --------------------------- | ---------------------------------------------------- | | type | "inline" | The type of parsed item this object represents. | | expr | Expression | The expression that was parsed as the inline string. |

AnyRoll

A combined type representing any valid roll. This is a combination of the following types:

• GroupedRoll
• FullRoll
• NumberType

ModGroupedRoll

This object represents a grouped roll with an optional modifier. This object extends the RootType interface.

Example

{4d6+3d8}kh1

| Property | Type | Description | | -------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | mods | Array<KeepDropModType,SuccessFailureModType> | The modifiers to be applied to the grouped roll. |

SuccessFailureCritModType

An object representing a success test modifier. This object extends the ParsedType interface. A "success" or "failure" modifier converts the result into a success type result which returns the number of rolls that meet the target. A "crit" or "critfail" modifier tests the roll for whether or not the roll should be displayed as a critical success or critical failure.

Example

Success: 3d6>3 Failure: 3d6f<3

| Property | Type | Description | | -------- | ------------------------------------------ | ------------------------------------------------- | | type | "success", "failure", "crit", "critfail" | The type of parsed item this object represents. | | mod | CompareOperation | The check type to use for the condition. | | expr | RollExpression | An expression representing the success condition. |

SuccessFailureModType

Equivalent to the SuccessFailureCritModType but only supporting "success" and "failure" modifiers. This object extends the SuccessFailureCritModType interface.

Example

Success: 3d6>3 Failure: 3d6f<3

| Property | Type | Description | | -------- | --------------------------------------- | ------------------------------------------------- | | type | "success", "failure" | The type of parsed item this object represents. | | mod | CompareOperation | The check type to use for the condition. | | expr | RollExpression | An expression representing the success condition. |

MatchModType

An object representing a match type modifier, used to modify the display of dice output in roll20. This object extends the ParsedType interface.

Example

2d6m

When used with the mt extension, will return the number of matches found.

Example

20d6mt

Additional arguments can be specified that increase the required number of matches or to add a constraint to matches.

Example

20d6mt3 counts matches of 3 items

Example

20d6m>3 Only counts matches where the rolled value is > 3

| Property | Type | Description | | -------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------ | | type | "match" | The type of parsed item this object represents. | | min | NumberType | The minimum number of matches to accept. This property defaults to 2 as a NumberType. | | count | boolean | Whether or not to count the matches. | | mod? | CompareOperation | The check type to use for the match condition, if specified. This field is optional. | | expr? | RollExpression | An expression representing the match condition, if specified. This field is optional. |

KeepDropModType

An object representing a keep or drop modifier, specifying a number of dice rolls to keep or drop, either the highest or lowest rolls. This object extends the ParsedType interface.

Example

Keep: 2d20kh1 Drop: 2d20dl1

| Property | Type | Description | | -------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | type | "keep", "drop" | The type of parsed item this object represents. | | highlow | HighLowType | Whether to keep/drop the highest or lowest roll. | | expr | RollExpression | An expression representing the number of rolls to keep/drop. This property defaults to 1 as a NumberType. Example: 2d6 |

GroupedRoll

This object represents a group of rolls combined, with optional modifiers. This object extends the ModGroupedRoll interface.

Example

{2d6,3d6}

| Property | Type | Description | | -------- | ---------------------------------------------- | ----------------------------------------------- | | type | "group" | The type of parsed item this object represents. | | rolls | Array<RollExpression> | The group of rolls included in this group. |

RollExpressionType

An object representing a roll expression including complex rolls and groups, only allows addition operations. This object extends the RootType interface.

Example

{2d6,3d6}kh1 + {3d6 + 2d6}kh2

| Property | Type | Description | | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | head | RollOrExpression | The initial roll or expression for the roll expression. | | type | "diceExpression" | The type of parsed item this object represents. | | ops | Array<MathType<RollOrExpression,DiceGroupMathOperation>> | The operations to apply to the initial roll or expression. |

RollExpression

A helper type combination of a complex roll expression, a roll, or a math expression. Represents the following types:

• RollExpressionType
• RollOrExpression

RollOrExpression

A helper type combination of a roll, or a math expression. Represents the following types:

• FullRoll
• Expression

FullRoll

An object representing a roll including the dice roll, and any modifiers. This object extends the DiceRoll interface.

Example

2d6kh1

| Property | Type | Description | | -------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | mods? | Array<ReRollMod,KeepDropModType> | Any modifiers attached to the roll. This property is optional. | | targets? | Array<SuccessFailureCritModType> | Any success or failure targets for the roll. This property is optional. | | match? | MatchModTyp | Any match modifiers for the roll. This property is optional. | | sort? | SortRollType | Any sort operations to apply to the roll. This property is optional. |

SortRollType

A sort operation to apply to a roll. This object extends the ParsedType interface.

Example

10d6sa

| Property | Type | Description | | -------- | --------- | ----------------------------------------------- | | type | "sort" | The type of parsed item this object represents. | | asc | boolean | Whether to sort ascending or descending. |

ReRollMod

An object representing a re-roll operation to apply to a roll. Can be one of the following types:

• "explode": re-rolls any dice that meet the target, continuing if the new roll matches
• "compound": re-rolls any dice that meet the target, continuing if the new roll matches and adding the results into a single roll
• "penetrate": re-rolls any dice that meet the target subtracting 1 from the new value, continuing if the new roll matches
• "reroll": re-rolls a die as long as it meets the target, keeping the final roll
• "rerollOnce": re-rolls a die once if it meets the target, keeping the new roll

Example

2d6!

| Property | Type | Description | | -------- | ------------------------------------------------------------ | ------------------------------------------------------ | | type | "explode", "compound", "penetrate", "reroll", "rerollOnce" | The type of parsed item this object represents. | | target | TargetMod | The target modifier to compare the roll value against. |

TargetMod

An object represting a target modifier to apply to a roll. This object extends the ParsedType interface.

| Property | Type | Description | | -------- | --------------------------------------- | ------------------------------------------------------ | | type | "target" | The type of parsed item this object represents. | | mod | CompareOperation | The check type to use for the condition. | | value | RollExpr | An expression representing the target condition value. |

DiceRoll

The representation of a die roll. This object extends the RootType interface.

Example

2d6

| Property | Type | Description | | -------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------- | | die | RollExpr,FateExpr | The die value to roll against, can be a fate die, a number or a complex roll expression. | | count | RollExpr | The number of time to roll this die. | | type | "die" | The type of parsed item this object represents. |

FateExpr

The representation of a fate die roll. This object extends the ParsedType interface.

Example

2dF

| Property | Type | Description | | -------- | -------- | ----------------------------------------------- | | type | "fate" | The type of parsed item this object represents. |

RollExpr

A helper type combination of a number or value that is not an expression. Represents the following types:

• MathExpression
• NumberType

Expression

A helper type combination of expression types. Represents the following types:

• InlineExpression
• MathExpression

MathExpression

A math type expression between two or more dice rolls. This object extends the RootType interface.

Example

2d6 + 3d6 * 4d6

| Property | Type | Description | | -------- | ----------------------------------------------------------- | ----------------------------------------------- | | head | AnyRoll | The initial roll to perform operations against. | | type | "expression" | The type of parsed item this object represents. | | ops | Array<MathType<AnyRoll>> | The operations to apply to the initial roll. |

MathType

An object representating an roll math operation to be applied and the value to apply it to. This object extends the ParsedType interface. The interface for this object takes a templated type TailType which specifies the type of the second value used in the operation. There is a second templated type OpValues which specifies the type of operations that can be used. This defaults to Array<MathOperation>`.

Example

+ 3d6 (as part of 2d6 + 3d6)

| Property | Type | Description | | -------- | ---------- | ----------------------------------------------- | | type | "math" | The type of parsed item this object represents. | | op | OpValues | The math operation to perform. | | tail | TailType | The second value to use in the operation. |

MathFunctionExpression

An object representing a math function to be applied and the expression to apply it to. This object extends the RootType interface.

Example

floor(3d6 / 2d4)

| Property | Type | Description | | -------- | ------------------------------- | ----------------------------------------------- | | type | "mathfunction" | The type of parsed item this object represents. | | op | MathFunction | The function to be applied. | | expr | AnyRoll | The expression to apply the function on. |

Helper Types

The following are support types used by the above interfaces.

DiceGroupMathOperation

A helper type representing the valid operations for a math operation on a group of dice.

"+" | "-"

MathOperation

A helper type representing the valid operations for a math operation.

"+" | "-" | "*" | "/" | "%" | "**"

MathFunction

A helper type representing the valid operations for a math operation.

"floor" | "ceil" | "round" | "abs"

CriticalType

A helper type used when marking a roll as a critical success or failure.

"success" | "failure" | null

CompareOperation

A helper type for the available operations for a comparison point.

">" | "<" | "="

HighLowType

A helper type used to determine which rolls to keep or drop.

"h" | "l" | null