https://github.com/edloidas/roll-parser
:dragon: Parser for classic (2d6+1), simple (2 6 1), and WoD (4d10!>6f1) dice rolls.
https://github.com/edloidas/roll-parser
dice dnd parser regexp roll wod
Last synced: about 2 months ago
JSON representation
:dragon: Parser for classic (2d6+1), simple (2 6 1), and WoD (4d10!>6f1) dice rolls.
- Host: GitHub
- URL: https://github.com/edloidas/roll-parser
- Owner: edloidas
- License: mit
- Created: 2017-03-14T07:08:16.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2020-10-11T11:55:39.000Z (over 5 years ago)
- Last Synced: 2024-04-14T10:16:05.376Z (about 2 years ago)
- Topics: dice, dnd, parser, regexp, roll, wod
- Language: JavaScript
- Homepage: http://edloidas.com/roll-parser/
- Size: 313 KB
- Stars: 4
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
Roll Parser
High-performance dice notation parser for tabletop RPGs.
TypeScript-first, Bun-optimized, Pratt parser architecture.
## Status
> **v3 Alpha** — Stage 1 (Core Engine) is complete with 300+ tests.
> Stages 2–3 are planned.
>
> For production use, install [v2.3.2](https://www.npmjs.com/package/roll-parser/v/2.3.2).
## Features
### Stage 1: Core Engine (Complete)
- Basic dice notation: `2d6`, `d20`, `4d6+4`
- Full arithmetic: `+`, `-`, `*`, `/`, `%`, `**`
- Parentheses: `(1d4+1)*2`
- Keep/Drop modifiers: `4d6kh3`, `2d20kl1`, `4d6dl1`
- Computed dice: `(1+1)d(3*2)`
- Seedable RNG for reproducible rolls
### Stage 2: System Compatibility (Planned)
- Exploding dice: `1d6!`, `1d6!!`, `1d6!p`
- Reroll mechanics: `2d6r<2`, `2d6ro<3`
- Success counting: `10d10>=6`, `10d10>=6f1`
- Math functions: `floor()`, `ceil()`, `max()`, `min()`
### Stage 3: Advanced Features (Planned)
- Variables: `1d20+@str`, `1d20+@{modifier}`
- Grouped rolls: `{1d8, 1d10}kh1`
- Rich JSON output with roll breakdown
## Installation
```bash
bun add roll-parser
npm install roll-parser
```
## Usage
```typescript
import { roll } from 'roll-parser';
const result = roll('4d6kh3');
console.log(result.total); // e.g., 14
console.log(result.notation); // "4d6kh3"
```
### CLI
```bash
roll-parser 2d6+3
roll-parser 4d6kh3
roll-parser --help
```
## Known Limitations
- **`4d6d1` parses as nested dice, not "drop 1".** The bare `d` token is always
interpreted as the dice operator, so `4d6d1` becomes `(4d6)d1` (roll 4d6, then
use the result as the count for d1). To drop dice, use the explicit `dl`
(drop lowest) or `dh` (drop highest) modifiers: `4d6dl1`.
## License
[MIT](LICENSE) © [Mikita Taukachou](https://edloidas.com)