morgul / rpgdice

A generic RPG dice roller syntax and library.

RPGDice

This project is an opinionated dice syntax and roller library designed to be used for any dice-based RPG system. Its main goal is to use a straightforward, easy to use grammar that has enough flexibility to allow players to easily codify their dice rolls. One of its central features, the ability to use variables, exists to facilitate a 'write once' philosophy of dice rolls.

Dice are Hard

The single largest complaint I ever hear about a given RPG system is that the dice are "too complicated", or "I can never remember how to roll that", or "I keep forgetting my bonuses." This is why RPGDice exists: computers are amazing at calculations; humans aren't. That's why we let the computer do the hard work of keeping track of everything, and the user just gets to see the results of what they told it to roll.

Opinionated

There is a semi-formal dice notation floating around. I personally find its syntax clunky, difficult to use, and nearly impossible to extend. Instead, I've created a syntax that is, in essence, mathematical operations, plus functions, variables, and XdY syntax. I feel my version is easy enough to learn for veterans and newbies alike, while leveraging some basic programing concepts, like the principal of least surprise.

Usage

Getting RPGDice

Our recommended way is via npm:

$ npm install --save rpgdicejs

Or with yarn:

$ yarn add rpgdicejs

Now, if you want to use this in a browser, any of the major bundlers should be able to handle this module just fine. It should be noted that as this is still a CJS module, you may be required to do some work, but it has no dependencies, and works in both node and the browser, so bundling it should be easy.

We used to provide a bundled version but have removed it in an interest of maintainability. In the future the code base will be converted to typescript, and at that time we'll provide UMD, CJS and ESM module versions for easy consumption.

Syntax Summary

d20 + floor(level / 2) + floor(('strength.score' - 10) / 2) + proficiency + 'Weapon Enhancement' + [Misc.Attack.Bonus]

As you can see, the syntax is very nearly a super-simplified version of javascript. It supports standard order of operations, XdY for rolls, function calls, and variables. (This particular roll is the formula for a D&D 4e attack, with the added pathology of showing all the various ways of escaping variables.)

When you make a roll, you will pass in a scope object, which RPGDice will use to look up all variables and functions. By default, we provide several mathematical functions, such as min(), max(), floor(), ceil(), round(). Additionally, we provide some common RPG rules: explode(), dropLowest(), dropHighest(), reroll().

If you set a variable on the scope to a function, but reference it without parenthesis, RPGDice will call it, passing in no arguments. Ex: 3d8 + strMod, where strMod was defined as:

function strMod()
{
    return Math.floor((scope.strength - 10) / 2);
} // end strMod

This gives you a lot of power in how you define your scope. You can additionally extend the functionality to support any rule set your heart desires, without needing explicit support in the syntax. For example, let's say you wanted to play with loaded dice. There's no special syntax support for that, but you can add it yourself:

function rollLoaded(sides)
{
    var roll = Math.floor(Math.random() * sides) + 1;

    // We make ourselves 3 times as likely to roll max, and impossible to roll the minimum.
    // Simply returning the max might look suspicious. :-p
    if(roll < sides/3)
    {
        return sides;
    } // end if

    return roll;
} // end strMod

Now, you can roll your loaded dice like such:

3(rollLoaded(6)) + 4

This expression calls rollLoaded(6) three times, and then adds 4. It's the equivalent to 3d4, except the dice rolling logic has been replaced by your loaded dice rules. Functions get the full results object, which includes the parse tree for each expression they get as an argument, which means functions can be incredibly powerful.

If you would like to dive further into the syntax, please check out our Syntax Documentation.

API

The API for rolling dice is super simple. There are exactly 2 functions, rpgdice.parse() and rpgdice.eval(). Each take a dice string to parse, and only differ in what they output; parse() simply returns you the tokenized roll as a parse tree, while eval() will return you a populated version of the parse tree. (The final result is in the value property of the root node.) Additionally, roll() can take a parse tree (such as the results of parse()) not just a string. This allows for a small optimization by only needing to tokenize the expression once, and calling eval() multiple times.

Here's a few examples:

// Roll a simple equation
var results = rpgDice.roll('3d6 + 4');

// Render the results as a string
console.log('Results:', results.render());

// Print the final result:
console.log('Total:', results.value);

//----------------------------------------------------------------

// Evaluate an expression
var eval = rpgDice.parse('3(4d10 - 2)')

// Maybe do something with the evaluated expresion

// Now, get the results for this roll
var results = rpgDice.roll(eval);

Expression API

The results of rpgdice.parse() and rpgdice.eval() are Expression objects. These represent the parse tree of the expression. While for a general use case you won't need the power they provide, they do expose a few useful functions:

• render() - Renders a parse tree to a string. If the parse tree has been evaluated, it includes the intermediate results.
• eval() - Evaluates the parse tree from this node down. (This is the same as passing the Expression object to rpgdice.eval().

For more details on the API, please check out our API Documentation.