DiceRoll
주사위 표현식을 파싱하고 실행하는 TypeScript 라이브러리입니다. 다양한 주사위 굴림 방식을 지원하며, 블록별로 적절한 roll 함수에 위임하여 계산합니다.
A TypeScript library for parsing and executing dice expressions. Supports various dice rolling methods and delegates calculations to appropriate roll functions block by block.
설치 / Installation
# pnpm
pnpm add @nihilapp/diceroll-v3
# npm
npm install @nihilapp/diceroll-v3
# yarn
yarn add @nihilapp/diceroll-v3빠른 시작 / Quick Start
ESM (import/export)
한국어: ES 모듈 형식으로 사용할 수 있습니다.
English: Can be used with ES module syntax.
import { rollDiceExpression } from '@nihilapp/diceroll-v3';
// 단일 주사위식
const result = rollDiceExpression('d20+5');
console.log(result);
// [
// {
// expression: 'D20+5',
// total: 18,
// rollDetails: [
// { block: 'D20', kind: 'basic', contribution: 13, rollResult: {...} }
// ],
// modifiers: [{ sign: '+', value: 5 }]
// }
// ]
// 여러 주사위식 (공백으로 구분)
const results = rollDiceExpression('d20+5 3d6+2');
console.log(results);
// [
// { expression: 'D20+5', total: 18, rollDetails: [...], modifiers: [...] },
// { expression: '3D6+2', total: 14, rollDetails: [...], modifiers: [...] }
// ]CommonJS (require/module.exports)
한국어: CommonJS 형식으로도 사용할 수 있습니다.
English: Can also be used with CommonJS syntax.
const { rollDiceExpression } = require('@nihilapp/diceroll-v3');
// 단일 주사위식
const result = rollDiceExpression('d20+5');
console.log(result);
// [
// {
// expression: 'D20+5',
// total: 18,
// rollDetails: [
// { block: 'D20', kind: 'basic', contribution: 13, rollResult: {...} }
// ],
// modifiers: [{ sign: '+', value: 5 }]
// }
// ]
// 여러 주사위식 (공백으로 구분)
const results = rollDiceExpression('d20+5 3d6+2');
console.log(results);
// [
// { expression: 'D20+5', total: 18, rollDetails: [...], modifiers: [...] },
// { expression: '3D6+2', total: 14, rollDetails: [...], modifiers: [...] }
// ]지원하는 주사위식 / Supported Dice Expressions
기본 굴림 / Basic Roll
가장 기본적인 주사위 굴림입니다.
The most basic dice rolling.
rollDiceExpression('d20'); // 1d20
rollDiceExpression('3d6'); // 3d6
rollDiceExpression('d20+5'); // 1d20 + 5한국어: d, D, ㅇ 모두 동일하게 처리되며, 자동으로 D로 통일됩니다. 개수가 생략되면 1개로 간주됩니다.
English: d, D, ㅇ are all treated the same and automatically normalized to D. If the count is omitted, it defaults to 1.
Compound (!!)
최대값이 나오면 추가 굴림 값을 기존 주사위 눈에 합쳐서 표시합니다.
When the maximum value is rolled, additional roll values are added to the original dice face.
rollDiceExpression('10d6!!'); // 6이 나오면 다시 굴려서 기존 값에 더함
rollDiceExpression('1d4!!'); // 4가 나오면 계속 더해서 단일 숫자로 반환
rollDiceExpression('5d10!!>8'); // 9 이상일 때 compound한국어: !! 접미사를 사용합니다. !!>N 형태로 임계값을 지정할 수 있습니다.
English: Use the !! suffix. You can specify a threshold with !!>N format.
Explode (!)
특정 조건을 만족하면 추가 주사위를 굴립니다.
Rolls additional dice when certain conditions are met.
rollDiceExpression('10d6!'); // 6이 나오면 주사위 추가
rollDiceExpression('5d10!>8'); // 9, 10이 나오면 주사위 추가한국어: ! 접미사를 사용합니다. !>N 형태로 임계값을 지정할 수 있습니다.
English: Use the ! suffix. You can specify a threshold with !>N format.
FVTT Explode (x/xo)
Foundry VTT 스타일 explode 문법도 지원합니다.
rollDiceExpression('1d6x'); // 폭발 굴림
rollDiceExpression('1d6xo'); // 한 번만 폭발
rollDiceExpression('1d10x<=5'); // 5 이하가 나오면 계속 폭발
rollDiceExpression('1d10x5'); // 기본 폭발 조건으로 최대 5회까지 폭발
rollDiceExpression('1d10x2>=9'); // 9 이상이면 폭발, 최대 2회까지한국어: 기존 !, !! 문법은 유지되며 x, xo와 병행 지원됩니다. x, xo는 =N, <=N, >=N, <N, >N 비교식을 받을 수 있고, x는 숫자를 바로 붙여 explode 최대 횟수 cap도 지정할 수 있습니다. 예: x5, x2>=9
English: Legacy !, !! syntax is preserved and can be used alongside x and xo. Both support comparison predicates such as =N, <=N, >=N, <N, and >N, and x also supports a numeric explode cap such as x5 or x2>=9.
Keep Highest/Lowest (kh/kl)
여러 개의 주사위를 굴린 뒤, 상위/하위 N개만 선택해 합산합니다.
Roll multiple dice and select only the highest/lowest N dice to sum.
rollDiceExpression('4d6kh3'); // 상위 3개만 선택 (D&D 능력치 생성)
rollDiceExpression('2d20kl1'); // 하위 1개만 선택 (Disadvantage)
rollDiceExpression('3d6kl1'); // 하위 1개만 선택한국어: khN은 상위 N개, klN은 하위 N개를 유지합니다.
English: khN keeps the highest N dice, klN keeps the lowest N dice.
FVTT Keep/Drop Shorthand
Foundry VTT 스타일 축약 keep/drop 문법도 지원합니다.
rollDiceExpression('4d6k'); // 상위 1개만 유지
rollDiceExpression('4d6d'); // 하위 1개 버림
rollDiceExpression('4d6kl'); // 하위 1개만 유지
rollDiceExpression('4d6dh'); // 상위 1개 버림한국어: k, kl, d, dh처럼 개수를 생략한 FVTT 축약형은 기본값 1로 처리됩니다.
English: FVTT shorthand forms like k, kl, d, and dh default to a count of 1.
Drop Highest/Lowest (dh/dl)
여러 개의 주사위를 굴린 뒤, 상위/하위 N개를 버리고 나머지만 합산합니다.
Roll multiple dice and drop the highest/lowest N dice, then sum the rest.
rollDiceExpression('4d6dh1'); // 상위 1개를 버림
rollDiceExpression('4d6dl1'); // 하위 1개를 버림
rollDiceExpression('5d8dl2'); // 하위 2개를 버림한국어: dhN은 상위 N개를 버리고, dlN은 하위 N개를 버립니다.
English: dhN drops the highest N dice, dlN drops the lowest N dice.
Reroll (r)
Foundry VTT 기준으로 조건을 만족하면 단 한 번 다시 굴립니다.
Rerolls only once when the condition is met, following Foundry VTT semantics.
rollDiceExpression('1d20r1'); // 1이 나오면 한 번만 다시 굴림
rollDiceExpression('1d6r<=2'); // 1, 2가 나오면 한 번만 다시 굴림
rollDiceExpression('2d10r<5'); // 4 이하가 나오면 한 번만 다시 굴림한국어: rN, r<=N, r>=N, r<N, r>N 형태로 조건을 지정할 수 있습니다.
English: You can specify conditions with rN, r<=N, r>=N, r<N, r>N formats.
Recursive Reroll (rr)
조건을 만족하면 더 이상 조건을 만족하지 않을 때까지 계속 다시 굴립니다.
Keeps rerolling until the condition is not met.
rollDiceExpression('1d20rr1'); // 1이 나오면 1이 아닐 때까지 다시 굴림
rollDiceExpression('2d6rr<2'); // 1이 나오면 2 이상이 나올 때까지 다시 굴림한국어: rrN, rr<=N, rr>=N, rr<N, rr>N 형태로 조건을 지정할 수 있습니다. 기존 ro 문법은 제거되었습니다.
English: Use rrN, rr<=N, rr>=N, rr<N, rr>N for recursive rerolls. Legacy ro has been removed.
FVTT Success Modifiers
Foundry VTT 스타일 success-family modifier 일부를 지원합니다.
rollDiceExpression('5d10cs>=8'); // 성공 개수
rollDiceExpression('3d10cs'); // 최대 눈(10)만 성공으로 간주
rollDiceExpression('4d6cf'); // 기본 실패값(1)의 개수
rollDiceExpression('4d6df'); // 기본 실패값(1)을 차감
rollDiceExpression('3d6sf<3'); // 실패한 눈의 값을 합계에서 차감
rollDiceExpression('3d6ms>10'); // 총합 - 목표값
rollDiceExpression('4d6even'); // 짝수 눈 개수
rollDiceExpression('4d6odd'); // 홀수 눈 개수
rollDiceExpression('4d6min2rr1kh3'); // modifier 조합 예시한국어: 현재 cs, cf, df, sf, ms, min, max, even, odd를 지원하며 kh, kl, dh, dl, r, rr, x, xo와 같은 블록 안에서 조합할 수 있습니다. min, max는 min2, max8처럼 숫자를 바로 붙이는 형태를 사용합니다. cs, cf, df는 비교식이 없으면 기본값 =최대눈, =1, =1을 사용합니다.
English: The parser supports cs, cf, df, sf, ms, min, max, even, and odd, and they can be mixed with kh, kl, dh, dl, r, rr, x, and xo in the same block. min and max use direct numeric suffixes such as min2 and max8. If no comparison is provided, cs, cf, and df default to =max, =1, and =1.
Success (>N, >=N, =N, <N)
성공 조건을 만족하는 주사위 개수만 카운트합니다 (WoD 등).
Counts only dice that meet the success condition (World of Darkness, etc.).
rollDiceExpression('5d10>7'); // 7을 초과하는 주사위 개수
rollDiceExpression('3d6=6'); // 정확히 6인 주사위 개수
rollDiceExpression('4d8>=6'); // 6 이상인 주사위 개수한국어: >N, >=N, =N, <N, <=N 형태로 성공 조건을 지정할 수 있습니다.
English: You can specify success conditions with >N, >=N, =N, <N, <=N formats.
Net Success (>NfM)
성공(+1)·실패(-1)로 계산하여 순성공(합산)을 반환합니다 (WoD 등).
Calculates success (+1) and failure (-1) to return net success (World of Darkness, etc.).
rollDiceExpression('5d10>8f1'); // 9, 10은 +1, 1은 -1
rollDiceExpression('6d6>4f<=2'); // 5, 6은 +1, 1, 2는 -1
rollDiceExpression('4d10>7f>=9'); // 8 이상은 +1, 9 이상은 -1한국어: >NfM 형태로 성공 조건과 실패 조건을 지정합니다. 실패 조건도 f<=N, f>=N, f<N, f>N 형태로 지정할 수 있습니다.
English: Specify success and failure conditions with >NfM format. Failure conditions can also be specified as f<=N, f>=N, f<N, f>N.
Percentile (d%)
퍼센타일 굴림 - 1~100 사이 난수 생성 (CoC 판정 등).
Percentile roll - generates a random number between 1~100 (Call of Cthulhu, etc.).
rollDiceExpression('d%'); // 1~100 사이 난수한국어: d% 또는 D% 형태로 사용합니다.
English: Use d% or D% format.
Fate Dice (dF)
Fate 시스템용 주사위 굴림.
Dice rolling for the Fate system.
rollDiceExpression('dF'); // 기본값 4dF
rollDiceExpression('4dF'); // 4dF
rollDiceExpression('1dF'); // 1dF한국어: dF 또는 DF 형태로 사용합니다. 개수를 생략하면 기본값 4개로 굴립니다.
English: Use dF or DF format. If count is omitted, defaults to 4 dice.
복합 표현식 / Complex Expressions
보정치 / Modifiers
숫자로 보정치를 추가할 수 있습니다.
You can add modifiers as numbers.
rollDiceExpression('d20+5'); // d20 + 5
rollDiceExpression('3d6+2-1'); // 3d6 + 2 - 1
rollDiceExpression('d20+5+4d6kl2'); // d20 + 5 + (4d6에서 하위 2개)한국어: +N 또는 -N 형태로 보정치를 추가합니다. 보정치는 별도 배열로 분리되어 반환됩니다.
English: Add modifiers with +N or -N format. Modifiers are returned in a separate array.
여러 주사위식 / Multiple Expressions
공백으로 구분하여 여러 주사위식을 한 번에 실행할 수 있습니다.
You can execute multiple dice expressions at once, separated by spaces.
rollDiceExpression('d20+5 d20+3d20'); // 두 개의 독립적인 주사위식
rollDiceExpression('d6 d8 d10'); // 세 개의 주사위식한국어: 공백이 없으면 하나의 주사위식으로, 공백이 있으면 여러 주사위식으로 분리됩니다. 각 주사위식은 독립적으로 계산되어 배열로 반환됩니다.
English: If there's no space, it's treated as a single expression. If there are spaces, it's split into multiple expressions. Each expression is calculated independently and returned as an array.
지원 범위 주의 / Current Expression Scope
현재 공개 API는 주사위 블록과 +N, -N 보정치 조합에 집중되어 있습니다.
The current public API focuses on dice blocks plus numeric +N and -N modifiers.
rollDiceExpression('d20+5+4d6rr1kh3'); // 지원
rollDiceExpression('5d10cs>=8+2'); // 지원한국어: 괄호 우선순위나 일반 산술 연산자(*, /)는 현재 공식 지원 범위가 아닙니다.
English: Parenthetical precedence and general arithmetic operators like * and / are not part of the current supported public syntax.
API 문서 / API Documentation
rollDiceExpression(input: string): DiceExpressionResult[]
주사위 표현식 문자열을 파싱하고 실행합니다.
Parses and executes a dice expression string.
Parameters / 매개변수:
input: 주사위 표현식 문자열 (예:"d20+5+4d20kl2")
Returns / 반환값:
type DiceExpressionResult = {
/** 주사위식 원문 */
expression: string;
/** 총계 (모든 블록 contribution + 보정치 합) */
total: number;
/** 상세 주사위식별 굴림 정보 */
rollDetails: DiceBlockRollDetail[];
/** 보정치 배열 */
modifiers: ModifierEntry[];
};한국어: 각 주사위식마다 하나의 결과 객체가 생성되며, 여러 주사위식이면 배열로 반환됩니다.
English: One result object is created for each dice expression, and multiple expressions are returned as an array.
parseDiceExpression(input: string): string[]
주사위 표현식 문자열을 파싱만 수행합니다 (실행하지 않음).
Only parses the dice expression string (does not execute).
Parameters / 매개변수:
input: 주사위 표현식 문자열
Returns / 반환값:
- 파싱된 표현식 문자열 배열
한국어: 공백 기준으로 주사위식을 분리하여 배열로 반환합니다.
English: Splits dice expressions by spaces and returns them as an array.
개별 roll 함수 내보내기 / Per-roll function exports
한국어: 각 주사위 룰 함수들도 패키지 루트에서 직접 임포트하여 사용할 수 있습니다.
English: Each roll rule function is also exported from the package root and can be imported directly.
import {
rollBasic,
rollExplode,
rollKeepHighest,
rollKeepLowest,
rollDropHighest,
rollDropLowest,
rollReroll,
rollRerollOnce,
rollSuccess,
rollNetSuccess,
rollPercentile,
rollFate,
} from '@nihilapp/diceroll-v3';
const basic = rollBasic(3, 6);
const exploded = rollExplode(10, 6);
const kh = rollKeepHighest(4, 6, 3);예제 / Examples
기본 사용 / Basic Usage
import { rollDiceExpression } from '@nihilapp/diceroll-v3';
// D&D 스타일 굴림
const attack = rollDiceExpression('d20+5');
console.log(attack[0].total); // 예: 18
// 능력치 생성 (4d6, 상위 3개)
const ability = rollDiceExpression('4d6kh3');
console.log(ability[0].total); // 예: 15
// 불리함 (2d20, 하위 1개)
const disadvantage = rollDiceExpression('2d20kl1');
console.log(disadvantage[0].total); // 예: 8복합 표현식 / Complex Expressions
// 여러 주사위와 보정치
const complex = rollDiceExpression('d20+5+4d20kl2+10d50r1');
console.log(complex[0].total);
console.log(complex[0].rollDetails); // 각 블록별 상세 정보
console.log(complex[0].modifiers); // 보정치 배열
// 여러 주사위식
const multiple = rollDiceExpression('d20+5 d20+3d20');
console.log(multiple.length); // 2
console.log(multiple[0].total); // 첫 번째 주사위식 결과
console.log(multiple[1].total); // 두 번째 주사위식 결과WoD 스타일 / World of Darkness Style
// 성공 개수
const successes = rollDiceExpression('5d10>7');
console.log(successes[0].total); // 성공 개수
// FVTT success-family modifier
const fvttSuccess = rollDiceExpression('5d10cs>=8');
console.log(fvttSuccess[0].total); // 성공 개수
// 순성공 (성공 - 실패)
const netSuccess = rollDiceExpression('5d10>8f1');
console.log(netSuccess[0].total); // 순성공 (성공 개수 - 실패 개수)개발 / Development
# 개발 모드 실행
pnpm dev
# 빌드
pnpm build
# 린트
pnpm lint라이선스 / License
ISC