Foundry Virtual Tabletop - API Documentation - Version 14
    Preparing search index...

    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.

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

    Hierarchy (View Summary)

    Index

    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: boolean = false

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

    modifiers: string[]

    The string modifiers applied to resolve the pool

    options: object

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

    results: DiceTermResult[]

    The array of dice pool results which have been rolled

    rolls: Roll[]

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

    terms: string[]

    The original provided terms to the Dice Pool

    CLOSE_REGEXP: RegExp = ...

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

    FLAVOR_REGEXP: RegExp = ...

    A regular expression which identifies term-level flavor text

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

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

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

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

    OPEN_REGEXP: RegExp = ...

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

    REGEXP: RegExp = ...

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

    SERIALIZE_ATTRIBUTES: string[] = ...

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

    Accessors

    • get dice(): DiceTerm[]

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

      Returns DiceTerm[]

    • get expression(): string

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

      Returns string

    • get flavor(): string

      Optional flavor text which modifies and describes this term.

      Returns string

    • get formula(): string

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

      Returns string

    • get isDeterministic(): boolean

      Whether this term is entirely deterministic or contains some randomness.

      Returns boolean

    • get resolver(): RollResolver

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

      Returns RollResolver

    • get total(): number | undefined

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

      Returns number | undefined

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

      foundry.dice.terms.DiceTerm#_evaluateModifier

    _evaluateModifiers

    • 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

    • 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 false | undefined

    • 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 false | undefined

    • 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 false | undefined

    • 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 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 false | undefined

    • 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

    • 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 PoolTerm | null

      The evaluated PoolTerm object or null if the formula is invalid

    • 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

    • 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

    • 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