Introduction

API

The technical API is for people wanting to delve a bit deeper into the parts that make up the library.

• Get set up quickly with the setup guide.
• Roll some dice with notations.

Namespaces

Namespace	Description
ast	Expression tree nodes and notation helpers for inspecting or constructing rolls.
dice	Die definitions, presets, and registries for extending dice notation.
engines	Random engines for controlling how dice are rolled.
errors	Error classes raised while parsing, evaluating, and importing rolls.
modifiers	Modifier definitions, handlers, and registries for extending roll behavior.
presenters	Presenters that format evaluated rolls and their results.
results	Result types and helpers for inspecting evaluated expressions.

Classes

Class	Description
Evaluator	Walks the AST and builds the result tree.
Parser	Parses dice notation into the AST.
Roll	One evaluated notation: the result tree and its totals.
Roller	Rolls notation and keeps a history of the rolls.
RollHistory	A log of rolls.
RollSettings	Resolved RollOptions, with the services built from them.

Interfaces

Interface	Description
EvaluatorRegistries	Registries used to resolve dice and modifier handlers during evaluation.
HistoryData	A roll history.
NumberGenerator	Generates numbers in a range from a RandomEngine.
ParserOptions	Options for parsing notation.
Presenter	Turns a roll, a roll history, or a result node into any output, e.g. text, HTML or Markdown.
RandomEngine	A source of randomness.
RollContext	Everything that changes per roll but isn't part of the notation.
RollData	A roll, with its result tree and totals.
RollLimits	Safety limits for a single roll.
RollOptions	How notation is parsed, rolled and presented. Every option is optional.

Type Aliases

Type Alias	Description
DieLike	A range or faces definition with optional behaviour overrides.
Encoded	The data with every number (except literal ones, like version) as an EncodedNumber.
EncodedExportData	Anything that has been exported.
EncodedHistoryData	An exported roll history: JSON-safe, with non-finite numbers tagged.
EncodedNumber	A number in exported data: a finite number as it is, otherwise a tag, e.g. { "$number": "Infinity" }, so it survives JSON (which would turn it into null).
EncodedRollData	An exported roll: JSON-safe, with non-finite numbers tagged.
ExportFormat	A supported export format.
ExpressionNode	Any node that evaluates to a number.
ExpressionResult	A result for an expression node; individual dice and group members are nested within it.
NonFiniteNumber	The tag names used for non-finite numbers.
Presentable	A roll, history, or evaluated expression result; an individual die result is not presentable.
RollerOptions	Options shared by all rolls made or imported by a roller.
RollMode	How dice are rolled.
TaggedDieResult	A die result carrying an internal pool tag during flattened group modifier handling.

Variables

Variable	Description
EXPORT_FORMATS	- object: plain JSON-safe data (EncodedRollData / EncodedHistoryData) - json: that data as a JSON string - base64: that JSON string, base64-encoded (UTF-8)
NON_FINITE_NUMBERS	The numbers JSON can't represent, by their tag.

Functions

Function	Description
roll	Shorthand for new Roll(input, options): rolls notation (or an AST) once, without a history.