diff options
| -rw-r--r-- | README.md | 76 |
1 files changed, 76 insertions, 0 deletions
@@ -1,3 +1,79 @@ # dicebag A dice expression parser and roller. + +## Installation + + npm install --save dicebag + +## Usage + + const { parse, pool, roll } = require('dicebag') + +The API consists of three functions: + +* `parse(diceExpression)` parses an expression into an object understood by the + other two functions. +* `pool(dice)` rolls each die in the `dice` object, returning an array of + results. +* `roll(dice)` rolls the dice and returns their sum. + +### Examples + + const d6 = parse('1d6') + roll(d6) # 4 + roll(d6) # 5 + pool(d6) # [ 2 ] + const dice = parse('2d6 + 1d8') + roll(dice) # 10 + pool(dice) # [ 1, 4, 7 ] + +## Dice expressions + +### Basics + +Simple expressions involving standard dice notation as used in most roleplaying +games are supported. You can do things like: + +* `XdY`: rolls `X` `Y`-sided dice (`1d6` is a single 6-sided die, `2d4` is two + 4-sided dice). +* `dice +/- constant`: rolls the dice, adds/subtracts the constant. +* `dice +/- moreDice`: sums/takes the difference of the results of rolling + `dice` and `moreDice`. + +### Full syntax and semantics + +**Note:** this is still an early version. Syntax and semantics will be expanded +in future versions. *Backwards incompatible changes are possible.* + +The parser recognizes the following grammar (all whitespace between symbols is +ignored): + + Die ::= <an integer> + | '(' Die ')' + | Die 'd' Die + | Die '+' Die + | Die '-' Die + | '-' Die + +Semantics are defined in terms of the `pool` function. + +* `N`, where an `N` is an integer, is a die that always rolls a single value + equal to `N`. `pool` returns an array containing just `N`. +* `DdE`, where `D` and `E` are dice expressions, is a die that rolls a number of + dice equal to the result of rolling `D`, where each die has a number of sides + equal to the result of rolling `E`. `pool` returns an array of `roll(D)` + numbers, each between 1 and `roll(E)`. *Note:* if `D` or `E` evaluates to a + negative number, the behavior is undefined. +* `D+E` appends the dice pool generated by `E` to the dice pool generated by + `D`. +* `-D` returns the opposites of values generated by `D`. +* `D-E` is equivalent to `D+(-E)`. + +Additionally: + +* The binary arithmetic operations (`+`, `-`) are left associative. +* The die operation `d` is right associative (`1d2d3` is equivalent to + 1d(2d3)`, use explicit parentheses if you need `(1d2)d3`) +* `d` binds stronger than the binary arithmetic operations (`1d6+1d4` is + equivalent to `(1d6) + (1d4)`). |