@3d-dice/dice-roller-parser 中文文档教程

Question

Dice Roller & Parser

这个掷骰子是一个字符串解析器，它返回一个包含掷骰子组成部分的对象。 它支持完整的Roll20 骰子规范。 它使用 pegjs 语法来创建骰子滚动格式的表示< /a>。 然后可以将其转换为简单的数值，或转换为用于显示完整滚动详细信息的复杂对象。

Credit

这是 Ben Morton 的 dice_roller 项目的分支。 它有一些错误，所以我重新发布了我的项目所需的修复和功能。

Quickstart

使用以下方法安装库：

npm install dice-roller-parser

安装后，只需在浏览器中加载库：

<script src="node_modules/dice-roller-parser/dist/index.js"></script>

或在节点中：

import { DiceRoller } from "dice-roller-parser";

然后创建 DiceRoller 的新实例类，并用它来进行一些骰子掷骰。

const diceRoller = new DiceRoller();

//    Returns the total rolled value
const roll = diceRoller.rollValue("2d20kh1");
console.log(roll);

//    Returns an object representing the dice roll, use to display the component parts of the roll
const rollObject = diceRoller.roll("2d20kh1");
console.log(rollObject.value);

Usage

这个库公开了两个类，DiceRoller 和 DiscordRollRenderer。

DiceRoller

DiceRoller 类管理骰子字符串的解析并根据结果执行掷骰。

//    Creates a new instance of the DiceRoller class
const roller = new DiceRoller();

Constructor options

默认构造函数使用 Math.random 并应用每个骰子的最大掷骰数 1000。这些可以使用以下构造函数重载指定。

DiceRoller(GeneratorFunction)

您可以指定一个函数作为掷骰器的随机数生成器。 这个函数应该是 () => 类型的。 number 并返回一个介于 0 和 1 之间的数字。默认情况下，它使用内置的 Math.random 方法。

//    Default constructor using Math.random
const roller = new DiceRoller();

//    Uses a custom random generator that always returns 0.5
const roller = new DiceRoller(() => 0.5);

这可以使用 randFunction 属性读取或修改。

roller.randFunction = () => 0.5;

DiceRoller(GeneratorFunction, MaxRollsPerDie)

为了防止尝试解析大量的骰子，可以指定一个骰子的最大掷骰数。 默认值设置为 1000。

//    Uses the default constructor with a limit of 100 rolls per die
const roller = new DiceRoller(null, 100);

//    Uses a custom random generator that always returns 0.5, and a limit of 10 rolls per die
const roller = new DiceRoller(() => 0.5, 10);

这可以使用 maxRollCount 属性读取或修改。

roller.maxRollCount = 75;

Class Usage

类，就可以通过三个选项来执行掷骰子：

• Getting a roll result directly
• Generate an object to represent the dice roll
• Just parse the input and add your own rolling logic

Getting a direct roll result

一旦构造了 DiceRoller 计算出的数值结果。

//    Rolls 2 d20 dice and keeps the value of the highest
const roll = roller.rollValue("2d20kh1");

//    Prints out the numeric value result
console.log(roll);

Generate an object representing the dice roll

roll 方法接受骰子字符串输入，对其进行解析，执行掷骰，然后返回表示掷骰的对象。 使用滚动对象，您可以构建自己的滚动显示功能，而不仅仅是输出最终值。

//    Rolls 2 d20 dice and keeps the value of the highest
const roll = roller.roll("2d20kh1");

//    Print out the full roll breakdown
printDiceRoll(roll);
//    Prints out the numeric value result
console.log(`Final roll value: ${roll.Value}`);

有关返回对象的更多详细信息，请参阅下面输出类型部分中的滚动结果输出 .

Just parse the value

parse 方法接受骰子字符串输入，对其进行解析并返回已解析输入的表示形式。 这可以用于执行掷骰子或重新构建原始输入。 rollParsed 方法将此解析结果作为输入，执行掷骰并返回与 相同的输出roll 方法。

//    Rolls 2 d20 dice and keeps the value of the highest
const parsedInput = roller.parse("2d20kh1");

//    Print out a re-constructed input string
printParsedInput(parsedInput);

//    Run the roller on the parsed object
const roll = roller.rollParsed(parsedInput);

//    Print out the full roll breakdown
printDiceRoll(roll);
//    Print out the numeric value result
console.log(`Final roll value: ${roll.Value}`);

有关返回对象的更多详细信息，请参阅下面输出类型部分中的解析的滚动输出 .

DiscordRollRenderer

DiscordRollRenderer 类是一个示例渲染器类，它接受由 RollBase 对象表示的滚动输入并将其渲染到降价格式的字符串，与 Discord 兼容。

//    Creates a new instance of the DiceRoller class
const renderer = new DiscordRollRenderer();

Class Usage

DiscordRollRenderer 公开了一个带有单个参数的 render 方法，RollBase 对象到渲染，并返回渲染后的字符串。

//    Rolls 2 d20 dice and keeps the value of the highest
const roll = roller.rollValue("2d20kh1");

//    Get the formatted string
const render = renderer.render(roll);
console.log(render);

Development

要开发这个库，只需克隆存储库，运行安装：

npm install

然后进行构建：

npm run build

这会做四件事：

# Clean any existing builds
npm run clean

# Build the dice grammer
npx pegjs src/diceroll.pegjs

# Run tslint against the project
tslint -c tslint.json --project tsconfig.json

# Then run webpack to build and package everything up nicely
webpack

要运行测试套件，请使用：

npm run test

仅此而已！

Output Types

以下对象类型是 DiceRoller 类的输出，可用作 typescript 用户的接口。

Roll Result Output

滚动结果返回的对象由以下类型组成。

RollBase

所有掷骰子的基类，基于 type 属性进行扩展。

Property	Type	Description
success	boolean	Was the roll a success, for target number rolls. Example: 3d6 > 3
type	RollType	The type of roll that this object represents.
valid	boolean	Is the roll still valid, and included in calculations.
value	number	The rolled or calculated value of this roll.
label	string	The display label for this roll. This property is optional.
order	number	A property used to maintain ordering of dice rolls within groups.

RollType

有效类型的 roll 的枚举。 可能的值是：

• "number"
• "diceexpressionroll"
• "expressionroll"
• "mathfunction"
• "grouproll"
• "fate"
• "die"
• "roll"
• "fateroll"

GroupedRoll

为骰子组扩展的中间接口。 此接口扩展 RollBase。

Property	Type	Description
dice	Array<RollBase>	The rolls included as part of this group.

DiceExpressionRoll

骰子表达式的表示。 此接口扩展 GroupedRoll。

示例

2d20 + 6d6

Property	Type	Description
type	"diceexpressionroll"	The type of roll that this object represents.
ops	Array<DiceGroupMathOperation>	The operations to perform on the rolls.

ExpressionRoll

数学表达式的表示。 此接口扩展 GroupedRoll。

示例

20 * 17

Property	Type	Description
type	"expressionroll"	The type of roll that this object represents.
ops	Array<MathOperation>	The operations to perform on the rolls.

MathFunctionRoll

数学函数的表示。 此接口扩展 RollBase。

Example

floor(20 / 17)

Property	Type	Description
type	"expressionfunc"	The type of roll that this object represents.
op	MathFunction	The operations to perform on the rolls.
expr	RollBase	The expression that the function is applied upon.

GroupRoll

一组卷的表示

Example

{4d6,3d6}。 此接口扩展 GroupedRoll。

Property	Type	Description
type	"grouproll"	The type of roll that this object represents.

DiceRollResult

一组骰子的滚动结果。 此接口扩展 RollBase。

示例

6d20

Property	Type	Description
die	RollBase	The die this result represents.
type	"die"	The type of roll that this object represents.
rolls	DieRollBase[]	Each roll of the die.
count	RollBase	The number of rolls of the die.
matched	boolean	Whether this is a match result.

DieRollBase

为单个掷骰子扩展的中间接口（见下文）。 此接口扩展 RollBase。

Property	Type	Description
roll	number	The rolled result of the die.
matched	boolean	Whether this roll is a match.

DieRoll

在普通模具上滚动。 此接口扩展 DieRollBase。

示例

d20 掷骰子

Property	Type	Description
die	number	The die number to be rolled.
type	"roll"	The type of roll that this object represents.
critical	CriticalType	If this role is a critical success or failure (for rendering).

FateDieRoll

。 此接口扩展 DieRollBase。

示例

dF

Property	Type	Description
type	"fateroll"	The type of roll that this object represents.

Parsed Roll Output

以下接口由库公开为已解析输入字符串的重新表示。 parse 方法的响应是一个 RootType 对象，可以是扩展它的任何接口。

ParsedObjectType

有效类型的 roll 的枚举。 可能的值是：

• "number"
• "inline"
• "success"
• "failure"
• "crit"
• "critfail"
• "match"
• "keep"
• "drop"
• "group"
• "diceExpression"
• "sort"
• "explode"
• "compound"
• "penetrate"
• "reroll"
• "rerollOnce"
• "target"
• "die"
• "fate"
• "expression"
• "math"
• "mathfunction"

ParsedType

这是所有解析类型的基本接口。

Property	Type	Description
type	string	The type of parsed item this object represents.

RootType

这是解析类型子集的基本接口，只有那些可以是根类型的类型。 该对象扩展了 ParsedType 接口。

Property	Type	Description
label?	string	The text label attached to this roll. This property is optional.
root	boolean	A boolean flag to indicate if this is the root of the parse tree.

NumberType

此对象表示输入中的单个数字。 此对象扩展了 RootType 接口。

Property	Type	Description
type	"number"	The type of parsed item this object represents.
value	number	The value of the number.

InlineExpression

此对象表示字符串中的内联骰子表达式，用双方括号括起来。 此对象扩展了 RootType 接口。

示例

我想掷 [[2d20]] 骰子

Property	Type	Description
type	"inline"	The type of parsed item this object represents.
expr	Expression	The expression that was parsed as the inline string.

AnyRoll

表示任何有效掷骰的组合类型。 这是以下类型的组合：

• GroupedRoll
• FullRoll
• NumberType

ModGroupedRoll

该对象表示带有可选修饰符的分组卷。 此对象扩展了 RootType 接口。

示例

{4d6+3d8}kh1

Property	Type	Description
mods	Array<KeepDropModType,SuccessFailureModType>	The modifiers to be applied to the grouped roll.

SuccessFailureCritModType

表示成功测试修饰符的对象。 该对象扩展了 ParsedType 接口。 "success" 或 "failure" 修饰符将结果转换为成功类型结果，返回满足目标的掷骰数。 “crit” 或 “critfail” 修饰符测试掷骰是否应显示为关键成功或关键失败。

示例

成功：3d6>3 失败：3d6f<3

Property	Type	Description
type	"success", "failure", "crit", "critfail"	The type of parsed item this object represents.
mod	CompareOperation	The check type to use for the condition.
expr	RollExpression	An expression representing the success condition.

SuccessFailureModType

等同于 SuccessFailureCritModType 但仅支持“成功”和“失败”修饰符。 此对象扩展了 SuccessFailureCritModType 接口。

示例

成功：3d6>3 失败：3d6f<3

Property	Type	Description
type	"success", "failure"	The type of parsed item this object represents.
mod	CompareOperation	The check type to use for the condition.
expr	RollExpression	An expression representing the success condition.

MatchModType

表示匹配类型修饰符的对象，用于修改 roll20 中骰子输出的显示。 该对象扩展了 ParsedType 接口。

示例

2d6m

与mt 扩展一起使用时，将返回找到的匹配项数。

示例

20d6mt

可以指定额外的参数来增加所需的匹配数或向匹配添加约束。

示例

20d6mt3 计算 3 个项目的匹配项

示例

20d6m>3 仅计算滚动值为 >; 的匹配项 3

Property	Type	Description
type	"match"	The type of parsed item this object represents.
min	NumberType	The minimum number of matches to accept. This property defaults to 2 as a NumberType.
count	boolean	Whether or not to count the matches.
mod?	CompareOperation	The check type to use for the match condition, if specified. This field is optional.
expr?	RollExpression	An expression representing the match condition, if specified. This field is optional.

KeepDropModType

表示保留或丢弃修饰符的对象，指定要保留或丢弃的骰子掷骰数，最高或最低掷骰数。 该对象扩展了 ParsedType 接口。

示例

保留：2d20kh1 Drop: 2d20dl1

Property	Type	Description
type	"keep", "drop"	The type of parsed item this object represents.
highlow	HighLowType	Whether to keep/drop the highest or lowest roll.
expr	RollExpression	An expression representing the number of rolls to keep/drop. This property defaults to 1 as a NumberType. Example: 2d6

GroupedRoll

这个对象代表一组组合的卷，带有可选的修饰符。 此对象扩展了 ModGroupedRoll 接口。

示例

{2d6,3d6}

Property	Type	Description
type	"group"	The type of parsed item this object represents.
rolls	Array<RollExpression>	The group of rolls included in this group.

RollExpressionType

表示包含复杂滚动和组的滚动表达式的对象，只允许进行加法运算。 此对象扩展了 RootType 接口。

示例

{2d6,3d6}kh1 + {3d6 + 2d6}kh2

Property	Type	Description
head	RollOrExpression	The initial roll or expression for the roll expression.
type	"diceExpression"	The type of parsed item this object represents.
ops	Array<MathType<RollOrExpression,DiceGroupMathOperation>>	The operations to apply to the initial roll or expression.

RollExpression

复杂滚动表达式、滚动或数学表达式的辅助类型组合。 表示以下类型：

• RollExpressionType
• RollOrExpression

RollOrExpression

roll 或数学表达式的辅助类型组合。 表示以下类型：

• FullRoll
• Expression

FullRoll

表示掷骰子的对象，包括掷骰子和任何修改器。 该对象扩展了 DiceRoll 接口。

示例

2d6kh1

Property	Type	Description
mods?	Array<ReRollMod,KeepDropModType>	Any modifiers attached to the roll. This property is optional.
targets?	Array<SuccessFailureCritModType>	Any success or failure targets for the roll. This property is optional.
match?	MatchModTyp	Any match modifiers for the roll. This property is optional.
sort?	SortRollType	Any sort operations to apply to the roll. This property is optional.

SortRollType

应用于滚动的排序操作。 该对象扩展了 ParsedType 接口。

示例

10d6sa

Property	Type	Description
type	"sort"	The type of parsed item this object represents.
asc	boolean	Whether to sort ascending or descending.

ReRollMod

表示应用于掷骰的重新掷骰操作的对象。 可以是以下类型之一：

• "explode": re-rolls any dice that meet the target, continuing if the new roll matches
• "compound": re-rolls any dice that meet the target, continuing if the new roll matches and adding the results into a single roll
• "penetrate": re-rolls any dice that meet the target subtracting 1 from the new value, continuing if the new roll matches
• "reroll": re-rolls a die as long as it meets the target, keeping the final roll
• "rerollOnce": re-rolls a die once if it meets the target, keeping the new roll

Example

2d6!

Property	Type	Description
type	"explode", "compound", "penetrate", "reroll", "rerollOnce"	The type of parsed item this object represents.
target	TargetMod	The target modifier to compare the roll value against.

TargetMod

一个对象 represt 一个目标修饰符以应用于一个 roll。 该对象扩展了 ParsedType 接口。

Property	Type	Description
type	"target"	The type of parsed item this object represents.
mod	CompareOperation	The check type to use for the condition.
value	RollExpr	An expression representing the target condition value.

DiceRoll

掷骰子的表示。 此对象扩展了 RootType 接口。

示例

2d6

Property	Type	Description
die	RollExpr,FateExpr	The die value to roll against, can be a fate die, a number or a complex roll expression.
count	RollExpr	The number of time to roll this die.
type	"die"	The type of parsed item this object represents.

FateExpr

命运骰子的表示。 该对象扩展了 ParsedType 接口。

示例

2dF

Property	Type	Description
type	"fate"	The type of parsed item this object represents.

RollExpr

不是表达式的数字或值的辅助类型组合。 表示以下类型：

• MathExpression
• NumberType

Expression

表达式类型的辅助类型组合。 表示以下类型：

• InlineExpression
• MathExpression

MathExpression

两个或多个骰子掷骰之间的数学类型表达式。 此对象扩展了 RootType 接口。

示例

2d6 + 3d6 * 4d6

Property	Type	Description
head	AnyRoll	The initial roll to perform operations against.
type	"expression"	The type of parsed item this object represents.
ops	Array<MathType<AnyRoll>>	The operations to apply to the initial roll.

MathType

表示要应用的滚动数学运算的对象及其应用的值。 该对象扩展了 ParsedType 接口。 此对象的接口采用模板化类型 TailType，它指定操作中使用的第二个值的类型。 还有第二个模板化类型 OpValues，它指定可以使用的操作类型。 这默认为 Array<MathOperation>`。

示例

+ 3d6（作为 2d6 + 3d6 的一部分）

Property	Type	Description
type	"math"	The type of parsed item this object represents.
op	OpValues	The math operation to perform.
tail	TailType	The second value to use in the operation.

MathFunctionExpression

表示要应用的数学函数的对象以及要应用它的表达式。 此对象扩展了 RootType 接口。

示例

floor(3d6 / 2d4)

Property	Type	Description
type	"mathfunction"	The type of parsed item this object represents.
op	MathFunction	The function to be applied.
expr	AnyRoll	The expression to apply the function on.

Helper Types

以下是上述接口使用的支持类型。

DiceGroupMathOperation

表示一组骰子上数学运算的有效运算的辅助类型。

<代码>"+" | “-”

MathOperation

表示数学运算的有效运算的辅助类型。

<代码>"+" | “-” | “*” | “/” | “％” | "**"

MathFunction

表示数学运算的有效运算的辅助类型。

<代码>“地板” | “天花板” | “圆” | “abs”

CriticalType

将掷骰标记为关键成功或失败时使用的辅助类型。

<代码>“成功” | “失败” | null

CompareOperation

比较点的可用操作的辅助类型。

<代码>">" | “<” | "="

HighLowType

一种辅助类型，用于确定要保留或丢弃哪些卷。

<代码>“h” | “我” | 空