Class PoolTerm

A type of RollTerm which encloses a pool of multiple inner Rolls which are evaluated jointly.

A dice pool represents a set of Roll expressions which are collectively modified to compute an effective total across all Rolls in the pool. The final total for the pool is defined as the sum over kept rolls, relative to any success count or margin.

Example: Keep the highest of the 3 roll expressions

let pool = new PoolTerm({
  terms: ["4d6", "3d8 - 1", "2d10 + 3"],
  modifiers: ["kh"]
});
pool.evaluate();

Hierarchy (View Summary)

Properties

_root isIntermediate modifiers options results rolls terms CLOSE_REGEXP FLAVOR_REGEXP FLAVOR_REGEXP_STRING MODIFIERS OPEN_REGEXP REGEXP SERIALIZE_ATTRIBUTES

Accessors

dice expression flavor formula isDeterministic resolver total values

Methods

_evaluate _evaluateModifier _evaluateModifiers alter countFailures countSuccess drop evaluate keep toJSON _evaluateAsync _evaluateSync _fromData fromData fromExpression fromJSON fromParseNode fromRolls isDeterministic

Properties

Internal_root

_root: Roll

A reference to the Roll at the root of the evaluation tree.

isIntermediate

isIntermediate: boolean = false

Is this term intermediate, and should be evaluated first as part of the simplification process?

modifiers

modifiers: string[]

The string modifiers applied to resolve the pool

options

options: object

An object of additional options which describes and modifies the term.

results

results: DiceTermResult[]

The array of dice pool results which have been rolled

rolls

rolls: Roll[]

Each component term of the dice pool as a Roll instance.

terms

terms: string[]

The original provided terms to the Dice Pool

StaticCLOSE_REGEXP

CLOSE_REGEXP: RegExp = ...

A regular expression pattern used to identify the closing of a dice pool expression.

StaticFLAVOR_REGEXP

FLAVOR_REGEXP: RegExp = ...

A regular expression which identifies term-level flavor text

StaticFLAVOR_REGEXP_STRING

FLAVOR_REGEXP_STRING: string = "(?:\\[([^\\]]+)\\])"

A regular expression pattern which identifies optional term-level flavor text

StaticMODIFIERS

MODIFIERS: Record<string, string | Function> = ...

Define the modifiers that can be used for this particular DiceTerm type.

StaticOPEN_REGEXP

OPEN_REGEXP: RegExp = ...

The regular expression pattern used to identify the opening of a dice pool expression.

StaticREGEXP

REGEXP: RegExp = ...

A regular expression pattern used to match the entirety of a DicePool expression.

StaticSERIALIZE_ATTRIBUTES

SERIALIZE_ATTRIBUTES: string[] = ...

An array of additional attributes which should be retained when the term is serialized

Accessors

dice

  • get dice(): DiceTerm[]

    Return an Array of each individual DiceTerm instances contained within the PoolTerm.

    Returns DiceTerm[]

expression

  • get expression(): string

    A string representation of the formula expression for this RollTerm, prior to evaluation.

    Returns string

flavor

  • get flavor(): string

    Optional flavor text which modifies and describes this term.

    Returns string

formula

  • get formula(): string

    A string representation of the formula, including optional flavor text.

    Returns string

isDeterministic

  • get isDeterministic(): boolean

    Whether this term is entirely deterministic or contains some randomness.

    Returns boolean

resolver

  • get resolver(): RollResolver

    A reference to the RollResolver app being used to externally resolve this term.

    Returns RollResolver

total

  • get total(): undefined | number

    A string or numeric representation of the final output for this term, after evaluation.

    Returns undefined | number

values

  • get values(): number[]

    Return an array of rolled values which are still active within the PoolTerm

    Returns number[]

Methods

_evaluate

  • _evaluate(options?: {}): PoolTerm | Promise<PoolTerm>

    Evaluate the term.

    Parameters

    • options: {} = {}

      Options which modify how the RollTerm is evaluated, see RollTerm#evaluate

    Returns PoolTerm | Promise<PoolTerm>

    Returns a Promise if the term is non-deterministic.

_evaluateModifier

  • _evaluateModifier(command: string, modifier: string): Promise<void>
    Internal

    Use the same logic as for the DiceTerm to avoid duplication

    Parameters

    • command: string
    • modifier: string

    Returns Promise<void>

    See

    foundry.dice.terms.DiceTerm#_evaluateModifier

_evaluateModifiers

alter

  • alter(...args: any[]): PoolTerm

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

    Parameters

    • ...args: any[]

      Arguments passed to each contained Roll#alter method.

    Returns PoolTerm

    The altered pool

countFailures

  • countFailures(modifier: string): undefined | false

    Count the number of failed results which occurred in a given result set. Failures are counted relative to some target, or relative to the lowest possible value if no target is given. Applying a count-failures modifier to the results re-casts all results to 1 (failure) or 0 (non-failure)

    6d6cf Count the number of dice which rolled a 1 as failures 6d6cf<=3 Count the number of dice which rolled less than 3 as failures 6d6cf>4 Count the number of dice which rolled greater than 4 as failures

    Parameters

    • modifier: string

      The matched modifier query

    Returns undefined | false

countSuccess

  • countSuccess(modifier: string): undefined | false

    Count the number of successful results which occurred in the pool. Successes are counted relative to some target, or relative to the maximum possible value if no target is given. Applying a count-success modifier to the results re-casts all results to 1 (success) or 0 (failure)

    20d20cs Count the number of dice which rolled a 20 20d20cs>10 Count the number of dice which rolled higher than 10 20d20cs<10 Count the number of dice which rolled less than 10

    Parameters

    • modifier: string

      The matched modifier query

    Returns undefined | false

drop

  • drop(modifier: string): undefined | false

    Keep a certain number of highest or lowest dice rolls from the result set.

    {1d6,1d8,1d10,1d12}dl3 Drop the 3 worst results in the pool {1d12,6}dh Drop the highest result in the pool

    Parameters

    • modifier: string

      The matched modifier query

    Returns undefined | false

evaluate

  • evaluate(
        options?: {
            allowStrings?: boolean;
            maximize?: boolean;
            minimize?: boolean;
        },
    ): RollTerm
    | Promise<RollTerm>

    Evaluate the term, processing its inputs and finalizing its total.

    Parameters

    • Optionaloptions: { allowStrings?: boolean; maximize?: boolean; minimize?: boolean } = {}

      Options which modify how the RollTerm is evaluated

      • OptionalallowStrings?: boolean

        If true, string terms will not throw an error when evaluated.

      • Optionalmaximize?: boolean

        Maximize the result, obtaining the largest possible value.

      • Optionalminimize?: boolean

        Minimize the result, obtaining the smallest possible value.

    Returns RollTerm | Promise<RollTerm>

    Returns a Promise if the term is non-deterministic.

keep

  • keep(modifier: string): undefined | false

    Keep a certain number of highest or lowest dice rolls from the result set.

    {1d6,1d8,1d10,1d12}kh2 Keep the 2 best rolls from the pool {1d12,6}kl Keep the lowest result in the pool

    Parameters

    • modifier: string

      The matched modifier query

    Returns undefined | false

toJSON

  • toJSON(): RollTermData

    Serialize the RollTerm to a JSON string which allows it to be saved in the database or embedded in text. This method should return an object suitable for passing to the JSON.stringify function.

    Returns RollTermData

Protected_evaluateAsync

  • _evaluateAsync(options?: object): Promise<PoolTerm>
    Protected

    Evaluate this pool term when it contains any non-deterministic sub-terms.

    Parameters

    • Optionaloptions: object = {}

    Returns Promise<PoolTerm>

Protected_evaluateSync

  • _evaluateSync(options?: object): PoolTerm
    Protected

    Evaluate this pool term when it contains only deterministic sub-terms.

    Parameters

    • Optionaloptions: object = {}

    Returns PoolTerm

Static_fromData

  • _fromData(data: any): RollTerm

    Define term-specific logic for how a de-serialized data object is restored as a functional RollTerm

    Parameters

    • data: any

      The de-serialized term data

    Returns RollTerm

    The re-constructed RollTerm object

StaticfromData

StaticfromExpression

  • fromExpression(formula: string, options?: object): null | PoolTerm

    Given a string formula, create and return an evaluated PoolTerm object

    Parameters

    • formula: string

      The string formula to parse

    • Optionaloptions: object = {}

      Additional options applied to the PoolTerm

    Returns null | PoolTerm

    The evaluated PoolTerm object or null if the formula is invalid

StaticfromJSON

  • fromJSON(json: string): RollTerm

    Reconstruct a RollTerm instance from a provided JSON string

    Parameters

    • json: string

      A serialized JSON representation of a DiceTerm

    Returns RollTerm

    A reconstructed RollTerm from the provided JSON

StaticfromParseNode

StaticfromRolls

  • fromRolls(rolls?: Roll[]): PoolTerm

    Create a PoolTerm by providing an array of existing Roll objects

    Parameters

    • rolls: Roll[] = []

      An array of Roll objects from which to create the pool

    Returns PoolTerm

    The constructed PoolTerm comprised of the provided rolls

StaticisDeterministic

  • isDeterministic(
        term: RollTerm,
        options?: { maximize?: boolean; minimize?: boolean },
    ): boolean

    Determine if evaluating a given RollTerm with certain evaluation options can be done so deterministically.

    Parameters

    • term: RollTerm

      The term.

    • Optionaloptions: { maximize?: boolean; minimize?: boolean } = {}

      Options for evaluating the term.

      • Optionalmaximize?: boolean

        Force the result to be maximized.

      • Optionalminimize?: boolean

        Force the result to be minimized.

    Returns boolean

Settings

Member Visibility

On This Page

Properties
Accessors
Methods