Skip to content
node.js package for rolling dice and adding modifiers. ex: 2d6+1
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin update to v1 Oct 30, 2014
example cleaning up some of the new validation code Oct 30, 2014
lib prepping 1.2.0 Sep 20, 2016
test update dependencies Sep 20, 2016
.gitignore Travis Dec 27, 2012
.npmignore added package.json, gitignore, npmignore Aug 21, 2011
LICENSE added license file (MIT) Nov 27, 2011
README.markdown prepping 1.2.0 Sep 20, 2016
package.json update dependencies Sep 20, 2016



Roll is a node.js package for rolling dice and adding modifiers (such as "2d6+1").


build status

How To Use (From Shell)

Installation (via npm)

$ npm install -g roll


$ roll 2d6+3
$ roll d20
$ roll d%

How To Use (As Library)

Installation (via npm)

$ npm install roll


Get an instance of the library:

var Roll = require('roll'),
  roll = new Roll();

Rolling a single die:

var oneDie = roll.roll('d6');
console.log(oneDie.result); //random number between 1 and 6 (inclusive)

Rolling multiple dice:

var twoTwenties = roll.roll('2d20');
console.log(twoTwenties.result); //random number between 2 and 40 (inclusive)

Rolling multiple sets of dice:

var bunchOfDice = roll.roll('2d20+1d12');
console.log(bunchOfDice.result); //random number between 3 and 52 (inclusive)

Rolling a percentage:

var chance = roll.roll('d%'); //same as '1d100', 'd100', or '1d%'
console.log(chance.result); //random number between 1 and 100 (inclusive)

Simple calculation (+, -, *, /):

var attack = roll.roll('2d6+2');
console.log(attack.result); //random number between 3 and 8 (inclusive)

Seeing what was rolled, rather than the sum:

var yahtzee = roll.roll('5d6');
console.log(yahtzee.rolled); //yahtzee.rolled will return something like [5, 2, 4, 6, 1] rather than the sum

var blessedSneaker = roll.roll('2d20b1+1d4+5');
console.log(blessedSneaker.rolled); // blessedSneaker.rolled will return an array containing an array for each component that is a roll of the dice, in the order in which they occurred, e.g. [[19,3],[1]]

Getting the highest two dice of the set:

var pickBestTwo = roll.roll('6d20b2'); //roll 6 dice and give me the 2 highest
console.log(pickBestTwo.calculations[1]); //pickBestTwo.calculations[0] is the same as .result, .calculations[1] is prior to the sum operation

Processing rolls without parsing a string:

var attack = roll.roll({
    quantity: 2,
    sides: 6,
    transformations: [ //can list n-number of pipeline operations to perform on the result
      'sum', //take the array of rolled dice and sum them together
      ['add', 2] //add 2 to the sum
console.log(attack.result); //random number between 3 and 8 (inclusive)

Using custom transformations:

var dropOnes = function(results){
  return results.filter(function (result) {
    return result !== 1;
var noOnes = roll.roll({
  quantity: 5,
  sides: 4,
  transformations: [
    dropOnes, // remove any 1s because we have teh lucky bootz

Using a custom seed:

var srand = require('srand'); // (npm install srand)

roll = new Roll(function () {
  return srand.random();


Validating user input:

var userInput = 'this isn\'t a valid roll',
  valid = roll.validate(userInput);

if (!valid) {
  console.error('"%s" is not a valid input string for node-roll!', userInput);


Inspired by Phillip Newton's Games::Dice.


MIT License


Troy Goode (

You can’t perform that action at this time.