Roll

Roll

An interface and API for constructing and evaluating 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)

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

// The parsed terms of the roll formula
console.log(r.terms);    // [Die, OperatorTerm, NumericTerm, OperatorTerm, NumericTerm]

// Execute the roll
r.evaluate();

// 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

_dice :Array.<DiceTerm>

An array of inner DiceTerms which were evaluated as part of the Roll evaluation

Type:

_evaluated :boolean

Track whether this Roll instance has been evaluated or not. Once evaluated the Roll is immutable.

Type:
  • boolean

_formula :string

Store the original cleaned formula for the Roll, prior to any internal evaluation or simplification

Type:
  • string

CHAT_TEMPLATE :string

The HTML template path used to render a complete Roll object to the chat log

Type:
  • string

data :Object

The original provided data object which substitutes into attributes of the roll formula

Type:
  • Object

dice

Return an Array of the individual DiceTerm instances contained within this Roll.

formula

Return a standardized representation for the displayed formula associated with this Roll.

MATH_PROXY :Math

A Proxy environment for safely evaluating a string using only available Math functions

Type:

options :object

Options which modify or describe the Roll

Type:
  • object

result

The resulting arithmetic expression after rolls have been evaluated

terms :Array.<RollTerm>

The identified terms of the Roll

Type:

TOOLTIP_TEMPLATE :string

The HTML template used to render an expanded Roll tooltip to the chat log

Type:
  • string

total :number

Return the total result of the Roll expression if it has been evaluated.

Type:
  • number

Methods

(static) collapseInlineResult(a)

Collapse an expanded inline roll to conceal it's tooltip

Parameters:
Name Type Description
a HTMLAnchorElement

The inline-roll button

(static) create(formula, dataopt, optionsopt) → {Roll}

A factory method which constructs a Roll instance using the default configured Roll class.

Parameters:
Name Type Attributes Default Description
formula string

The formula used to create the Roll instance
data object <optional>
 {}

The data object which provides component data for the formula
options object <optional>
 {}

Additional options which modify or describe this Roll
Returns:

The constructed Roll instance

Type
Roll

(async, static) expandInlineResult(a) → {Promise.<void>}

Expand an inline roll element to display it's contained dice result as a tooltip

Parameters:
Name Type Description
a HTMLAnchorElement

The inline-roll button
Returns:
Type
Promise.<void>

(static) fromData(data) → {Roll}

Recreate a Roll instance using a provided data object

Parameters:
Name Type Description
data object

Unpacked data representing the Roll
Returns:

A reconstructed Roll instance

Type
Roll

(static) fromJSON(json) → {Roll}

Recreate a Roll instance using a provided JSON string

Parameters:
Name Type Description
json string

Serialized JSON data representing the Roll
Returns:

A reconstructed Roll instance

Type
Roll

(static) fromTerms(terms, optionsopt) → {Roll}

Manually construct a Roll object by providing an explicit set of input terms

Example
const t1 = new Die({number: 4, faces: 8};
const plus = new OperatorTerm({operator: "+"});
const t2 = new NumericTerm({number: 8});
const roll = Roll.fromTerms([t1, plus, t2]);
roll.formula; // 4d8 + 8
Parameters:
Name Type Attributes Default Description
terms Array.<RollTerm>

The array of terms to use as the basis for the Roll
options object <optional>
 {}

Additional options passed to the Roll constructor
Returns:

The constructed Roll instance

Type
Roll

(static) getFormula(terms) → {string}

Transform an array of RollTerm objects into a cleaned string formula representation.

Parameters:
Name Type Description
terms Array.<RollTerm>

An array of terms to represent as a formula
Returns:

The string representation of the formula

Type
string

(static) parse(formula, data) → {Array.<RollTerm>}

Parse a formula by following an order of operations:

Step 1: Replace formula data Step 2: Split outer-most parenthetical groups Step 3: Further split outer-most dice pool groups Step 4: Further split string terms on arithmetic operators Step 5: Classify all remaining strings

Parameters:
Name Type Description
formula string

The original string expression to parse
data object

A data object used to substitute for attributes in the formula
Returns:

A parsed array of RollTerm instances

Type
Array.<RollTerm>

(static) replaceFormulaData(formula, data, missingopt, warnopt)

Replace referenced data attributes in the roll formula with values from the provided data. Data references in the formula use the @attr syntax and would reference the corresponding attr key.

Parameters:
Name Type Attributes Description
formula string

The original formula within which to replace
data object

The data object which provides replacements
missing string <optional>

The value that should be assigned to any unmatched keys. If null, the unmatched key is left as-is.
warn boolean <optional>

Display a warning notification when encountering an un-matched key.

(static) safeEval(expression) → {number}

A sandbox-safe evaluation function to execute user-input code with access to scoped Math methods.

Parameters:
Name Type Description
expression string

The input string expression
Returns:

The numeric evaluated result

Type
number

(static) simplifyTerms(terms) → {Array.<RollTerm>}

After parenthetical and arithmetic terms have been resolved, we need to simplify the remaining expression. Any remaining string terms need to be combined with adjacent non-operators in order to construct parsable terms.

Parameters:
Name Type Description
terms Array.<RollTerm>

An array of terms which is eligible for simplification
Returns:

An array of simplified terms

Type
Array.<RollTerm>

(static) simulate(formula, n) → {Array.<number>}

Simulate a roll and evaluate the distribution of returned results

Parameters:
Name Type Default Description
formula string

The Roll expression to simulate
n number 10000

The number of simulations
Returns:

The rolled totals

Type
Array.<number>

(static) validate(formula) → {boolean}

Validate that a provided roll formula can represent a valid

Parameters:
Name Type Description
formula string

A candidate formula to validate
Returns:

Is the provided input a valid dice formula?

Type
boolean

(protected) _prepareData(data) → {object}

Prepare the data structure used for the Roll. This is factored out to allow for custom Roll classes to do special data preparation using provided input.

Parameters:
Name Type Description
data object

Provided roll data
Returns:

The prepared data object

Type
object

alter(multiply, add, multiplyNumericopt) → {Roll}

Alter the Roll expression by adding or multiplying the number of dice which are rolled

Parameters:
Name Type Attributes Description
multiply number

A factor to multiply. Dice are multiplied before any additions.
add number

A number of dice to add. Dice are added after multiplication.
multiplyNumeric boolean <optional>

Apply multiplication factor to numeric scalar terms
Returns:

The altered Roll expression

Type
Roll

clone() → {Roll}

Clone the Roll instance, returning a new Roll instance that has not yet been evaluated.

Returns:
Type
Roll

evaluate(optionsopt) → {Roll|Promise.<Roll>}

Execute the Roll, replacing dice and evaluating the total result

Example
let r = new Roll("2d6 + 4 + 1d4");
r.evaluate();
console.log(r.result); // 5 + 4 + 2
console.log(r.total);  // 11
Parameters:
Name Type Attributes Default Description
options object <optional>
 {}

Options which inform how the Roll is evaluated

Properties
Name Type Attributes Default Description
minimize boolean <optional>
 false

Minimize the result, obtaining the smallest possible value.
maximize boolean <optional>
 false

Maximize the result, obtaining the largest possible value.
async boolean <optional>
 false

Evaluate the roll asynchronously, receiving a Promise as the returned value. This will become the default behavior in version 10.x
Returns:

The evaluated Roll instance

Type
Roll | Promise.<Roll>

(async) getTooltip() → {Promise.<string>}

Render the tooltip HTML for a Roll instance

Returns:

The rendered HTML tooltip as a string

Type
Promise.<string>

(async) render(chatOptionsopt) → {Promise.<string>}

Render a Roll instance to HTML

Parameters:
Name Type Attributes Description
chatOptions object <optional>

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

The rendered HTML template as a string

Type
Promise.<string>

reroll(optionsopt) → {Roll}

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.

Parameters:
Name Type Attributes Default Description
options object <optional>
 {}

Evaluation options passed to Roll#evaluate
Returns:

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

Type
Roll

roll()

See:

Alias for evaluate.

toJSON() → {Object}

Represent the data of the Roll as an object suitable for JSON serialization.

Returns:

Structured data which can be serialized into JSON

Type
Object

(async) toMessage(messageData, optionsopt) → {Promise.<ChatMessage>}

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 Description
messageData object

The data object to use when creating the message
options options <optional>

Additional options which modify the created message.

Properties
Name Type Attributes Default Description
rollMode string <optional>

The template roll mode to use for the message from CONFIG.Dice.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.<ChatMessage>