A TypeScript library for parsing dice rolling expressions, most commonly used in tabletop RPGs.
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
npm install dice-typescript
At its simplest, the dice roller is very simple to use. Take the following example:
;;;console.logresult; // Outputs a random number between 1 and 20.
roll(expression: string) method returns a
DiceResult object that, aside from the total of the roll, also includes the number of passes/fails that were rolled (if pass and fail conditions were specified). Finally, it also provides an expanded model of the results for each die roll, for any required breakdown.
Dice class has several methods that can be overridden in order to modify the construction of the lexer/parser/interpreter/generator:
// Used to control the breaking down of a string into tokens: (4d10) = LPAREN, NUMBER, DICE, NUMBER, RPAREN, etc.protected createLexerinput: string | CharacterStream: Lexer;// Used to control the construction of a stream of tokens into an abstract syntax tree.protected createParserlexer: Lexer: Parser;// Used to actually process an abstract syntax tree, perform the appropriate dice rolls and figure out successes/failures.protected createInterpreter: DiceInterpreter;// Used to control how an expression is 'rendered', that is, how an abstract syntax tree is converted back into a string.protected createGenerator: DiceGenerator;
Overriding any of the above methods will allow you to control the exact instance that is created for each part of the interpreting process.
In addition to the
sqrt functions, the Dice library also supports adding definitions for custom functions, such as the example below:
;customFunctions =;;console.logresult; // Outputs a random number between 1 and 20, divided by 2, then rounded down.
By default, the Dice library uses random-js to generate random numbers. In some instances, this may not be suitable, so this can be enhanced by a custom implementation of the
RandomProvider interface as in the example below:
;;console.logresult; // Outputs 4.
Limiting the number of rolls or sides
Limit the number of rolls or dice sides by providing a configuration object to the
;;console.logresult1.errors; // Outputs ["Invalid number of rolls: 50. Maximum allowed: 20."];console.logresult2.errors; // Outputs ["Invalid number of dice sides: 500. Maximum allowed: 500."]
Dice Expression Syntax
The dice rolling syntax is based on the system used by Roll20, a detailed explanation of which can be found on the Roll20 Wiki.
In addition to the above syntax rules, some slightly more complicated variations are available. For example, you can roll a variable number of dice using an expression similar to the following:
As per the Roll20 syntax, you can use conditional operators, such as in
4d20>10, but in this library, the semantics of those operators is slightly different. In the Roll20 engine,
>10 actually means
>=10, but in this library, you would need to actually use the
>= operator. I feel needing to use the correct mathematical operators makes for a more intuitive library.
Sometimes it is necessary to roll complex groups of dice that aren't supported by the basic syntax. For example, rolling a saving throw at disadvantage for 10 creatures. For this, you can use the group repeater modifier, which works like this:
The above will roll 10 disadvantaged saving throws, reporting successes for those that break DC14.
Fractional Dice Rolls
Using the allowed syntax, it is possible to request a fractional number of dice to be rolled. Take the following example:
(2 / 5)d6
In this instance, the number of dice to be rolled will be rounded to the nearest integer (2.5 gets rounded up to 3).
This will first roll
4d4 dice, and use the outcome of that to determine how many
d20 dice will be rolled.
Installing the dependencies is done using a standard
Running the Tests
npm run test
Building the project
npm run build
We use SemVer for versioning. For the versions available, see the tags on this repository.
- Tom Wolfe - Initial work - trwolfe13
See also the list of contributors who participated in this project.
This project is licensed under the MIT License - see the LICENSE file for details