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:
- Array.<string>
(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
(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