Roll

Roll

This class provides an interface and API for conducting dice rolls. The basic structure for a dice roll is a string formula and an object of data against which to parse it.

Constructor

new Roll(formula, data)

Source:
See:
Example
// Attack with advantage!
let r = new Roll("2d20kh + @prof + @strMod", {prof: 2, strMod: 4});

// The parsed components of the roll formula
console.log(r.parts);    // [Die, +, 2, +, 4]

// Execute the roll
r.roll();

// The resulting equation after it was rolled
console.log(r.result);   // 16 + 2 + 4

// The total resulting from the roll
console.log(r.total);    // 22
Parameters:
Name Type Description
formula String

The string formula to parse
data Object

The data object against which to parse attributes within the formula

Members

_formula :string

Source:

The original "raw" formula before any substitutions or evaluation

Type:
  • string

_result

Source:

Cache the rolled total to avoid re-evaluating it multiple times

_total

Source:

Cache the evaluated total to avoid re-evaluating it

data :Object

Source:

The original provided data

Type:
  • Object

dice :Array.<Die>

Source:

Get an Array of any Die objects which were rolled as part of the evaluation of this roll

Type:

formula :string

Source:

The processed formula resulting from substitution and evaluation

Type:
  • string

parts :Array

Source:

An array of evaluate Roll parts

Type:

result

Source:

The resulting arithmetic expression after rolls have been evaluated

rgx

Source:

Regular expression patterns

total

Source:

Express the total result of the roll and cache the result to avoid re-evaluating

Methods

(static) cleanFormula(formula) → {*}

Source:

Clean a dice roll formula, returning the formatted string with proper spacing

Parameters:
Name Type Description
formula
Returns:
Type
*

(static) fromData(data) → {Roll}

Source:

Recreate a Roll instance using a provided JSON string

Parameters:
Name Type Description
data Object

Unpacked data representing the Roll
Returns:

A revived Roll instance

Type
Roll

(static) fromJSON(json) → {Roll}

Source:

Recreate a Roll instance using a provided JSON string

Parameters:
Name Type Description
json string

Serialized JSON data representing the Roll
Returns:

A revived Roll instance

Type
Roll

(static) maximize(formula) → {Roll}

Source:

Return the maximum possible Dice roll which can result from the given formula

Parameters:
Name Type Description
formula string

A dice roll formula to maximize
Returns:

A Roll instance representing the maximal roll

Type
Roll

(static) minimize(formula) → {Roll}

Source:

Return the minimum possible Dice roll which can result from the given formula

Parameters:
Name Type Description
formula string

A dice roll formula to minimize
Returns:

A Roll instance representing the minimal roll

Type
Roll

alter(add, multiply)

Source:

Alter the Roll formula by adding or multiplying the number of dice included in each roll term

Example
let r = new Roll("4d8 + 4 + 2d4");
r.alter(1, 2);
r.formula;
> 9d8 + 4 + 5d4
Parameters:
Name Type Description
add Number

A number of dice to add to each Die term
multiply Number

A multiplier for the number of dice in each Die term

getTooltip() → {Promise.<HTMLElement>}

Source:

Render the tooltip HTML for a Roll instance

Returns:
Type
Promise.<HTMLElement>

(async) render(chatOptions) → {Promise.<HTMLElement>}

Source:

Render a Roll instance to HTML

Parameters:
Name Type Description
chatOptions Object

An object configuring the behavior of the resulting chat message.
Returns:

A Promise which resolves to the rendered HTML

Type
Promise.<HTMLElement>

reroll() → {Roll}

Source:

Create a new Roll object using the original provided formula and data Each roll is immutable, so this method returns a new Roll instance using the same data.

Returns:

A new Roll object, rolled using the same formula and data

Type
Roll

roll() → {Roll}

Source:

Execute the Roll, replacing dice and evaluating the total result

Example
let r = new Roll("2d6 + 4 + 1d4");
r.roll();
> 12
Returns:

The rolled Roll object, able to be chained into other methods

Type
Roll

toJSON() → {Object}

Source:

Structure the Roll data as an object suitable for JSON stringification

Returns:

Structured data which can be serialized into JSON

Type
Object

toMessage(chatData, rollModeopt, createopt) → {Promise|Object}

Source:

Transform a Roll instance into a ChatMessage, displaying the roll result. This function can either create the ChatMessage directly, or return the data object that will be used to create.

Parameters:
Name Type Attributes Default Description
chatData Object

The data object to use when creating the message
rollMode string | null <optional>
 null

The template roll mode to use for the message from CONFIG.rollModes
create boolean <optional>
 true

Whether to automatically create the chat message, or only return the prepared chatData object.
Returns:

A promise which resolves to the created ChatMessage entity, if create is true or the Object of prepared chatData otherwise.

Type
Promise | Object