The original provided data object which substitutes into attributes of the roll formula.
Options which modify or describe the Roll
The identified terms of the Roll
Internal _formulaStore the original cleaned formula for the Roll, prior to any internal evaluation or simplification
Internal _diceAn array of inner DiceTerms that were evaluated as part of the Roll evaluation
Internal _evaluatedTrack whether this Roll instance has been evaluated or not. Once evaluated the Roll is immutable.
Internal _totalCache the numeric total generated through evaluation of the Roll.
Internal _rootA reference to the Roll at the root of the evaluation tree.
Internal _resolverA reference to the RollResolver app being used to externally resolve this Roll.
Static MATH_A Proxy environment for safely evaluating a string using only available Math functions
Static CHAT_The HTML template path used to render a complete Roll object to the chat log
Static TOOLTIP_The HTML template used to render an expanded Roll tooltip to the chat log
Static RESOLVERSA mapping of Roll instances to currently-active resolvers.
Return a standardized representation for the displayed formula associated with this Roll.
The resulting arithmetic expression after rolls have been evaluated
Return the total result of the Roll expression if it has been evaluated.
Return the arbitrary product of evaluating this Roll.
Whether this Roll contains entirely deterministic terms or whether there is some randomness.
Static defaultStatic resolverRetrieve the appropriate resolver implementation based on the user's configuration.
Alter the Roll expression by adding or multiplying the number of dice which are rolled
A factor to multiply. Dice are multiplied before any additions.
A number of dice to add. Dice are added after multiplication.
Optional multiplyNumeric: boolean = {}Apply multiplication factor to numeric scalar terms
The altered Roll expression
Execute the Roll asynchronously, replacing dice and evaluating the total result
Optional options: { Options which inform how the Roll is evaluated
Minimize the result, obtaining the smallest possible value.
Maximize the result, obtaining the largest possible value.
If true, string terms will not cause an error to be thrown during evaluation.
If false, force the use of non-interactive rolls and do not prompt the user to make manual rolls.
The evaluated Roll instance
let r = new Roll("2d6 + 4 + 1d4");
await r.evaluate();
console.log(r.result); // 5 + 4 + 2
console.log(r.total); // 11
Execute the Roll synchronously, replacing dice and evaluating the total result.
Optional options: { Minimize the result, obtaining the smallest possible value.
Maximize the result, obtaining the largest possible value.
Throw an Error if the Roll contains non-deterministic terms that cannot be evaluated synchronously. If this is set to false, non-deterministic terms will be ignored.
If true, string terms will not cause an error to be thrown during evaluation.
The evaluated Roll instance.
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.
Optional options: object = {}Evaluation options passed to Roll#evaluate
A new Roll object, rolled using the same formula and data
Render a Roll instance to HTML
Optional options: { Options which affect how the Roll is rendered
Flavor text to include
A custom HTML template path
Is the Roll displayed privately?
The rendered HTML template as a string
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.
The data object to use when creating the message
Optional options: options = {}Additional options which modify the created message.
A promise which resolves to the created ChatMessage document if create is true, or the Object of prepared chatData otherwise.
Construct an inline roll link for this Roll.
Optional options: { Additional options to configure how the link is constructed.
A custom label for the total.
Attributes to set on the link.
Custom data attributes to set on the link.
Additional classes to add to the link. The classes inline-roll
and inline-result are added by default.
A font-awesome icon class to use as the icon instead of a d20.
Protected _prepareProtected _evaluateProtected Evaluate the roll asynchronously.
Optional options: { Options which inform how evaluation is performed
Force the result to be minimized
Force the result to be maximized
If true, string terms will not cause an error to be thrown during evaluation.
If false, force the use of digital rolls and do not prompt the user to make manual rolls.
Protected _evaluateASTAsyncProtected Evaluate an AST asynchronously.
The root node or term.
Optional options: { Options which inform how evaluation is performed
Force the result to be minimized
Force the result to be maximized
If true, string terms will not cause an error to be thrown during evaluation.
Protected _evaluateProtected Evaluate the roll synchronously.
Optional options: { Options which inform how evaluation is performed
Force the result to be minimized
Force the result to be maximized
Throw an error if encountering a term that cannot be synchronously evaluated.
If true, string terms will not cause an error to be thrown during evaluation.
Protected _evaluateASTSyncProtected Evaluate an AST synchronously.
The root node or term.
Optional options: { Options which inform how evaluation is performed
Force the result to be minimized
Force the result to be maximized
Throw an error if encountering a term that cannot be synchronously evaluated.
If true, string terms will not cause an error to be thrown during evaluation.
Protected _evaluateStatic createA factory method which constructs a Roll instance using the default configured Roll class.
The formula used to create the Roll instance
Optional data: object = {}The data object which provides component data for the formula
Optional options: object = {}Additional options which modify or describe this Roll
The constructed Roll instance
Static getTransform an array of RollTerm objects into a cleaned string formula representation.
An array of terms to represent as a formula
The string representation of the formula
Static safeStatic simplifyAfter 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.
An array of terms which is eligible for simplification
An array of simplified terms
Static simulateStatic registerRegister an externally-fulfilled result with an active RollResolver.
The fulfillment method.
The die denomination being fulfilled.
The obtained result.
Whether the result was consumed. Returns undefined if no resolver was available.
Static parseStatic instantiateASTStatic replaceReplace referenced data attributes in the roll formula with values from the provided data. Data references in the formula use the
The original formula within which to replace
The data object which provides replacements
Optional options: { Options which modify formula replacement
The value that should be assigned to any unmatched keys. If null, the unmatched key is left as-is.
Display a warning notification when encountering an un-matched key.
syntax and would reference the corresponding attr key.
Static validateStatic identifyStatic _classifyInternal Classify a remaining string term into a recognized RollTerm class
A classified RollTerm instance
Static expandStatic collapseStatic fromStatic fromJSONStatic fromManually construct a Roll object by providing an explicit set of input terms
The array of terms to use as the basis for the Roll
Optional options: object = {}Additional options passed to the Roll constructor
The constructed Roll instance
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
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.
Example: Attack with advantage