# @3d-dice/dice-roller-parser 中文文档

规范地址：https://npmcn.com/package/%403d-dice/dice-roller-parser/

版本：0\.2\.6
npm 元数据更新时间：2022-05-26T16:45:05.710Z
中文译文更新时间：2026-11-06T08:50:02.263Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%403d-dice/dice-roller-parser
原文对照：https://npmcn.com/package/%403d-dice/dice-roller-parser/?lang=original
项目主页：https://github.com/3d-dice/dice-roller-parser#readme
源码仓库：https://github.com/3d-dice/dice-roller-parser

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：278 kB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2021-09-14T16:33:01.622Z
- 最新版本发布：2022-05-26T16:45:05.643Z
- 近 30 天下载量：3725（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 0 个）

## 中文简介

一个 Javascript 骰子滚动器, 用于解析 roll20 格式字符串并生成滚动输出

## 安装

```sh
npm install @3d-dice/dice-roller-parser
```

也可以使用：`pnpm add @3d-dice/dice-roller-parser`、`yarn add @3d-dice/dice-roller-parser`、`bun add @3d-dice/dice-roller-parser`

## README

# 骰子滚盘和解析器

这个骰子滚盘是一个字符串解析器,它返回一个包含骰子滚盘组件的物体. 它支持充分的 [卷20 剂量规格](https://roll20.zendesk.com/hc/en-us/articles/360037773133-Dice-Reference#DiceReference-Roll20DiceSpecification)它使用 [标签](https://github.com/pegjs/pegjs) 创建一个 [骰子滚动格式的表示](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-parsed-roll-output),然后可以将其转换成一个简单的数字值,或者转换为一个 [复杂对象](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-roll-result-output) 用于显示全卷的细节.

## 信贷

这是本·莫顿的叉子 [骰子滚动器](https://github.com/BTMorton/dice_roller) 项目。 它有几只虫子,所以我正在重排 我的项目所需的修复和特性.

## 快速启动

使用 :

```bash
npm install dice-roller-parser
```

安装后, 只需在浏览器中加载库 :

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

或在节点:

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

然后创建一个新的实例 [`DiceRoller`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-DiceRoller) 表演骰子卷.

```javascript
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);
```

## 使用量

这个图书馆有两门课 [`DiceRoller`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-DiceRoller) (单位:千美元) [`DiscordRollRenderer`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-DiscordRollRenderer)。 。 。 .

### `DiceRoller`

这个 `DiceRoller` class 管理骰子字符串的解析,并根据结果执行滚动.

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

#### 构造选项

默认构造器使用 `Math.random` 并应用最高卷数每死1000. 这些可以使用下列构造器超载来指定.

##### `DiceRoller(GeneratorFunction)`

您可以指定一个函数, 以骰子滚筒作为随机数生成器 。 此函数应为类型 `() => number` 并返回 0 到 1 之间的数字。 默认使用内置 `Math.random` 方法.

```javascript
//	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` 属性.

```javascript
roller.randFunction = () => 0.5;
```

##### `DiceRoller(GeneratorFunction, MaxRollsPerDie)`

为防止试图剖析出数量非常多的死卷,可以指定死卷的最大数量. 默认值设定为 1000 .

```javascript
//	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` 属性.

```javascript
roller.maxRollCount = 75;
```

#### 类用法

一旦 `DiceRoller` 已经构建了类, 执行骰子卷有三种选项:

-   直接获得滚动结果
-   生成一个代表骰子卷的对象
-   只要解析输入并添加自己的滚动逻辑

##### 获得直接滚动结果

这个 `rollValue` 方法需要骰子字符串输入,解析,执行一卷并返回计算出的数字值结果.

```javascript
//	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);
```

##### 生成一个代表骰子滚的物体

这个 `roll` 方法需要骰子字符串输入,解析,执行一卷并返回代表一卷的物体。 使用滚动对象可以构建出自己的滚动显示功能,而不只是输出出最终值.

```javascript
//	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}`);
```

见 [滚动结果产出](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-roll-result-output) 输入 [输出类型](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-output-types) 关于返回对象的更详细情况,请在下面一节中说明.

##### 只要分析一下值

这个 `parse` 方法使用骰子字符串输入,解析并返回解析后输入的表示。 这可以用来进行骰子卷或重新构建原始输入. 这个 `rollParsed` 方法将此解析结果作为输入,执行卷并返回与输出相同的 [`roll`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-generate-an-object-representing-the-dice-roll) 方法.

```javascript
//	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}`);
```

见 [解析卷输出](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-parsed-roll-output) 输入 [输出类型](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-output-types) 关于返回对象的更详细情况,请在下面一节中说明.

### `DiscordRollRenderer`

这个 `DiscordRollRenderer` class 是实例渲染器类,它使用滚动输入,以一个 [`RollBase`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollBase) 对象并将其以下标格式变成与Discord兼容的字符串.

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

#### 类用法

这个 `DiscordRollRenderer` 暴露一个单身 `render` 使用单一参数的方法 [`RollBase`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollBase) 对象可渲染,并返回已渲染的字符串.

```javascript
//	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);
```

## 发展

要开发此库, 只需复制寄存器, 运行一个安装 :

```bash
npm install
```

然后做一个建:

```bash
npm run build
```

这有四件事:

```bash
# 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
```

要运行测试套件,请使用:

```bash
npm run test
```

就是这样!

## 输出类型

以下对象类型是来自 [`DiceRoller`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-DiceRoller) 类,并可作为排字用户的界面.

### 滚动结果输出

以卷式结果返回的对象由下列类型组成.

#### `RollBase`

根据类型属性扩展所有死活的基类.

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 成功 | `boolean` | 卷子是成功的, 对于目标数卷。 示例 `3d6 > 3` |
| 类型 | [`RollType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollType) | 此对象所代表的卷轴类型 . |
| 无效 | `boolean` | 卷子是否仍然有效,并包括在计算中. |
| 价值 | `number` | 本卷的滚动或计算值. |
| 标签 | `string` | 本卷的显示标签 。 此地产可选. |
| 顺序 | `number` | 用来在组内维持骰子滚的订单的财产. |

#### `RollType`

有效卷的圆柱. 可能的价值是:

-   `"number"`
-   [`"diceexpressionroll"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-DiceExpressionRoll)
-   [`"expressionroll"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-ExpressionRoll)
-   [`"mathfunction"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-MathFunctionRoll)
-   [`"grouproll"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-GroupRoll)
-   `"fate"`
-   [`"die"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-DiceRollResult)
-   [`"roll"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-DieRoll)
-   [`"fateroll"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-FateDieRoll)

#### `GroupedRoll`

为骰子组扩展的中间接口 。 此接口扩展 [`RollBase`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollBase)。 。 。 .

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 骰子 | `Array<`[`RollBase`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollBase)`>` | 卷入为本组. |

#### `DiceExpressionRoll`

表示骰子表达式. 此接口扩展 [`GroupedRoll`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-GroupedRoll)。 。 。 .

**示例**

> `2d20 + 6d6`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 类型 | `"diceexpressionroll"` | 此对象所代表的卷轴类型 . |
| 行动 | `Array<`[`DiceGroupMathOperation`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-DiceGroupMathOperation)`>` | 运行在卷上. |

#### `ExpressionRoll`

一个数学表达式的体现. 此接口扩展 [`GroupedRoll`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-GroupedRoll)。 。 。 .

**示例**

> `20 * 17`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 类型 | `"expressionroll"` | 此对象所代表的卷轴类型 . |
| 行动 | `Array<`[`MathOperation`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-MathOperation)`>` | 运行在卷上. |

#### `MathFunctionRoll`

数学功能的体现. 此接口扩展 [`RollBase`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollBase)。 。 。 .

**示例**

> `floor(20 / 17)`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 类型 | `"expressionfunc"` | 此对象所代表的卷轴类型 . |
| 执行 | [`MathFunction`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-MathFunction) | 运行在卷上. |
| 外观 | [`RollBase`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollBase) | 应用函数的表达式 . |

#### `GroupRoll`

代表一组卷

**示例**

> \[4d6,3d6\] (英语). 此接口扩展 [`GroupedRoll`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-GroupedRoll)。 。 。 .

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 类型 | `"grouproll"` | 此对象所代表的卷轴类型 . |

#### `DiceRollResult`

一群骰子的滚出结果 此接口扩展 [`RollBase`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollBase)。 。 。 .

**示例**

> `6d20`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 死亡( e) | [`RollBase`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollBase) | 这个结果意味着死亡. |
| 类型 | `"die"` | 此对象所代表的卷轴类型 . |
| 卷轴 | [`DieRollBase`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-DieRollBase)\[ | 每出一卷死相会. |
| 计数 | [`RollBase`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollBase) | 死生所取之数. |
| 匹配 | `boolean` | 是否这是匹配的结果 . |

#### `DieRollBase`

为个人死亡卷扩展的中间接口(见下文)。 此接口扩展 [`RollBase`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollBase)。 。 。 .

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 滚动 | `number` | 死因的滚动结果. |
| 匹配 | `boolean` | 此卷是否为相. |

#### `DieRoll`

一卷活活活活活活活 此接口扩展 [`DieRollBase`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-DieRollBase)。 。 。 .

**示例**

> `d20`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 死亡( e) | `number` | 死亡数字要滚动. |
| 类型 | `"roll"` | 此对象所代表的卷轴类型 . |
| 关键事项 | [`CriticalType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-CriticalType) | 如果这个角色是关键的成败(用于渲染). |

#### `FateDieRoll`

一卷一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一 此接口扩展 [`DieRollBase`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-DieRollBase)。 。 。 .

**示例**

> `dF`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 类型 | `"fateroll"` | 此对象所代表的卷轴类型 . |

### 解析滚动输出

以下界面被库所曝光,作为解析后输入字符串的重写. 联合国的答复 `parse` 方法是一个 `RootType` 对象,也可以是扩展它的任何接口.

#### `ParsedObjectType`

有效卷的圆柱. 可能的价值是:

-   [`"number"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-NumberType)
-   [`"inline"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-InlineExpression)
-   [`"success"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-SuccessFailureCritModType)
-   [`"failure"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-SuccessFailureCritModType)
-   [`"crit"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-SuccessFailureCritModType)
-   [`"critfail"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-SuccessFailureCritModType)
-   [`"match"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-MatchModType)
-   [`"keep"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-KeepDropModType)
-   [`"drop"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-KeepDropModType)
-   [`"group"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-GroupedRoll)
-   [`"diceExpression"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollExpressionType)
-   [`"sort"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-SortRollType)
-   [`"explode"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-ReRollMod)
-   [`"compound"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-ReRollMod)
-   [`"penetrate"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-ReRollMod)
-   [`"reroll"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-ReRollMod)
-   [`"rerollOnce"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-ReRollMod)
-   [`"target"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-TargetMod)
-   [`"die"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-DiceRoll)
-   [`"fate"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-FateExpr)
-   [`"expression"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-MathExpression)
-   [`"math"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-MathType)
-   [`"mathfunction"`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-MathFunctionExpression)

#### `ParsedType`

这是所有解析类型的基础界面 .

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 类型 | `string` | 此对象所代表的解析项的类型 . |

#### `RootType`

这是子集解析类型的基础界面,只有那些可以作为根类型的. 此对象延伸 [`ParsedType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-ParsedType) 接口.

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 标签? | `string` | 本卷所附文字标签. 此地产可选. |
| 根号 | `boolean` | 一个布尔旗来表示是否这是 parse 树的根 . |

#### `NumberType`

此对象代表输入中的单个数字. 此对象延伸 [`RootType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RootType) 接口.

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 类型 | `"number"` | 此对象所代表的解析项的类型 . |
| 价值 | `number` | 数之所值. |

#### `InlineExpression`

这个对象代表了字符串中的内在骰子表达,用双方括号包裹. 此对象延伸 [`RootType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RootType) 接口.

**示例**

> `I want to roll [[2d20]] dice`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 类型 | `"inline"` | 此对象所代表的解析项的类型 . |
| 外观 | [`Expression`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-Expression) | 被解析为内线字符串的表达式 . |

#### `AnyRoll`

代表任何有效卷的组合类型。 这是以下几种类型的组合:

-   [`GroupedRoll`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-GroupedRoll)
-   [`FullRoll`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-FullRoll)
-   [`NumberType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-NumberType)

#### `ModGroupedRoll`

此对象代表带有可选修饰符的分组卷. 此对象延伸 [`RootType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RootType) 接口.

**示例**

> `{4d6+3d8}kh1`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 模式 | `Array<`[`KeepDropModType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-KeepDropModType)`,`[`SuccessFailureModType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-SuccessFailureModType)`>` | 适用于分组卷的修改语句. |

#### `SuccessFailureCritModType`

一个代表成功测试修饰对象的对象 。 此对象延伸 [`ParsedType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-ParsedType) 接口. A 类 `"success"` 或者说 `"failure"` 修饰器将结果转换成成功类型结果,返回达到目标的卷数. A 类 `"crit"` 或者说 `"critfail"` 修改器测试卷子是否应该显示为关键的成功还是关键失败.

**示例**

> 成功 : `3d6>3` 失败 : `3d6f<3`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 类型 | `"success", "failure", "crit", "critfail"` | 此对象所代表的解析项的类型 . |
| 模式 | [`CompareOperation`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-CompareOperation) | 用于条件的检查类型 . |
| 外观 | [`RollExpression`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollExpression) | 代表成功条件的表达式. |

#### `SuccessFailureModType`

等同于 [`SuccessFailureCritModType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-SuccessFailureCritModType) 但仅支持"成功"和"失败"修饰者. 此对象延伸 [`SuccessFailureCritModType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-SuccessFailureCritModType) 接口.

**示例**

> 成功 : `3d6>3` 失败 : `3d6f<3`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 类型 | `"success", "failure"` | 此对象所代表的解析项的类型 . |
| 模式 | [`CompareOperation`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-CompareOperation) | 用于条件的检查类型 . |
| 外观 | [`RollExpression`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollExpression) | 代表成功条件的表达式. |

#### `MatchModType`

一个代表匹配类型修饰器的物体,用于修改卷20中骰子输出的显示. 此对象延伸 [`ParsedType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-ParsedType) 接口.

**示例**

> `2d6m`

当使用时 `mt` 扩展名,将返回找到的匹配数.

**示例**

> `20d6mt`

还可以指定其他参数来增加所需的匹配次数,或者添加对匹配的限制.

**示例**

> `20d6mt3 counts matches of 3 items`

**示例**

> `20d6m>3 Only counts matches where the rolled value is > 3`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 类型 | `"match"` | 此对象所代表的解析项的类型 . |
| 分钟 | [`NumberType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-NumberType) | 要接受的最小匹配数 。 此属性默认为 2 a [`NumberType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-NumberType)。 。 。 . |
| 计数 | `boolean` | 是否计算匹配 . |
| 摩德吗? | [`CompareOperation`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-CompareOperation) | 如果指定了匹配条件的检查类型 。 此字段可选 . |
| 爱普尔? | [`RollExpression`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollExpression) | 如果指定, 表示匹配条件的表达式 。 此字段可选 . |

#### `KeepDropModType`

代表保存或投放调制器的物体,指定要保存或投放的骰子卷数,可以指最高或最低的卷数. 此对象延伸 [`ParsedType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-ParsedType) 接口.

**示例**

> 保留 : `2d20kh1` 丢入 : `2d20dl1`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 类型 | `"keep", "drop"` | 此对象所代表的解析项的类型 . |
| 高调 | [`HighLowType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-HighLowType) | 是否保留/ 投放最高或最低卷 . |
| 外观 | [`RollExpression`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollExpression) | 表示要保存/ 滴入的卷数的表达式 。 此属性默认为 1 [`NumberType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-NumberType)示例: `2d6` |

#### `GroupedRoll`

这个对象代表一组卷子组合,带有可选的修饰符. 此对象延伸 [`ModGroupedRoll`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-ModGroupedRoll) 接口.

**示例**

> `{2d6,3d6}`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 类型 | `"group"` | 此对象所代表的解析项的类型 . |
| 卷轴 | `Array<`[`RollExpression`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollExpression)`>` | 本组所收卷. |

#### `RollExpressionType`

代表卷式表达式的对象,包括复杂的卷和组,只允许添加操作. 此对象延伸 [`RootType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RootType) 接口.

**示例**

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

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 头 | [`RollOrExpression`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollOrExpression) | 出自"活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活. |
| 类型 | `"diceExpression"` | 此对象所代表的解析项的类型 . |
| 行动 | `Array<`[`MathType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-MathType)`<`[`RollOrExpression`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollOrExpression)`,`[`DiceGroupMathOperation`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-DiceGroupMathOperation)`>>` | 适用于初始卷或表达式的操作. |

#### `RollExpression`

复合卷式表达式,卷式或数学表达式的帮助者类型组合. 下列类型:

-   [`RollExpressionType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollExpressionType)
-   [`RollOrExpression`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollOrExpression)

#### `RollOrExpression`

帮助者类型组合一卷,或数学表达式. 下列类型:

-   [`FullRoll`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-FullRoll)
-   [`Expression`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-Expression)

#### `FullRoll`

代表一卷(包括骰子卷)和任何修饰器的物体。 此对象延伸 [`DiceRoll`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-DiceRoll) 接口.

**示例**

> `2d6kh1`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 摩德吗? | `Array<`[`ReRollMod`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-ReRollMod)`,`[`KeepDropModType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-KeepDropModType)`>` | 任何附卷之修饰. 此地产可选. |
| 目标? | `Array<`[`SuccessFailureCritModType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-SuccessFailureCritModType)`>` | 任何成功或失败的目标 滚动。 此地产可选. |
| 比赛? | [`MatchModTyp`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-MatchModTyp) | 任何匹配的修改器的卷。 此地产可选. |
| 有点? | [`SortRollType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-SortRollType) | 任何类型的操作 适用于卷。 此地产可选. |

#### `SortRollType`

用于卷的排序操作 。 此对象延伸 [`ParsedType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-ParsedType) 接口.

**示例**

> `10d6sa`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 类型 | `"sort"` | 此对象所代表的解析项的类型 . |
| 资产c | `boolean` | 是否排序升降. |

#### `ReRollMod`

代表重滚动操作的物体,适用于卷。 可以是下列类型之一:

-   `"explode"`: 重新滚动任何符合目标的骰子, 如果新卷匹配则继续
-   `"compound"`: 重新滚动任何符合目标的骰子, 如果新卷匹配的话继续, 并将结果添加到单卷中
-   `"penetrate"`: 将任何符合目标的骰子从新值中减去1, 如果新卷匹配则继续
-   `"reroll"`:只要达到目标,就重新滚动死亡,保留最后的卷
-   `"rerollOnce"`:如果达到目标,则重新滚动一次死亡,保留新卷

**示例**

> `2d6!`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 类型 | `"explode", "compound", "penetrate", "reroll", "rerollOnce"` | 此对象所代表的解析项的类型 . |
| 目标 | [`TargetMod`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-TargetMod) | 目标修饰以比较卷取值. |

#### `TargetMod`

对象重写目标修饰器以适用于卷. 此对象延伸 [`ParsedType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-ParsedType) 接口.

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 类型 | `"target"` | 此对象所代表的解析项的类型 . |
| 模式 | [`CompareOperation`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-CompareOperation) | 用于条件的检查类型 . |
| 价值 | [`RollExpr`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollExpr) | 表示目标条件值的表达式 . |

#### `DiceRoll`

代表死亡一卷。 此对象延伸 [`RootType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RootType) 接口.

**示例**

> `2d6`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 死亡( e) | [`RollExpr`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollExpr)`,`[`FateExpr`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-FateExpr) | 倒转的去死值,可以是命中注定的去死,一个数字或者一个复杂的去死来表示. |
| 计数 | [`RollExpr`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RollExpr) | 卷出这个的时数会死. |
| 类型 | `"die"` | 此对象所代表的解析项的类型 . |

#### `FateExpr`

代表命运的活活 此对象延伸 [`ParsedType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-ParsedType) 接口.

**示例**

> `2dF`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 类型 | `"fate"` | 此对象所代表的解析项的类型 . |

#### `RollExpr`

一个非表达式的由数字或值组成的帮助者类型组合. 下列类型:

-   [`MathExpression`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-MathExpression)
-   [`NumberType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-NumberType)

#### `Expression`

表达式类型的帮助者类型组合. 下列类型:

-   [`InlineExpression`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-InlineExpression)
-   [`MathExpression`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-MathExpression)

#### `MathExpression`

两个或两个以上骰子滚相间的数学类型表达. 此对象延伸 [`RootType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RootType) 接口.

**示例**

> `2d6 + 3d6 * 4d6`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 头 | [`AnyRoll`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-AnyRoll) | 初一卷来进行行动. |
| 类型 | `"expression"` | 此对象所代表的解析项的类型 . |
| 行动 | `Array<`[`MathType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-MathType)`<`[`AnyRoll`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-AnyRoll)`>>` | 适用于初卷的操作. |

#### `MathType`

一个对象代表要应用的滚动数学操作以及应用它的值. 此对象延伸 [`ParsedType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-ParsedType) 接口. 此对象的界面需要模板类型 `TailType` 指定操作中使用的第二个值的类型. 有第二个模板类型 `OpValues` 指定可以使用的操作类型。 此默认为 `Array<`[`MathOperation`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-MathOperation)\>\`.

**示例**

> `+ 3d6 (as part of 2d6 + 3d6)`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 类型 | `"math"` | 此对象所代表的解析项的类型 . |
| 执行 | `OpValues` | 要执行的数学操作. |
| 尾声 | `TailType` | 操作中使用的第二个值 . |

#### `MathFunctionExpression`

表示要应用的数学函数的对象和用于应用的表达式。 此对象延伸 [`RootType`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-RootType) 接口.

**示例**

> `floor(3d6 / 2d4)`

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 类型 | `"mathfunction"` | 此对象所代表的解析项的类型 . |
| 执行 | [`MathFunction`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-MathFunction) | 要应用的函数 . |
| 外观 | [`AnyRoll`](https://npmcn.com/package/%403d-dice/dice-roller-parser/#readme-AnyRoll) | 应用此函数的表达式 . |

### 帮助类型

以下为上述接口所使用的支持类型.

#### `DiceGroupMathOperation`

表示一组骰子上数学操作的有效操作的助手类型 .

> `"+" | "-"`

#### `MathOperation`

一个代表数学操作中有效操作的助手类型.

> `"+" | "-" | "*" | "/" | "%" | "**"`

#### `MathFunction`

一个代表数学操作中有效操作的助手类型.

> `"floor" | "ceil" | "round" | "abs"`

#### `CriticalType`

在将卷标为关键成败时使用的帮助类型.

> `"success" | "failure" | null`

#### `CompareOperation`

用于比较点的可用操作的帮助类型 .

> `">" | "<" | "="`

#### `HighLowType`

用于确定要保存或放下的卷的帮助类型 .

> `"h" | "l" | null`

## 常见问题

### @3d-dice/dice-roller-parser 是什么？

一个 Javascript 骰子滚动器, 用于解析 roll20 格式字符串并生成滚动输出

### 如何安装 @3d-dice/dice-roller-parser？

在项目目录运行 npm install @3d-dice/dice-roller-parser，或使用 pnpm add / yarn add / bun add。

### @3d-dice/dice-roller-parser 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @3d-dice/dice-roller-parser 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @3d-dice/dice-roller-parser 可以商用吗？

@3d-dice/dice-roller-parser 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @3d-dice/dice-roller-parser 的下载量有多少？

根据 npm 官方下载统计，@3d-dice/dice-roller-parser 在 2026/10/05 – 2026/11/03 这 30 天内被下载 3,725 次，日均约 124 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @3d-dice/dice-roller-parser 还在维护吗？

最新版本 0\.2\.6 发布于 2022/05/27（4 年前）；至今共发布 8 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/09/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。