Documentation

Please review the API documentation.

Install

Node:

npm install roll-parser

Then in the console or JS file:

const rollParser = require('roll-parser');

Browser:

<script src="https://unpkg.com/roll-parser/dist/roll-parser.js"></script>

Minified version:

<script src="https://unpkg.com/roll-parser/dist/roll-parser.min.js"></script>

Then access all functions from rollParser object.

Console:

$ roll-parser [options] [<rolls>]

Run roll-parser --help for more details.

Usage

const { parse, roll, parseAndRoll, Roll } = require('roll-parser');

// `parse()` function parses any notation and returns `Roll` or `WodRoll` object
//=> { dice: 6, count: 4, modifier: 1 }
const parsedRoll = parse('4d6+1');

// `Roll` or `WodRoll` can be stringified
//=> '4d6+1'
const rollNotation = parsedRoll.toString();

//=> { notation: '4d6+1', value: 16, rolls: [3, 1, 6, 5] }
const result1 = roll(parsedRoll);
//=> { notation: '2d20-3', value: 23, rolls: [11, 15] }
const result2 = roll(new Roll(20, 2, -3));
// Can also accept plain objects
//=> { notation: '2d10>7', value: 1, rolls: [4, 8] }
const result3 = roll({dice: 10, count: 2, success: 7});

// `parseAndRoll()` function can parse any notation and then roll the dice
// Any invalid arguments, except `null` or `undefined`, will be parsed as default `Roll`
//=> { notation: '3d10!>8f1', value: 2, rolls: [3, 10, 7, 9] }
const result4 = parseAndRoll('3d10!>8f1');

//=> '(3d10!>8f1) 2 [3,10,7,9]'
const resultNotation = result4.toString();

Specific parsers can be used.

Classic (D&D):

const {
  parseClassicRoll,
  rollClassic,
  parseAndRollClassic,
  Roll
} = require('roll-parser');

//=> { dice: 10, count: 1, modifier: 0 }
const parsedRoll = parseClassicRoll('d10');

//=> { notation: 'd10', value: 7, rolls: [7] }
const result1 = rollClassic(parsedRoll);

//=> { notation: '2d20', value: 26, rolls: [11, 15] }
const result2 = rollClassic(new Roll(20, 2));

//=> { notation: '4d10+1', value: 22, rolls: [4, 6, 2, 9] }
const result3 = rollClassic({ dice: 10, count: 4, modifier: 1 });

//=> { notation: '3d6', value: 15, rolls: [6, 6, 3] }
const result4 = parseAndRollClassic('3d6');

WoD (World of Darkness):

const {
  parseWodRoll,
  rollWod,
  parseAndRollWod,
  WodRoll
} = require('roll-parser');

//=> { dice: 10, count: 1, again: false, success: 6, fail: 0 }
const parsedRoll = parseWodRoll('d10>6');

// Returns notation, number of success rolls and list of all dice rolls
//=> { notation: 'd10', value: 1, rolls: [7] }
const result1 = rollWod(parsedRoll);

//=> { notation: '4d10>6f1', value: 1, rolls: [4, 10, 5, 2] }
const result2 = rollWod(new WodRoll(10, 4, false, 6, 1));

//=> { notation: '4d10!>8f1', value: 22, rolls: [1, 8, 5, 10, 10, 4] }
const result3 = rollWod({ dice: 10, count: 2, again: true, success: 8, fail: 1 });

//=> { notation: '4d10>7f4', value: 1, rolls: [6, 3, 8, 4] }
const result4 = parseAndRollWod('4d10>7f4');

Simple (D&D, space-separated):

const { parseSimpleRoll, parseAndRollSimple } = require('roll-parser');

//=> { dice: 10, count: 1, modifier: 0 }
const parsedRoll = parseSimpleRoll('10');

//=> { notation: '4d10-1', value: 23, rolls: [3, 6, 8, 7] }
const result = parseAndRollSimple('4 10 -1');

Random number generator can be used to roll the dice.

const { random } = require('roll-parser');

//=> 84 - d100-like roll
random(100);

//=> 7 - d10-like roll
random(10);

//=> [2, 5, 2, 6] - 4d6-like roll
[...Array(4)].map(() => random(6));

Even so the parse&roll functions uses checks to convert non-standard objects to Roll or WodRoll, explicit conversion can be used in some cases:

const { convert } = require('roll-parser');

//=> new Roll(undefined, 4, -3)
convert({ count: 4, modifier: -3 });

//=> new WodRoll(10, 6, true, undefined, 2)
convert({ dice: 10, count: 6, again: true, fail: 2 });

Releases

Please review the changelog.

Contributing

♥ roll-parser and want to get involved? Please, check the guide first.

License

MIT © Mikita Taukachou