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 terms of the roll formula
console.log(r.terms);    // [Die, +, 2, +, 4]

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

(static) ARITHMETIC :Array.<string>

Source:

Allowed arithmetic operators which can join together terms in a Roll expression

Type:

(static) MATH_PROXY :Math

Source:

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

Type:
  • Math

(static) PARENTHETICAL_RGX :RegExp

Source:

A regular expression used to identify the Roll formula for parenthetical terms

Type:
  • RegExp

_dice :Array.<DiceTerm>

Source:

An array of inner terms which were rolled parenthetically

Type:

_formula :string

Source:

The original formula before evaluation

Type:
  • string

data :Object

Source:

The original provided data

Type:
  • Object

dice

Source:

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

formula

Source:

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

parts

Source:
Deprecated:
  • since 0.7.0
See:

result

Source:

The resulting arithmetic expression after rolls have been evaluated

results :Array.<(number|string)>

Source:

The evaluated results of the Roll

Type:
  • Array.<(number|string)>

terms :Array.<(Roll|DicePool|DiceTerm|number|string)>

Source:

The identified terms of the Roll

Type:

total :number|null

Source:

Return the total result of the Roll expression if it has been evaluated, otherwise null

Type:
  • number | null

Methods

(static) cleanFormula() → {string}

Source:

Create a formula string from an array of Dice terms.

Returns:
Type
string

(static) cleanTerms(terms) → {Array.<(DiceTerm|string|number)>}

Source:

Clean the terms of a Roll equation, removing empty space and de-duping arithmetic operators

Parameters:
Name Type Description
terms Array.<(DiceTerm|string|number)>

The input array of terms
Returns:

The cleaned array of terms

Type
Array.<(DiceTerm|string|number)>

(static) create(…args) → {Roll}

Source:

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

Parameters:
Name Type Attributes Description
args Array.<any> <repeatable>

Arguments passed to the Roll instance constructor
Returns:

The constructed Roll instance

Type
Roll

(static) fromData(data) → {Roll}

Source:

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}

Source:

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) fromTerm(term, data) → {Roll}

Source:

Construct a new Roll object from a parenthetical term of an outer Roll.

Parameters:
Name Type Description
term string

The isolated parenthetical term, for example (4d6)
data object

The Roll data object, provided by the outer Roll
Returns:

An inner Roll object constructed from the term

Type
Roll

(static) maximize()

Source:
Deprecated:
  • since 0.7.0
See:

(static) minimize()

Source:
Deprecated:
  • since 0.7.0
See:

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

Source:

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) simulate(formula, n) → {Array.<number>}

Source:

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}

Source:

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

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

Source:

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}

Source:

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

Returns:
Type
Roll

evaluate(minimizeopt, maximizeopt) → {Roll}

Source:

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 Description
minimize boolean <optional>

Produce the minimum possible result from the Roll instead of a random result.
maximize boolean <optional>

Produce the maximum possible result from the Roll instead of a random result.
Returns:

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

Type
Roll

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:

Evaluate and return the Roll expression. This function simply calls the evaluate() method but is maintained for backwards compatibility.

Returns:

The Roll instance, containing evaluated results and the rolled total.

Type
Roll

toJSON() → {Object}

Source:

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

Returns:

Structured data which can be serialized into JSON

Type
Object

toMessage(messageData, 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
messageData 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.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 | Object