fdice

fdice is a library for creating callable roll functions from dice expressions. The library is packaged as an ESM module.

import parse from 'fdice';

let roll = parse("2d6");
let result = roll();

Dice notation

fdice has its own idea about dice pool modifiers (keep/drop, etc) but otherwise the syntax is fairly conventional.

Notation	Description
d20	Roll a 20-sided die
4d6	Roll a 6-sided die 4 times
4d6+2	Add a constant to the rolled value
3dF	Roll 3 Fudge/Fate dice (faces -1, 0, 1)
d%	Roll a percentile die (identical to d100)
4d6kh	Keep only the highest die
4d6kh3	Keep the 3 highest dice
4d6kl	Keep only the lowest die
4d6kl3	Keep the 3 lowest dice
4d6dh	Discard the highest die
4d6dh3	Discard the 3 highest dice
4d6dl	Discard the lowest die
4d6dl3	Discard the 3 lowest dice
1d20r	Roll a d20, re-roll on 1 (defaults to lowest face value)
1d20r20	Roll a d20, re-roll on 20
1d10t	Roll a d10, count 10s twice (defaults to highest face value)
1d10t3	Roll a d10, count 3s twice
7d10!	Exploding dice, 10s explode (defaults to highest face value)
7d10!1	Exploding dice, 1s explode

Modifiers that accept a face value argument will work with dF (face values {-1, 0, 1}) and d% (1..100).

Modifiers that accept a number-of-dice argument default to 1 die if it is not provided.

D&D advantage can be rolled using either 2d20kh or 2d20dl. Likewise disadvantage can be 2d20kl and 2d20dh.

Unreduced results

By default, the roll function returned by parse(expr) will reduce the entire expression to a single result value. The roll function itself takes an optional boolean parameter (default is true) to control this. Pass false to create a function which returns the individual rolls and constants in the expression as a nested array. Each dice pool in the expression results in an array of all of its rolls, and each constant resolves to itself. If a dice pool is negative then all of its rolls will be negative.

The total result can be obtained by flattening and summing the returned array.

// Dice pools produce an array:
parse('4d6')(false); // => [[3, 1, 3, 2]]
// Negative dice pools result in negative values,
parse('-4d6')(false); // => [[-3, -1, -3, -2]]
// Constants will appear as-is,
parse('d6 + 2')(false); // [[4], 2]
// Extra dice rolled by modifiers will appear:
parse('4d10!')(false); // => [[3, 10, 4, 6, 10, 7]]

Backlog

• Evaluation of equalities to a boolean output, i.e. 3d10 >= 17, 1d20 < 1d20 and so on.
• Multiple arguments for e.g. reroll and twice: 4d10t9,10 or possibly just use chaining 4d10t10t9 -- are these functionally equivalent? Would need to repeat the chain until no changes.
• Chaining of modifiers: 6d8!kl4kh2r5 or 3dFt-1dl2
• Think about / and * (order of evaluation problems -- no longer simply ltr?)
• Tree-shakable version using lodash-es (or just lodash if supported)