https://github.com/alvarocastro/roll
Library to parse and roll dices from an AdX dice notation string.
https://github.com/alvarocastro/roll
dice dice-roller random roll roll-details roll-dices
Last synced: 3 months ago
JSON representation
Library to parse and roll dices from an AdX dice notation string.
- Host: GitHub
- URL: https://github.com/alvarocastro/roll
- Owner: alvarocastro
- License: mit
- Created: 2020-03-29T18:50:50.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-25T18:05:41.000Z (over 3 years ago)
- Last Synced: 2025-03-20T10:51:29.708Z (over 1 year ago)
- Topics: dice, dice-roller, random, roll, roll-details, roll-dices
- Language: JavaScript
- Homepage:
- Size: 1.17 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Roll
[](https://www.npmjs.com/package/@alvarocastro/roll)
[](https://github.com/alvarocastro/roll/actions?query=workflow%3Abuild)
[](https://codeclimate.com/github/alvarocastro/roll/maintainability)
[](https://coveralls.io/github/alvarocastro/roll?branch=master)
[](https://bundlephobia.com/result?p=@alvarocastro/roll)
[](https://github.com/xojs/xo)
[](https://github.com/semantic-release/semantic-release)
Library to parse and roll dices from a string as an `AdX` dice notation roll, like `1d6`, supporting simple transforms like `2d10+5`, or more complex like `1d8-1d6/2`.
- [Install](#install)
- [Usage](#usage)
- [Roll details](#roll-details)
- [Contributing](#contributing)
- [Support](#support)
- [Related](#related)
## Install
```bash
npm install -g @alvarocastro/roll
```
## Usage
```js
const roll = require('@alvarocastro/roll');
roll('1d6');
// => 3
roll('2d8');
// => 11
roll('1d3+1d6');
// => 7
roll('4+3d10/1d6');
// => 6.33333
```
### roll(rollString[, rollCallback])
Returns the result of the parsed and rolled `rollString`.
#### rollString
Type: `String`
Rolls to make in the form of `AdX` supporting basic mathematical expressions.
#### rollCallback
Type: `Function`
Function called for every sub roll made, it receives the sub roll string as first parameter and an array of roll results as second parameter.
```js
roll('2d6+1d8', (roll, results) => {
console.log(roll, results);
});
// => "2d6", [3, 4]
// => "1d8", [7]
```
## Roll details
To get a detailed output of the roll being made, to check for duplicate rolls, "critical" rolls, etc. `roll.detailed()` is provided.
```js
const roll = require('@alvarocastro/roll');
roll.detailed('2d10+4');
// => {
// result: 17,
// rolls: [
// {
// roll: '2d10',
// result: [
// 7,
// 6
// ]
// }
// ]
// }
```
## Contributing
Contributions are always welcome! Please run `npm test` beforehand to ensure everything is ok.
## Support
If you use this package please consider starring it :)
## Related
* [@alvarocastro/roll-cli](https://github.com/alvarocastro/roll-cli) - CLI version of this library.