This skill should be used when implementing dice rolling, creating Roll formulas, sending rolls to chat with toMessage, preparing getRollData, creating custom dice types, or handling roll modifiers like advantage/disadvantage. Covers Roll class, evaluation, and common patterns.
Implements Foundry VTT dice rolling using the Roll class, including formula creation, evaluation, and sending results to chat. Used when creating attack/damage rolls, ability checks, or any rollable mechanics with variable substitution.
/plugin marketplace add ImproperSubset/hh-agentics/plugin install fvtt-dev@hh-agenticsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Domain: Foundry VTT Module/System Development Status: Production-Ready Last Updated: 2026-01-04
Foundry VTT provides a powerful dice rolling system built around the Roll class. Understanding this system is essential for implementing game mechanics.
const roll = new Roll(formula, data, options);
formula: Dice expression string (e.g., "2d20kh + @prof")data: Object for @ variable substitutionoptions: Optional configurationconst roll = new Roll("2d20kh + @prof + @strMod", {
prof: 2,
strMod: 4
});
// 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
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.
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
});
// Only for maximize/minimize (deterministic)
roll.evaluateSync({ strict: true });
// With strict: false, non-deterministic = 0
roll.evaluateSync({ strict: false });
Sends a roll to chat as a ChatMessage.
await roll.toMessage();
await roll.toMessage({
speaker: ChatMessage.getSpeaker({ actor: this.actor }),
flavor: "Attack Roll",
user: game.user.id
}, {
rollMode: game.settings.get("core", "rollMode")
});
| Mode | Command | Visibility |
|---|---|---|
| Public | /roll | Everyone |
| GM | /gmroll | Roller + GM |
| Blind | /blindroll | GM only |
| Self | /selfroll | Roller only |
Always respect user's roll mode:
rollMode: game.settings.get("core", "rollMode")
Prepares data context for roll formulas.
getRollData() {
// Always return a COPY
const data = foundry.utils.deepClone(this.system);
// Add shortcuts
data.lvl = data.details.level;
// Flatten ability mods for easy access
for (const [key, ability] of Object.entries(data.abilities)) {
data[key] = ability.mod; // @str, @dex, etc.
}
return data;
}
Merge item and actor data:
getRollData() {
const data = foundry.utils.deepClone(this.system);
if (!this.actor) return data;
// Merge actor's roll data
return foundry.utils.mergeObject(
this.actor.getRollData(),
data
);
}
// In console with token selected:
console.log(canvas.tokens.controlled[0].actor.getRollData());
"4d6kh3" // Keep 3 highest (ability scores)
"4d6kl3" // Keep 3 lowest
"4d6dh1" // Drop 1 highest
"4d6dl1" // Drop 1 lowest
"2d20kh" // Advantage (keep highest)
"2d20kl" // Disadvantage (keep lowest)
"5d10x" // Explode on max (10)
"5d10x8" // Explode on 8+
"2d10xo" // Explode once per die
"1d20r1" // Reroll 1s (once)
"1d20r<3" // Reroll below 3 (once)
"1d20rr<3" // Recursive reroll while < 3
"10d6cs>4" // Count successes > 4
"10d6cf<2" // Count failures < 2
"1d20min10" // Minimum result 10
"1d20max15" // Maximum result 15
async rollAttack() {
const rollData = this.actor.getRollData();
const parts = ["1d20"];
if (this.system.proficient) parts.push("@prof");
if (this.system.ability) parts.push(`@${this.system.ability}.mod`);
if (this.system.attackBonus) parts.push(this.system.attackBonus);
const formula = parts.join(" + ");
const roll = new Roll(formula, rollData);
await roll.evaluate();
return roll.toMessage({
speaker: ChatMessage.getSpeaker({ actor: this.actor }),
flavor: `${this.name} - Attack Roll`,
rollMode: game.settings.get("core", "rollMode")
});
}
async rollDamage(critical = false) {
const rollData = this.actor.getRollData();
let formula = this.system.damage.formula;
// Add ability mod
if (this.system.damage.ability) {
formula += ` + @${this.system.damage.ability}.mod`;
}
// Double dice on critical
if (critical) {
formula = formula.replace(/(\d+)d(\d+)/g, (m, num, faces) => {
return `${num * 2}d${faces}`;
});
}
const roll = new Roll(formula, rollData);
await roll.evaluate();
return roll.toMessage({
speaker: ChatMessage.getSpeaker({ actor: this.actor }),
flavor: `${this.name} - ${critical ? "Critical " : ""}Damage`,
rollMode: game.settings.get("core", "rollMode")
});
}
async rollAbility(abilityId, { advantage = false, disadvantage = false } = {}) {
const rollData = this.actor.getRollData();
let dieFormula = "1d20";
if (advantage && !disadvantage) dieFormula = "2d20kh";
if (disadvantage && !advantage) dieFormula = "2d20kl";
const formula = `${dieFormula} + @abilities.${abilityId}.mod`;
const roll = new Roll(formula, rollData);
await roll.evaluate();
return roll.toMessage({
speaker: ChatMessage.getSpeaker({ actor: this.actor }),
flavor: `${CONFIG.abilities[abilityId]} Check`,
rollMode: game.settings.get("core", "rollMode")
});
}
// In activateListeners
html.on("click", ".rollable", this._onRoll.bind(this));
async _onRoll(event) {
event.preventDefault();
const element = event.currentTarget;
const { roll: formula, label } = element.dataset;
if (!formula) return;
const roll = new Roll(formula, this.actor.getRollData());
await roll.evaluate();
return roll.toMessage({
speaker: ChatMessage.getSpeaker({ actor: this.actor }),
flavor: label || "Roll",
rollMode: game.settings.get("core", "rollMode")
});
}
Template:
<a class="rollable" data-roll="1d20 + @str" data-label="Strength Check">
<i class="fas fa-dice-d20"></i> Roll
</a>
export class StressDie extends foundry.dice.terms.Die {
static DENOMINATION = "s"; // Use as "1ds"
async evaluate(options = {}) {
await super.evaluate(options);
// Custom logic: explode on 6, panic on 1
for (const result of this.results) {
if (result.result === 6) result.exploded = true;
if (result.result === 1) result.panic = true;
}
return this;
}
}
export class CustomRoll extends Roll {
static CHAT_TEMPLATE = "systems/mysystem/templates/roll.hbs";
get successes() {
return this.dice.reduce((sum, die) => {
return sum + die.results.filter(r => r.success).length;
}, 0);
}
}
Hooks.once("init", () => {
CONFIG.Dice.terms.s = StressDie;
CONFIG.Dice.rolls.push(CustomRoll);
});
Critical: Register custom rolls or they won't reconstruct from chat messages.
// WRONG - total is undefined
const roll = new Roll("1d20");
console.log(roll.total); // undefined!
// CORRECT
const roll = new Roll("1d20");
await roll.evaluate();
console.log(roll.total); // 15
// WRONG - always public
roll.toMessage();
// CORRECT - respects user setting
roll.toMessage({}, {
rollMode: game.settings.get("core", "rollMode")
});
// WRONG - modifies document data
getRollData() {
return this.system; // Direct reference!
}
// CORRECT - return a copy
getRollData() {
return foundry.utils.deepClone(this.system);
}
// WRONG - data captured once
const rollData = this.actor.getRollData();
// ...actor updates...
new Roll("1d20 + @prof", rollData); // Stale!
// CORRECT - get fresh data
new Roll("1d20 + @prof", this.actor.getRollData());
// UNSAFE
const roll = new Roll(userInput);
// SAFER - validate first
if (!Roll.validate(userInput)) {
ui.notifications.error("Invalid roll formula");
return;
}
const roll = new Roll(userInput, rollData);
// WRONG - rolls break on reload
class MyRoll extends Roll {}
// CORRECT - register with CONFIG
class MyRoll extends Roll {}
CONFIG.Dice.rolls.push(MyRoll);
// PROBLEMATIC - hooks can't reliably await
Hooks.on("preCreateItem", async (doc, data) => {
const roll = new Roll("1d20");
await roll.evaluate(); // May fail!
});
// BETTER - use onCreate
Hooks.on("createItem", async (doc, options, userId) => {
if (userId !== game.user.id) return;
const roll = new Roll("1d20");
await roll.evaluate(); // Safe
});
await roll.evaluate() before accessing roll.totalgetRollData() returning a deep clonerollMode: game.settings.get("core", "rollMode") to toMessageChatMessage.getSpeaker({ actor }) for proper speakerRoll.validate()Last Updated: 2026-01-04 Status: Production-Ready Maintainer: ImproperSubset
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.