dice-lang

Roll dice using a streamlined and easy to learn language in a modern web app.

Use Online

Try and learn dice-lang using our online demo.

The sources for the demo can be found here:
https://github.com/Mvrlex/dice-lang-website

Installation

You can install the package using npm or yarn:

npm install @character-sheets/dice-lang

Use it in your project like this:

import { roll } from '@character-sheets/dice-lang';
const result = roll('2d6 + 1');
console.log(result.result);

Features

• Rolling dice of any size
• Math
• Success Comparison
• Filter (highest, lowest, keep, drop, and range of values)
• Counting
• Values References

For examples and explanations check out our documentation.

Usage

You can use the roll function to evaluate dice expressions, which can include arithmetic operations, die rolls, and various other operations like keep, drop, and count.

The function will return an expression object that contains the result in a tree-like structure, with the root node being the result of the entire expression.

roll("2d6 + 1").result // => 9
roll("d10 / 2").result // => 3
roll("d6 + @strength", { context: { strength: 2 } }).result // => 8
roll("2d6 keep highest").result // => 6

Syntax

Use d to denote a die roll, followed by the number of sides.

d6

If you want to roll multiple dice, provide a number before the d:

2d6

You can also use arithmetic operations like addition, subtraction, multiplication, and division. Division is always integer division, meaning it will round down to the nearest whole number.

2d6 + 1

(2 + 3) * 4 / 3

Filtering Results

Keep

You can filter the results of a die roll using the keep or drop keywords.

2d6 keep highest

This will keep the highest result of the rolled dice. You can also specify a number of results to keep or drop:

2d6 keep 2 highest

This will keep the two highest results of the rolled dice. You can also use conditions to filter the results:

2d6 keep >3

This will keep all results that are greater than 3.

All of these filters can be combined in a single expression:

2d6 keep 2 lowest >3

The order is important: you first specify the amount of results to keep or drop, then the selector (e.g. highest or lowest), and then the filter condition (e.g. >3). Any of these parts can be omitted, but the order must be preserved.

Drop

Drop has the same syntax as keep, but it will remove the results that match the condition instead of keeping them.

2d6 drop 2 lowest

Combined Filters

You can combine keep and drop filters in a single expression:

2d6 keep highest keep lowest

Filters will always be applied to all dice rolls, meaning that the keep lowest will keep the lowest result in addition to the highest result from the previous filter.

Counting

You can count the number of results that match a certain condition using the count keyword.

2d6 count >3

Alternatively, you can use the count keyword after a filtered expression to count the number of dice that were kept.

2d6 keep >3 count

References

You can reference variables in the expression using the @ symbol. This allows you to use variables from the context in your expressions, such as attributes from a character sheet in a role-playing game.

For example, if you have a variable strength in your context, you can use it like this:

@strength + 2d6

Currently, references are very limited, and you can only reference numbers. References can also not be nested.

Problems

If you have any issues with dice-lang please feel free to report them on our issue tracker.