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 full)

Properties

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

Accessors

dice expression total values isDeterministic formula flavor resolver

Methods

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

Properties

terms

terms: string[]

The original provided terms to the Dice Pool

modifiers

modifiers: string[]

The string modifiers applied to resolve the pool

rolls

rolls: Roll[]

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

results

results: DiceTermResult[]

The array of dice pool results which have been rolled

options

options: object

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

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?

Static MODIFIERS

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

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

Static OPEN_REGEXP

OPEN_REGEXP: RegExp = ...

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

Static CLOSE_REGEXP

CLOSE_REGEXP: RegExp = ...

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

Static REGEXP

REGEXP: RegExp = ...

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

Static SERIALIZE_ATTRIBUTES

SERIALIZE_ATTRIBUTES: string[] = ...

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

Static FLAVOR_REGEXP_STRING

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

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

Static FLAVOR_REGEXP

FLAVOR_REGEXP: RegExp = ...

A regular expression which identifies term-level flavor text

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

total

  • get total(): number

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

    Returns number

values

  • get values(): number[]

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

    Returns number[]

isDeterministic

  • get isDeterministic(): boolean

  • Whether this term is entirely deterministic or contains some randomness.

    Returns boolean

formula

  • get formula(): string

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

    Returns string

flavor

  • get flavor(): string

  • Optional flavor text which modifies and describes this term.

    Returns string

resolver

  • get resolver(): RollResolver

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

    Returns RollResolver

Methods

alter

  • alter(...args): PoolTerm

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

    Parameters

    • Rest ...args: any[]

      Arguments passed to each contained Roll#alter method.

    Returns PoolTerm

    The altered pool

_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.

    _evaluateModifiers

    • _evaluateModifiers(): any

    • Use the same logic as for the DiceTerm to avoid duplication

      Returns any

      See

      DiceTerm#_evaluateModifiers

    _evaluateModifier

    • _evaluateModifier(command, modifier): any

    • Use the same logic as for the DiceTerm to avoid duplication

      Parameters

      • command: any
      • modifier: any

      Returns any

      See

      DiceTerm#_evaluateModifier

    toJSON

    • toJSON(): object

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

    keep

    • keep(modifier): any

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

    drop

    • drop(modifier): any

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

    countSuccess

    • countSuccess(modifier): any

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

    countFailures

    • countFailures(modifier): any

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

    evaluate

    • evaluate(options?): RollTerm | Promise<RollTerm>

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

      Parameters

      • Optional options: {
            minimize: boolean;
            maximize: boolean;
            allowStrings: boolean;
        } = {}

        Options which modify how the RollTerm is evaluated

        • minimize: boolean

          Minimize the result, obtaining the smallest possible value.

        • maximize: boolean

          Maximize the result, obtaining the largest possible value.

        • allowStrings: boolean

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

      Returns RollTerm | Promise<RollTerm>

      Returns a Promise if the term is non-deterministic.

    Protected _evaluateAsync

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

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

      Parameters

      • Optional options: object = {}

      Returns Promise<PoolTerm>

    Protected _evaluateSync

    • _evaluateSync(options?): PoolTerm
    • Protected

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

      Parameters

      • Optional options: object = {}

      Returns PoolTerm

    Static _fromData

    • _fromData(data): 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

    Static fromExpression

    • fromExpression(formula, options?): PoolTerm

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

      Parameters

      • formula: string

        The string formula to parse

      • Optional options: object = {}

        Additional options applied to the PoolTerm

      Returns PoolTerm

      The evaluated PoolTerm object or null if the formula is invalid

    Static fromRolls

    • fromRolls(rolls?): RollTerm

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

      The constructed PoolTerm comprised of the provided rolls

    Static fromParseNode

    Static isDeterministic

    • isDeterministic(term, options?): boolean

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

      Parameters

      • term: RollTerm

        The term.

      • Optional options: {
            maximize: boolean;
            minimize: boolean;
        } = {}

        Options for evaluating the term.

        • maximize: boolean

          Force the result to be maximized.

        • minimize: boolean

          Force the result to be minimized.

      Returns boolean

    Static fromData

    • fromData(data): RollTerm

    • Construct a RollTerm from a provided data object

      Parameters

      • data: object

        Provided data from an un-serialized term

      Returns RollTerm

      The constructed RollTerm

    Static fromJSON

    • fromJSON(json): 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

    Settings

    Member Visibility

    Theme

    On This Page

    termsmodifiersrollsresultsoptions_rootisIntermediateMODIFIERSOPEN_REGEXPCLOSE_REGEXPREGEXPSERIALIZE_ATTRIBUTESFLAVOR_REGEXP_STRINGFLAVOR_REGEXPdiceexpressiontotalvaluesisDeterministicformulaflavorresolveralter_evaluate_evaluateModifiers_evaluateModifiertoJSONkeepdropcountSuccesscountFailuresevaluate_evaluateAsync_evaluateSync_fromDatafromExpressionfromRollsfromParseNodeisDeterministicfromDatafromJSON