A high-performance dice probability engine for D&D 5e DPR calculations. Powers dprcalc.com.
npm install @yipe/dice

!TypeScript
!Size
!Dice
!Last Commit
!Dependencies



A TypeScript library for D&D 5e damage-per-round (DPR) calculations, designed for players, Dungeon Masters, and developers who want to analyze combat mathematically.
This library powers dprcalc.com and provides a precise, composable way to model dice rolls, attacks, and outcomes with probability mass functions (PMFs) โ not just averages. This allows for rich charting and statistics with full outcome attribution. It provides two main entry points: a fluent typescript interface or a dice expression string.
``ts
import { parse } from "@yipe/dice";
const attack = parse("(d20 + 8 AC 16) * (1d8 + 4) crit (2d8 + 4)");
console.log("DPR:", attack.mean());
// or
const attack = d20.plus(8).ac(16).onHit(d8.plus(4));
console.log("DPR:", attack.mean());
`
- D&D 5e Focused: Designed around 5e rules (2014 and 2024).
- Probability Mass Functions (PMF): Precise modeling of dice rolls and outcomes, not just averages.
- Complex Attack Expressions: Supports crit ranges, advantage/disadvantage, conditional damage, rerolls, minimum damage, and more.
- Composable API: Build dice expressions, run queries, and analyze results in just a few lines.
- TypeScript First: Full type safety and developer experience.
`bash`Install with npm or yarn
npm install @yipe/diceor
yarn add @yipe/dice
`ts
import { parse, DiceQuery } from "@yipe/dice";
const query = d20.plus(8).ac(16).onHit(d4.plus(4)).toQuery();
console.log("Hit chance:", query.probAtLeastOne(["hit", "crit"]));
console.log("Crit chance:", query.probAtLeastOne(["crit"]));
console.log("DPR:", query.mean());
`
Output:
``
Hit chance: 0.65
Crit chance: 0.05
DPR: 4.35
- Node.js: >= 18.17
- Yarn: 4.9.4 (specified in packageManager)
`bashClone the repository
git clone https://github.com/yipe/dice.git
cd dice
$3
| Command | Purpose |
|---------|---------|
|
yarn build | Compile TypeScript to JavaScript (outputs to dist/) |
| yarn test | Run test suite once |
| yarn test:watch | Run tests in watch mode |
| yarn typecheck | Type-check without emitting files |
| yarn lint | Run ESLint |
| yarn example | Run example scripts |$3
`
src/
โโโ builder/ # Fluent API for building dice expressions
โ โโโ factory.ts # Factory functions (d20, d6, roll, etc.)
โ โโโ roll.ts # RollBuilder - core builder class
โ โโโ ac.ts # ACBuilder - attack roll builder
โ โโโ attack.ts # AttackBuilder - attack with damage
โ โโโ save.ts # SaveBuilder - saving throw builder
โ โโโ dc.ts # DCBuilder - difficulty check builder
โ โโโ ast.ts # AST generation and PMF conversion
โ โโโ nodes.ts # AST node type definitions
โโโ parser/ # String-based dice expression parser
โ โโโ parser.ts # Main parser implementation
โ โโโ dice.ts # Dice class (legacy parser representation)
โโโ pmf/ # Probability Mass Function core
โ โโโ pmf.ts # PMF class - core data structure
โ โโโ query.ts # DiceQuery - analysis interface
โ โโโ mixture.ts # Mixture operations
โโโ common/ # Shared utilities
โโโ types.ts # Type definitions
โโโ lru-cache.ts # LRU cache implementation
`๐ Architecture Overview
The library provides two parallel entry points for creating dice expressions:
$3
Parses text expressions like
"(d20 + 8 AC 16) * (1d8 + 4) crit (2d8 + 4)":`
String Expression
โ
โโ parse() โโโโโโโโโโโโโโโ
โ โ
โ โผ
โ parseExpression()
โ โ
โ โโ parseArgument() โโโบ Dice objects
โ โ
โ โโ parseOperation() โโโบ Dice operations
โ โ
โ โผ
โ Dice.toPMF() โโโบ PMF
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโ
`$3
Type-safe builder pattern:
`
RollBuilder (d20, d6, roll(), etc.)
โ
โโ .plus() โโโบ RollBuilder
โโ .ac() โโโโโบ ACBuilder
โ โ
โ โโ .onHit() โโโบ AttackBuilder
โ โ
โ โโ .toQuery() โโโบ DiceQuery
โ โโ .pmf โโโโโโโโโโบ PMF
โ
โโ .toPMF() โโโบ PMF
`$3
`
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ User Input Layer โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ String Parser โ Fluent Builder โ
โ parse("...") โ d20.plus(8).ac(16) โ
โโโโโโโโโโโโโโฌโโโโโโโโโโโโโดโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โผ โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Builder Layer โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ RollBuilder โโโบ ACBuilder โโโบ AttackBuilder โ
โ โ โ โ โ
โ โ โ โ โ
โ โโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโ โ
โ โ โ
โ โผ โ
โ astFromRollConfigs() โ
โ โ โ
โ โผ โ
โ ExpressionNode (AST) โ
โโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ PMF Generation โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ pmfFromRollBuilder() โ
โ โ โ
โ โโ d20RollPMF() โโโบ PMF (for d20 rolls) โ
โ โโ diePMF() โโโโโโโบ PMF (for regular dice) โ
โ โโ combinePMFs() โโบ PMF (convolve multiple PMFs) โ
โโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Query & Analysis โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ DiceQuery โ
โ โ โ
โ โโ .mean() โโโโโโโโโโโโโบ Expected damage โ
โ โโ .variance() โโโโโโโโโบ Damage variance โ
โ โโ .probAtLeastOne() โโโบ Hit/crit probabilities โ
โ โโ .toChartSeries() โโโโโบ Chart data โ
โ โโ .combined โโโโโโโโโโโโบ Final PMF โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
`$3
The
PMF class is the core mathematical representation:`
PMF
โโโ map: Map
โ โโโ Bin
โ โโโ p: number (probability)
โ โโโ count: {...} (outcome counts: hit, crit, miss)
โ โโโ attr: {...} (damage attribution)
โโโ epsilon: number (probability threshold)
โโโ normalized: boolean (whether PMF sums to 1.0)
โโโ identifier: string (cache key / debug name)
`$3
Here's how a simple attack flows through the system:
`
1. User creates: d20.plus(5).ac(15).onHit(d6.plus(2))2. Builder chain:
RollBuilder(d20)
โ plus(5) โ RollBuilder(d20 + 5)
โ ac(15) โ ACBuilder(d20 + 5 AC 15)
โ onHit(...) โ AttackBuilder
3. AST generation:
RollConfig[] โ ExpressionNode
- DieNode (d20)
- ConstantNode (+5)
- D20RollNode (AC check)
- ConditionalNode (on hit)
4. PMF generation:
AST โ PMF operations
- d20RollPMF(rollType, rerollOne) โ PMF
- Conditional application โ PMF.branch()
- Damage PMF โ PMF
- Combine โ PMF (final result)
5. Query creation:
AttackBuilder.toQuery() โ DiceQuery
- singles: [PMF]
- combined: PMF (convolved)
6. Analysis:
DiceQuery.mean() โ 3.20 DPR
`๐ฆ Core Concepts
| Concept | Description |
| ---------- | ---------------------------------------------------------------------------- |
| PMF | Probability Mass Function. The core mathematical representation of outcomes. |
| Query | Runs calculations and scenarios over one or more PMFs. |
| Parser | Parses text-based dice expressions like
(d20 + 8 AC 16) * (1d4 + 4). |
| Builder| Fluent TypeScript API for building dice expressions. |
| AST | Abstract Syntax Tree representing dice operations. |๐ง Usage Examples
$3
`ts
import { parse, DiceQuery } from "@yipe/dice";const query = d20.plus(8).ac(16).onHit(d4.plus(4)).toQuery();
console.log("Hit chance:", query.probAtLeastOne(["hit", "crit"]));
console.log("Crit chance:", query.probAtLeastOne(["crit"]));
console.log("DPR:", query.mean());
`$3
`ts
import { parse } from "@yipe/dice";const pmf = parse("(d20 + 8 AC 16) * (1d8 + 4) crit (2d8 + 4)");
const query = new DiceQuery(pmf);
console.log("DPR:", query.mean());
`$3
Conditional damage ("once-per-turn damage riders") like Sneak Attack can be modeled easily:
`ts
import { DiceQuery, PMF, roll } from "@yipe/dice";function sneakAttack() {
const attackPMF = d20.plus(8).ac(16).onHit(d4.plus(4)).pmf;
const sneakAttack = roll(3, d6);
const attacks = new DiceQuery([attackPMF, attackPMF]);
const [pHit, pCrit] = attacks.firstSuccessSplit(onAnyHit, onCritOnly);
const sneakPMF = PMF.exclusive([
[sneakAttack.pmf, pHit],
[sneakAttack.doubleDice().pmf, pCrit],
]);
return new DiceQuery([attackPMF, attackPMF, sneakPMF]);
}
console.log("DPR with once-per-turn sneak attack: ", sneakAttack().mean());
`$3
`ts
import { parse, DiceQuery } from "@yipe/dice";const query = parse("(d20 + 8 AC 16) * (1d4 + 4) crit (2d4 + 4)").toQuery();
console.table(query.toChartSeries());
`Output:
`
โโโโโโโโโโโฌโโโโโฌโโโโโโโโโโโ
โ (index) โ x โ y โ
โโโโโโโโโโโผโโโโโผโโโโโโโโโโโค
โ 0 โ 0 โ 0.35 โ
โ 1 โ 5 โ 0.15 โ
โ 2 โ 6 โ 0.153125 โ
โ 3 โ 7 โ 0.15625 โ
โ 4 โ 8 โ 0.159375 โ
โ 5 โ 9 โ 0.0125 โ
โ 6 โ 10 โ 0.009375 โ
โ 7 โ 11 โ 0.00625 โ
โ 8 โ 12 โ 0.003125 โ
โโโโโโโโโโโดโโโโโดโโโโโโโโโโโ
`๐งช Running Examples
This repository includes example scripts:
`bash
yarn example basic
yarn example stats
yarn example sneakattack
yarn example misc
`Here is the basic example output:
`
% yarn example basicโโโโโโโโโโโโโโ
โ Summary โ
โโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Expression: (d20 + 5 AC 15) * (1d6+2) crit (2d6 + 2) โ
โ Success Chance: 0.55 โ
โ Expected DPR: 3.20 โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โโโโโโโโโโโโโโ
โ PMF () โ
โโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 0: โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 45.00% โ
โ 3: โโโโโโโโโโโโโโ 8.33% โ
โ 4: โโโโโโโโโโโโโโ 8.47% โ
โ 5: โโโโโโโโโโโโโโ 8.61% โ
โ 6: โโโโโโโโโโโโโโโ 8.75% โ
โ 7: โโโโโโโโโโโโโโโ 8.89% โ
โ 8: โโโโโโโโโโโโโโโ 9.03% โ
โ 9: โโ 0.83% โ
โ 10: โโ 0.69% โ
โ 11: โ 0.56% โ
โ 12: โ 0.42% โ
โ 13: โ 0.28% โ
โ 14: โ 0.14% โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โโโโโโโโโโโโโโโโโโโโ
โ CDF (): P(X โค x) โ
โโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 0: โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 45.00% โ
โ 1: โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 45.00% โ
โ 2: โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 45.00% โ
โ 3: โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 53.33% โ
โ 4: โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 61.81% โ
โ 5: โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 70.42% โ
โ 6: โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 79.17% โ
โ 7: โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 88.06% โ
โ 8: โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 97.08% โ
โ 9: โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 97.92% โ
โ 10: โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 98.61% โ
โ 11: โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 99.17% โ
โ 12: โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 99.58% โ
โ 13: โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 99.86% โ
โ 14: โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 100.00% โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โโโโโโโโโโโโโโโโโโโโ
โ Outcome Table () โ
โโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ DAMAGE โ PERCENT โ Crit % โ Hit % โ Miss % โ
โโโโโโโโโโผโโโโโโโโโโผโโโโโโโโโผโโโโโโโโโผโโโโโโโโโโค
โ 0 โ 45.000% โ 0.000% โ 0.000% โ 45.000% โ
โ 3 โ 8.333% โ 0.000% โ 8.333% โ 0.000% โ
โ 4 โ 8.472% โ 0.139% โ 8.333% โ 0.000% โ
โ 5 โ 8.611% โ 0.278% โ 8.333% โ 0.000% โ
โ 6 โ 8.750% โ 0.417% โ 8.333% โ 0.000% โ
โ 7 โ 8.889% โ 0.556% โ 8.333% โ 0.000% โ
โ 8 โ 9.028% โ 0.694% โ 8.333% โ 0.000% โ
โ 9 โ 0.833% โ 0.833% โ 0.000% โ 0.000% โ
โ 10 โ 0.694% โ 0.694% โ 0.000% โ 0.000% โ
โ 11 โ 0.556% โ 0.556% โ 0.000% โ 0.000% โ
โ 12 โ 0.417% โ 0.417% โ 0.000% โ 0.000% โ
โ 13 โ 0.278% โ 0.278% โ 0.000% โ 0.000% โ
โ 14 โ 0.139% โ 0.139% โ 0.000% โ 0.000% โ
โโโโโโโโโโดโโโโโโโโโโดโโโโโโโโโดโโโโโโโโโดโโโโโโโโโโ
`This enables rich statistics like "how much damage comes from crits vs hits".
๐งฑ Roadmap
- [ ] Create a web playground with live examples
- [ ] Consider creating higher-level APIs:
Turn, Attack, DamageRider
- [ ] Add more comprehensive 5e rule examples
- [ ] Performance improvements for DPR-only calculations
- [ ] Multi-round and sustained vs nova simulations
- [ ] Deeper integration with dprcalc.com
- [ ] Blog posts and documentation
- [ ] Grammar refinements and new YACC parsing๐ฌ Discuss
Join our Discord to discuss this library and more!
๐ค Contributing
Clone the repo and install dependencies:
`bash
git clone https://github.com/yipe/dice.git
cd dice
yarn install
`Run tests:
`bash
yarn test
`Run examples:
`bash
yarn example
``2025 MIT ยฉ Michael Margolis
Wizards of the Coast, Dungeons & Dragons, and their logos are trademarks of Wizards of the Coast LLC in the United States and other countries.
ยฉ 2025 Wizards. All Rights Reserved.
Portions of this code are inspired by dice.clockworkmod.com by Koushik Dutta (2013), licensed under the Apache License 2.0.
Initial TypeScript port expertly created by loginName1.