# Roll.js, an Exact Dice-Simulation Library

Last updated:

Are you the sort of person who likes to play around with RPG or boardgame mechanics? Have you ever looked at some dice-based mechanic and wondered just what the outcome chances really were, but instead just gave up, rolled a couple of times, and relied on vibes? Have you tried using AnyDice.com but gave up when you saw you'd have to learn a funky DSL to do anything non-trivial? Do you know JavaScript?

If you answered yes to some of those questions, I've got a new library for you! Roll.js is an exact-results dice-simulation library - it doesn't do simulations of the "repeat 10k times and report the average", it tracks every outcome with its precise chance of occurring (up to floating-point accuracy, at least).

The README explains the library itself, and there's a playground tool that'll let you write code against it immediately and even share the results with others! There are several bits of example code in the README, and several more in the playground (click the ? in the upper-right).

For example, a simple "d20 with advantage" roll is:

`Roll.d20.advantage()`

Want to know average damage of a greatsword after Great Weapon Master is applied (re-roll 1s and 2s, a single time)?

`Roll.nd(2, 6).replace(x=> x <= 2, Roll.d6).sum();`

Wanna build a d5 out of a d6 by rerolling 6s until they stop coming up, as long as it takes?

```// "reroll()" calls map on its returned Roll
// results again, until things stabilize.
Roll.d6.reroll({
map: x=> (x == 6) ? Roll.d6 : x
});```

Wanna do something complicated, like figure out what the chances are of dying/stabilizing/reviving from a D&D death save?

```Roll.d20.reroll({
summarize(roll, oldSummary={}) {
return {
successes:(roll>=10?1:0) + (oldSummary.successes || 0),
failures:(roll<10?1:0) + (roll==1?1:0) + (oldSummary.failures || 0),
nat20: (roll==20),
toString() { return `\${this.successes}/\${this.failures}/\${this.nat20}`; },
}
},
map(summary) {
if(summary.nat20) return "revive";
if(summary.successes >= 3) return "stabilize";
if(summary.failures >= 3) return "die";
return Roll.d20;
}
})```

Point is, this library can do a lot of stuff, pretty easily, and you can use the JS you already know to do arbitrarily complicated stuff with it. I originally wrote it because I was fed up rewriting simulation code every time my brother and I were thinking about D&D homebrew, and in particular when I wrote some code to test out an alternate death-save mechanic it was getting too complicated; I figured I could just do it right, once, and (after several days of swearing at infinite-looping reroll code) I was correct!

At the moment the convenience functions (like `.advantage()`) are pretty biased towards D&D 5e usage, but I'm happy to add more for other dice systems. If you have any you'd like to see, let me know in a comment!

(a limited set of Markdown is supported)

“Have you ever looked at some dice-based mechanic and wondered just what the outcome chances really were, but instead just gave up, rolled a couple of times, and relied on vibes?”

Yes, I have. But mainly while playing Pass the Pigs, and unfortunately a JavaScript library is going to be able to help with that, no matter how much I want it to!