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

    Class DiceTerm

    An abstract base class for any type of RollTerm which involves randomized input from dice, coins, or other devices.

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    _root isIntermediate minValue modifiers options results _faces _number DENOMINATION FLAVOR_REGEXP FLAVOR_REGEXP_STRING MODIFIER_REGEXP MODIFIERS MODIFIERS_REGEXP_STRING REGEXP SERIALIZE_ATTRIBUTES

    Accessors

    denomination dice expression faces flavor formula isDeterministic maxResult method minResult number resolver total values

    Methods

    _evaluate _evaluateModifier _evaluateModifiers alter evaluate getResultCSS getResultLabel getTooltipData mapRandomFace randomFace roll toJSON _evaluateAsync _evaluateSync _roll _applyCount _applyDeduct _fromData _keepOrDrop compareResult fromData fromJSON fromMatch fromParseNode isDeterministic matchTerm

    Constructors

    • Parameters

      • termData: {
            faces?: number | Roll;
            method: string;
            minValue?: number;
            modifiers?: string[];
            number?: number | Roll;
            options?: object;
            results?: DiceTermResult[];
        }

        Data used to create the Dice Term, including the following:

        • Optionalfaces?: number | Roll

          The number of faces on each die of this type, or a Roll instance that will be evaluated to a number.

        • method: string

          The resolution method used to resolve DiceTerm.

        • OptionalminValue?: number

          The minimum possible value on any face of the die with positive faces.

        • Optionalmodifiers?: string[]

          An array of modifiers applied to the results

        • Optionalnumber?: number | Roll

          The number of dice of this term to roll, before modifiers are applied, or a Roll instance that will be evaluated to a number.

        • Optionaloptions?: object

          Additional options that modify the term

        • Optionalresults?: DiceTermResult[]

          An optional array of pre-cast results for the term

      Returns DiceTerm

    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?

    minValue: number

    The minimum possible value (integer) on any face of the die with positive faces.

    modifiers: string[]

    An Array of dice term modifiers which are applied

    options: object

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

    results: DiceTermResult[]

    The array of dice term results which have been rolled

    Protected_faces

    _faces: number | Roll

    The number of faces on the die, or a Roll instance that will be evaluated to a number.

    Protected_number

    _number: number | Roll

    The number of dice of this term to roll, before modifiers are applied, or a Roll instance that will be evaluated to a number.

    DENOMINATION: string = ""

    Define the denomination string used to register this DiceTerm type in CONFIG.Dice.terms

    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

    MODIFIER_REGEXP: RegExp = ...

    A regular expression used to separate individual modifiers

    MODIFIERS: Record<string, string | Function> = {}

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

    MODIFIERS_REGEXP_STRING: string = "([^ (){}[\\]+\\-*/]+)"

    A regular expression pattern which captures the full set of term modifiers Anything until a space, group symbol, or arithmetic operator

    REGEXP: RegExp = ...

    A regular expression used to match a term of this type

    SERIALIZE_ATTRIBUTES: string[] = ...

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

    Accessors

    • get denomination(): string

      The denomination of this DiceTerm instance.

      Returns string

    • get dice(): DiceTerm[]

      An array of additional DiceTerm instances involved in resolving this DiceTerm.

      Returns DiceTerm[]

    • get expression(): string

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

      Returns string

    • get faces(): number | void

      The number of faces on the die. Returns undefined if the faces are represented as a complex term that has not yet been evaluated.

      Returns number | void

    • set faces(value: number | Roll): void

      Parameters

      • value: number | Roll

      Returns void

    • 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 maxResult(): number

      The maximum result that can be rolled on the die. If the faces are 0, the maximum result is 0. If the faces are positive and integer, the maximum result is equal to the minimum value (DiceTerm#minValue) plus the number of faces (DiceTerm#faces) minus 1.

      Returns number

    • get method(): string

      The resolution method used to resolve this DiceTerm.

      Returns string

    • get minResult(): number

      The minimum result that can be rolled on the die. If the faces are 0, the minimum result is 0. If the faces are positive and integer, the minimum result is equal to the minimum value (DiceTerm#minValue).

      Returns number

    • get number(): number | void

      The number of dice of this term to roll. Returns undefined if the number is a complex term that has not yet been evaluated.

      Returns number | void

    • set number(value: number | Roll): void

      Parameters

      • value: number | Roll

      Returns void

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

      Returns number[]

    Methods

    _evaluate

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

      Evaluate the term.

      Parameters

      • options: {} = {}

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

      Returns DiceTerm | Promise<DiceTerm>

      Returns a Promise if the term is non-deterministic.

    _evaluateModifier

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

      Asynchronously evaluate a single modifier command, recording it in the array of evaluated modifiers

      Parameters

      • command: string

        The parsed modifier command

      • modifier: string

        The full modifier request

      Returns Promise<void>

    _evaluateModifiers

    • _evaluateModifiers(): Promise<void>
      Internal

      Sequentially evaluate each dice roll modifier by passing the term to its evaluation function Augment or modify the results array.

      Returns Promise<void>

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

      Parameters

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

      Returns DiceTerm

      The altered term

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

    • Get the CSS classes that should be used to display each rolled result

      Parameters

      Returns (string | null)[]

      The desired classes

    • Return a string used as the label for each rolled result

      Parameters

      Returns string

      The result label

    • Render the tooltip HTML for a Roll instance

      Returns object

      The data object used to render the default tooltip template for this DiceTerm

    • Maps a randomly-generated value in the interval [0, 1) to a face value on the die. Returns NaN if the faces are NaN or represented as a complex term that has not yet been evaluated.

      Parameters

      • randomUniform: number

        A value to map. Must be in the interval [0, 1).

      Returns number

      The face value, an integer between DiceTerm#minResult and DiceTerm#maxResult, or NaN if the faces are NaN or not evaluated yet.

    • Generate a random face value for this die using the configured PRNG. Returns NaN if the faces are NaN or are represented as a complex term that has not yet been evaluated.

      Returns number

      The face value, an integer between DiceTerm#minResult and DiceTerm#maxResult, or NaN if the faces are NaN or not evaluated yet.

    • Roll the DiceTerm by mapping a random uniform draw against the faces of the dice term.

      Parameters

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

        Options which modify how a random result is produced

        • Optionalmaximize?: boolean

          Maximize the result, obtaining the largest possible value.

        • Optionalminimize?: boolean

          Minimize the result, obtaining the smallest possible value.

      Returns Promise<DiceTermResult>

      The produced result

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

      Evaluate this dice term asynchronously.

      Parameters

      • Optionaloptions: object = {}

        Options forwarded to inner Roll evaluation.

      Returns Promise<DiceTerm>

    Protected_evaluateSync

    • _evaluateSync(
          options?: { maximize?: boolean; minimize?: boolean; strict?: boolean },
      ): DiceTerm
      Protected

      Evaluate deterministic values of this term synchronously.

      Parameters

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

          Force the result to be maximized.

        • Optionalminimize?: boolean

          Force the result to be minimized.

        • Optionalstrict?: boolean

          Throw an error if attempting to evaluate a die term in a way that cannot be done synchronously.

      Returns DiceTerm

    Protected_roll

    • _roll(options?: object): Promise<number | void>
      Protected

      Generate a roll result value for this DiceTerm based on its fulfillment method.

      Parameters

      • Optionaloptions: object = {}

        Options forwarded to the fulfillment method handler.

      Returns Promise<number | void>

      Returns a Promise that resolves to the fulfilled number, or undefined if it could not be fulfilled.

    Static_applyCount

    • _applyCount(
          results: any,
          comparison: any,
          target: any,
          __namedParameters?: { flagFailure?: boolean; flagSuccess?: boolean },
      ): void

      A reusable helper function to handle the identification and deduction of failures

      Parameters

      • results: any
      • comparison: any
      • target: any
      • __namedParameters: { flagFailure?: boolean; flagSuccess?: boolean } = {}

      Returns void

    Static_applyDeduct

    • _applyDeduct(
          results: any,
          comparison: any,
          target: any,
          __namedParameters?: { deductFailure?: boolean; invertFailure?: boolean },
      ): void

      A reusable helper function to handle the identification and deduction of failures

      Parameters

      • results: any
      • comparison: any
      • target: any
      • __namedParameters: { deductFailure?: boolean; invertFailure?: boolean } = {}

      Returns void

    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

    Static_keepOrDrop

    • _keepOrDrop(
          results: object[],
          number: number,
          options?: { highest?: boolean; keep?: boolean },
      ): object[]

      A helper method to modify the results array of a dice term by flagging certain results are kept or dropped.

      Parameters

      • results: object[]

        The results array

      • number: number

        The number to keep or drop

      • Optionaloptions: { highest?: boolean; keep?: boolean } = {}
        • Optionalhighest?: boolean

          Keep the highest?

        • Optionalkeep?: boolean

          Keep results?

      Returns object[]

      The modified results array

    • A helper comparison function. Returns a boolean depending on whether the result compares favorably against the target.

      Parameters

      • result: number

        The result being compared

      • comparison: string

        The comparison operator in [=,<,<=,>,>=]

      • target: number

        The target value

      Returns boolean

      Is the comparison true?

    • 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

    • Construct a term of this type given a matched regular expression array.

      Parameters

      • match: RegExpMatchArray

        The matched regular expression array

      Returns DiceTerm

      The constructed term

    • 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

    • Determine whether a string expression matches this type of term

      Parameters

      • expression: string

        The expression to parse

      • Optionaloptions: { imputeNumber?: boolean } = {}

        Additional options which customize the match

        • OptionalimputeNumber?: boolean

          Allow the number of dice to be optional, i.e. "d6"

      Returns RegExpMatchArray | null

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods