Class DiceTerm

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

Hierarchy (View Summary)

Constructors

constructor

Properties

_root isIntermediate 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 method 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

constructor

  • new DiceTerm(
        termData: {
            faces?: number | Roll;
            method: string;
            modifiers?: string[];
            number?: number | Roll;
            options?: object;
            results?: DiceTermResult[];
        },
    ): DiceTerm

    Parameters

    • termData: {
          faces?: number | Roll;
          method: string;
          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.

      • 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

isIntermediate: boolean = false

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

modifiers

modifiers: string[]

An Array of dice term modifiers which are applied

options

options: object

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

results

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.

StaticDENOMINATION

DENOMINATION: string = ""

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

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

StaticMODIFIER_REGEXP

MODIFIER_REGEXP: RegExp = ...

A regular expression used to separate individual modifiers

StaticMODIFIERS

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

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

StaticMODIFIERS_REGEXP_STRING

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

StaticREGEXP

REGEXP: RegExp = ...

A regular expression used to match a term of this type

StaticSERIALIZE_ATTRIBUTES

SERIALIZE_ATTRIBUTES: string[] = ...

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

Accessors

denomination

  • get denomination(): string

    The denomination of this DiceTerm instance.

    Returns string

dice

  • get dice(): DiceTerm[]

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

    Returns DiceTerm[]

expression

  • get expression(): string

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

    Returns string

faces

  • 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

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

method

  • get method(): string

    The resolution method used to resolve this DiceTerm.

    Returns string

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

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

  • alter(multiply: number, add: number): DiceTerm

    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

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

getResultCSS

  • getResultCSS(result: DiceTermResult): (null | string)[]

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

    Parameters

    Returns (null | string)[]

    The desired classes

getResultLabel

  • getResultLabel(result: DiceTermResult): string

    Return a string used as the label for each rolled result

    Parameters

    Returns string

    The result label

getTooltipData

  • getTooltipData(): object

    Render the tooltip HTML for a Roll instance

    Returns object

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

mapRandomFace

  • mapRandomFace(randomUniform: number): number

    Maps a randomly-generated value in the interval [0, 1) to a face value on the die.

    Parameters

    • randomUniform: number

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

    Returns number

    The face value.

randomFace

  • randomFace(): number

    Generate a random face value for this die using the configured PRNG.

    Returns number

roll

  • roll(
        options?: { maximize?: boolean; minimize?: boolean },
    ): Promise<DiceTermResult>

    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

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

StaticcompareResult

  • compareResult(result: number, comparison: string, target: number): boolean

    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?

StaticfromData

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

StaticfromMatch

  • fromMatch(match: RegExpMatchArray): DiceTerm

    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

StaticfromParseNode

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

StaticmatchTerm

  • matchTerm(
        expression: string,
        options?: { imputeNumber?: boolean },
    ): null | RegExpMatchArray

    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 null | RegExpMatchArray

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods