m-chrzan.xyz
aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.md76
1 files changed, 76 insertions, 0 deletions
diff --git a/README.md b/README.md
index d187bcd..82c428a 100644
--- a/README.md
+++ b/README.md
@@ -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)`).