dice-expression-evaluator
v0.1.2
Published
Parses and evaluates dice expressions using simulated dice rolls
Downloads
2,452
Readme
dice-expression-evaluator
dice-expession-evaluator
is used to parse dice expressions and to evaluate them using simulated dice rolls.
Installation
$ npm install --save dice-expression-evaluator
Dice expressions
Dice expressions are used to specify calculations that are based on a series of dice rolls. For example, this is a dice expression that represents a single, standard 6-sided die:
1d6
This can be shortened to:
d6
What if we rolled five of those dice at once and added up?
5d6
To roll two other 10-sided dice and subtract the sum of the two from above?
5d6 - 2d10
What if we also wanted to add 15 to ensure that the final result does not go below zero?
5d6 - 2d10 + 15
If the number of sides is 100, it can be replaced with a % sign (percentage, out of 100, got it?)
5d100 == 5d%
Dice expressions can also be specified as:
- Any string denoting a whole number (don't start with 0 or minus sign please) is a dice expression.
- Any string of form
x?(d|D)y
where x and y are both whole numbers (see warning above) is a dice expression. ? means x is optional and (d|D) means either d or D works. - Any string of form
x?(d|D)%
where x and y are both whole numbers is a dice expression. - Any string of form DiceExpression + DiceExpression or form DiceExpression - DiceExpression is a dice expression.
- Leading or trailing spaces don't matter and neither do spaces between terms and operators. Just like in math.
API
var DiceExpression = require('dice-expression-evaluator');
var d = new DiceExpression('2d5 + 4d2 + 10');
d()
: evaluates the dice expression by simulating dice rolls and returns the resulting rolld.min()
: returns the minimum possible roll for the dice expressiond.max()
: returns the maximum possible roll for the dice expressiond.roll()
: evaluates the dice expression by simulating dice rolls and returns the resulting roll as well as the value for each term within the dice expression and the individual dice rolls within that term.
Examples
d() // 20
d() // 18
d() // 23
d.min() // 16
d.max() // 28
d.roll() // { roll: 23, diceSums: [7, 6, 10], diceRaw: [[3, 4], [1, 2, 2, 1], [10]] }
Future plans
We may add support for
- Coefficients for terms so that we can multiply dice rolls by a constant value
- Other arithmetic operators
- Nested expressions using parantheses
License
MIT © Dan Kang