fvtt-dice-rolls

# Foundry VTT Dice Rolls

**Domain:** Foundry VTT Module/System Development
**Status:** Production-Ready
**Last Updated:** 2026-01-04

## Overview

Foundry VTT provides a powerful dice rolling system built around the `Roll` class. Understanding this system is essential for implementing game mechanics.

### When to Use This Skill

- Creating roll formulas with variable substitution
- Implementing attack rolls, damage rolls, saving throws
- Sending rolls to chat with proper speaker/flavor
- Preparing actor/item roll data with getRollData()
- Creating custom dice types for specific game systems
- Using roll modifiers (keep, drop, explode, reroll)

## Roll Class Basics

### Constructor

```javascript
const roll = new Roll(formula, data, options);
```

- `formula`: Dice expression string (e.g., "2d20kh + @prof")
- `data`: Object for @ variable substitution
- `options`: Optional configuration

```javascript
const roll = new Roll("2d20kh + @prof + @strMod", {
  prof: 2,
  strMod: 4
});
```

### Formula Syntax

```javascript
// Basic dice
"1d20"          // Roll one d20
"4d6"           // Roll four d6

// Variables with @ syntax
"1d20 + @abilities.str.mod"
"1d20 + @prof"

// Nested paths
"@classes.barbarian.levels"
"@abilities.dex.mod"

// Parenthetical (dynamic dice count)
"(@level)d6"    // Roll [level] d6s

// Dice pools
"{4d6kh3, 4d6kh3, 4d6kh3}"  // Multiple separate rolls
```

## Roll Evaluation

### Async evaluate() - REQUIRED

```javascript
const roll = new Roll("1d20 + 5");
await roll.evaluate();

console.log(roll.result);  // "15 + 5"
console.log(roll.total);   // 20
```

**Critical:** `roll.total` is undefined until evaluated.

### Evaluation Options

```javascript
await roll.evaluate({
  maximize: true,    // All dice roll max value
  minimize: true,    // All dice roll min value
  allowStrings: true // Don't error on string terms
});
```

### Sync Evaluation (Deterministic Only)

```javascript
// Only for maximize/minimize (deterministic)
roll.evaluateSync({ st