dice roller parser

骰子滾輪和解析器

此骰子滾軸是一個字串解析器，它會傳回包含骰子滾軸組成部分的物件。它支援完整的 Roll20 Dice 規範。它使用 pegjs 語法來創建骰子滾動格式的表示。然後可以將其轉換為簡單的數值，或轉換為用於顯示完整捲詳細資訊的複雜物件。

信用

這是 Ben Morton 的 dice_roller 專案的一個分支。它有一些錯誤，所以我重新發布了我的專案所需的修復和功能。

快速入門

使用以下命令安裝庫：

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

用法

該庫公開兩個類，一個DiceRoller和一個DiscordRollRenderer 。

DiceRoller

DiceRoller類別管理骰子字串的解析並根據結果執行擲骰。

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

建構函數選項

預設建構子使用Math.random並套用每個骰子的最大擲骰數 1000。

DiceRoller(GeneratorFunction)

您可以指定一個函數用作骰子滾輪的隨機數產生器。此函數的類型應為() => number並傳回 0 Math.random 1 之間的數字。

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

類別的用法

一旦建構了DiceRoller類，就可以使用三種選項來執行擲骰子操作：

• 直接取得滾動結果
• 產生一個物件來表示擲骰子
• 只需解析輸入並添加您自己的滾動邏輯

獲得直接滾動結果

rollValue方法接受骰子字串輸入，解析它，執行擲骰並傳回計算的數值結果。

 //	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方法接受骰子字串輸入，對其進行解析，執行擲骰，然後傳回表示擲骰的物件。使用捲動對象，您可以建立自己的捲動顯示功能，而不僅僅是輸出最終值。

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

有關傳回物件的更多詳細信息，請參閱下面的輸出類型部分中的捲動結果輸出。

只需解析該值

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 相容的 markdown 格式的字串。

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

類別的用法

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

發展

要開發這個庫，只需克隆儲存庫，運行安裝：

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

這就是全部了！

輸出類型

以下物件類型是DiceRoller類別的輸出，並且可用作打字稿使用者的介面。

滾動結果輸出

滾動結果傳回的物件由以下類型組成。

RollBase

所有骰子的基類，根據類型屬性進行擴展。

財產	類型	描述
成功	boolean	擲骰是否成功（目標擲骰數）。範例： 3d6 > 3
類型	RollType	該物件代表的磁碟區的類型。
有效的	boolean	該卷是否仍然有效，並包含在計算中。
價值	number	此擲骰的擲骰值或計算值。
標籤	string	此磁碟區的顯示標籤。此屬性是可選的。
命令	number	用於維護組內擲骰子順序的屬性。

RollType

有效卷類型的枚舉。可能的值為：

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

GroupedRoll

為骰子組擴充的中間介面。此介面擴展了RollBase 。

財產	類型	描述
骰子	Array< RollBase	這些卷包含在該組中。

DiceExpressionRoll

骰子表達式的表示。此介面擴充了GroupedRoll 。

例子

2d20 + 6d6

財產	類型	描述
類型	"diceexpressionroll"	該物件代表的磁碟區的類型。
操作	Array< DiceGroupMathOperation >	在磁碟區上執行的操作。

ExpressionRoll

數學表達式的表示。此介面擴充了GroupedRoll 。

例子

20 * 17

財產	類型	描述
類型	"expressionroll"	該物件代表的磁碟區的類型。
操作	Array< MathOperation >	在磁碟區上執行的操作。

MathFunctionRoll

數學函數的表示。此介面擴展了RollBase 。

例子

floor(20 / 17)

財產	類型	描述
類型	"expressionfunc"	該物件代表的磁碟區的類型。
操作	MathFunction	在磁碟區上執行的操作。
表達式	RollBase	應用函數的表達式。

GroupRoll

一組卷的表示

例子

{4d6,3d6}。此介面擴充了GroupedRoll 。

財產	類型	描述
類型	"grouproll"	該物件代表的磁碟區的類型。

DiceRollResult

一組骰子的擲出結果。此介面擴展了RollBase 。

例子

6d20

財產	類型	描述
死	RollBase	該結果所代表的骰子。
類型	"die"	該物件代表的磁碟區的類型。
卷	DieRollBase []	每擲一次骰子。
數數	RollBase	骰子的捲數。
匹配的	boolean	這是否是比賽結果。

DieRollBase

單一骰子擴充的中間介面（見下文）。此介面擴展了RollBase 。

財產	類型	描述
卷	number	骰子的滾動結果。
匹配的	boolean	此卷是否符合。

DieRoll

普通模具上的一卷。此介面擴展了DieRollBase 。

例子

d20

財產	類型	描述
死	number	要滾動的骰子數量。
類型	"roll"	該物件代表的磁碟區的類型。
批判的	CriticalType	如果這個角色成敗關鍵（對於渲染）。

FateDieRoll

一卷命運就死了。此介面擴展了DieRollBase 。

例子

dF

財產	類型	描述
類型	"fateroll"	該物件代表的磁碟區的類型。

解析的滾動輸出

庫將以下介面公開為已解析輸入字串的重新表示。 parse方法的回應是一個RootType對象，並且可以是任何擴展它的介面。

ParsedObjectType

有效卷類型的枚舉。可能的值為：

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

ParsedType

這是所有解析類型的基本介面。

財產	類型	描述
類型	string	該物件代表的已解析項目的類型。

RootType

這是已解析類型子集的基本接口，僅限那些可以作為根類型的類型。該物件擴展了ParsedType介面。

財產	類型	描述
標籤？	string	附在該磁碟區上的文字標籤。此屬性是可選的。
根	boolean	一個布林標誌，指示這是否是解析樹的根。

NumberType

此物件代表輸入中的單一數字。此物件擴充了RootType介面。

財產	類型	描述
類型	"number"	該物件代表的已解析項目的類型。
價值	number	數字的值。

InlineExpression

該物件表示字串內的內聯骰子表達式，用雙方括號括起來。此物件擴充了RootType介面。

例子

I want to roll [[2d20]] dice

財產	類型	描述
類型	"inline"	該物件代表的已解析項目的類型。
表達式	Expression	被解析為內聯字串的表達式。

AnyRoll

代表任何有效卷的組合類型。這是以下類型的組合：

• GroupedRoll
• FullRoll
• NumberType

ModGroupedRoll

此物件代表帶有可選修飾符的分組滾動。此物件擴充了RootType介面。

例子

{4d6+3d8}kh1

財產	類型	描述
模組	Array< KeepDropModType , SuccessFailureModType >	應用於分組磁碟區的修改器。

SuccessFailureCritModType

代表成功測試修飾符的物件。該物件擴展了ParsedType介面。 "success"或"failure"修飾符將結果轉換為成功類型結果，該結果會傳回滿足目標的擲骰數。 "crit"或"critfail"修飾符測試擲骰是否應顯示為關鍵成功或關鍵失敗。

例子

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

財產	類型	描述
類型	"success", "failure", "crit", "critfail"	該物件代表的已解析項目的類型。
模組	CompareOperation	用於條件的檢查類型。
表達式	RollExpression	表示成功條件的表達式。

SuccessFailureModType

相當於SuccessFailureCritModType但僅支援「成功」和「失敗」修飾符。此物件擴充了SuccessFailureCritModType介面。

例子

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

財產	類型	描述
類型	"success", "failure"	該物件代表的已解析項目的類型。
模組	CompareOperation	用於條件的檢查類型。
表達式	RollExpression	表示成功條件的表達式。

MatchModType

表示匹配類型修飾符的對象，用於修改 roll20 中骰子輸出的顯示。該物件擴展了ParsedType介面。

例子

2d6m

與mt擴展一起使用時，將傳回找到的匹配項數。

例子

20d6mt

可以指定其他參數來增加所需的匹配數或為匹配添加約束。

例子

20d6mt3 counts matches of 3 items

例子

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

財產	類型	描述
類型	"match"	該物件代表的已解析項目的類型。
分分鐘	NumberType	接受的最小匹配數。此屬性預設為 2 作為NumberType 。
數數	boolean	是否計算匹配數。
模組？	CompareOperation	用於匹配條件的檢查類型（如果指定）。該字段是可選的。
表達式？	RollExpression	表示符合條件的表達式（如果指定）。該字段是可選的。

KeepDropModType

表示保留或丟棄修飾符的對象，指定保留或丟棄的骰子擲骰數，最高或最低擲骰。該物件擴展了ParsedType介面。

例子

保留： 2d20kh1掉落： 2d20dl1

財產	類型	描述
類型	"keep", "drop"	該物件代表的已解析項目的類型。
高低	HighLowType	是否保留/放棄最高或最低滾動。
表達式	RollExpression	表示要保留/丟棄的磁碟區數的表達式。此屬性預設為 1 作為NumberType 。範例： 2d6

GroupedRoll

此物件代表一組組合的擲骰，具有可選的修飾符。此物件擴充了ModGroupedRoll介面。

例子

{2d6,3d6}

財產	類型	描述
類型	"group"	該物件代表的已解析項目的類型。
卷	Array< RollExpression >	該組中包含的捲組。

RollExpressionType

表示包含複雜滾動和群組的滾動表達式的物件僅允許加法操作。此物件擴充了RootType介面。

例子

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

財產	類型	描述
頭	RollOrExpression	初始滾動或滾動表達式的表達式。
類型	"diceExpression"	該物件代表的已解析項目的類型。
操作	Array< MathType < RollOrExpression , DiceGroupMathOperation >>	應用於初始滾動或表達式的操作。

RollExpression

複雜滾動表達式、滾動或數學表達式的輔助類型組合。代表以下類型：

• RollExpressionType
• RollOrExpression

RollOrExpression

滾動或數學表達式的輔助類型組合。代表以下類型：

• FullRoll
• Expression

FullRoll

表示擲骰子的對象，包括骰子擲骰和任何修飾符。此物件擴充了DiceRoll介面。

例子

2d6kh1

財產	類型	描述
模組？	Array< ReRollMod , KeepDropModType >	附加到磁碟區上的任何修飾符。此屬性是可選的。
目標？	Array< SuccessFailureCritModType >	任何成功或失敗都是擲骰子的目標。此屬性是可選的。
匹配？	MatchModTyp	擲骰的任何匹配修飾符。此屬性是可選的。
種類？	SortRollType	應用於磁碟區的任何排序操作。此屬性是可選的。

SortRollType

應用於磁碟區的排序操作。該物件擴展了ParsedType介面。

例子

10d6sa

財產	類型	描述
類型	"sort"	該物件代表的已解析項目的類型。
升序	boolean	是否按升序或降序排序。

ReRollMod

表示應用於滾動的重新滾動操作的物件。可以是以下類型之一：

• "explode" ：重新擲骰子，如果新的骰子匹配，則繼續擲骰子
• "compound" ：重新擲任何符合目標的骰子，如果新擲骰子配對則繼續，並將結果加到單一擲骰子中
• "penetrate" : 重新擲任何符合目標的骰子，從新值中減去 1，如果新擲骰匹配則繼續
• "reroll" ：只要達到目標就重新擲骰子，保持最後的擲骰結果
• "rerollOnce" ：如果骰子達到目標，則重新擲骰子一次，並保持新的擲骰數

例子

2d6!

財產	類型	描述
類型	"explode", "compound", "penetrate", "reroll", "rerollOnce"	該物件代表的已解析項目的類型。
目標	TargetMod	用於比較擲骰值的目標修正值。

TargetMod

代表要應用於擲骰的目標修改器的物件。該物件擴展了ParsedType介面。

財產	類型	描述
類型	"target"	該物件代表的已解析項目的類型。
模組	CompareOperation	用於條件的檢查類型。
價值	RollExpr	表示目標條件值的表達式。

DiceRoll

骰子的表示。此物件擴充了RootType介面。

例子

2d6

財產	類型	描述
死	RollExpr , FateExpr	要滾動的骰子值可以是命運骰子、數字或複雜的滾動表達式。
數數	RollExpr	擲骰子的次數。
類型	"die"	該物件代表的已解析項目的類型。

FateExpr

命運骰子的代表。該物件擴展了ParsedType介面。

例子

2dF

財產	類型	描述
類型	"fate"	該物件代表的已解析項目的類型。

RollExpr

非表達式的數字或值的輔助類型組合。代表以下類型：

• MathExpression
• NumberType

Expression

表達式類型的輔助類型組合。代表以下類型：

• InlineExpression
• MathExpression

MathExpression

兩個或多個擲骰子之間的數學類型表達式。此物件擴充了RootType介面。

例子

2d6 + 3d6 * 4d6

財產	類型	描述
頭	AnyRoll	要執行操作的初始磁碟區。
類型	"expression"	該物件代表的已解析項目的類型。
操作	Array< MathType < AnyRoll >>	應用於初始卷的操作。

MathType

一個對象，表示要應用的滾動數學運算以及要應用到的值。該物件擴展了ParsedType介面。該物件的介面採用模板化類型TailType ，它指定操作中使用的第二個值的類型。還有第二個模板類型OpValues ，它指定可以使用的操作類型。預設為Array< MathOperation 。

例子

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

財產	類型	描述
類型	"math"	該物件代表的已解析項目的類型。
操作	OpValues	要執行的數學運算。
尾巴	TailType	操作中使用的第二個值。

MathFunctionExpression

表示要應用的數學函數和要套用該函數的表達式的物件。此物件擴充了RootType介面。

例子

floor(3d6 / 2d4)

財產	類型	描述
類型	"mathfunction"	該物件代表的已解析項目的類型。
操作	MathFunction	要應用的函數。
表達式	AnyRoll	應用函數的表達式。

助手類型

以下是上述介面使用的支援類型。

DiceGroupMathOperation

表示對一組骰子進行數學運算的有效運算的輔助類型。

"+" | "-"

MathOperation

表示數學運算的有效運算的輔助類型。

"+" | "-" | "*" | "/" | "%" | "**"

MathFunction

表示數學運算的有效運算的輔助類型。

"floor" | "ceil" | "round" | "abs"

CriticalType

將擲骰標記為關鍵成功或失敗時使用的輔助類型。

"success" | "failure" | null

CompareOperation

比較點可用操作的輔助類型。

">" | "<" | "="

HighLowType

用於確定保留或丟棄哪些磁碟區的輔助類型。

"h" | "l" | null