# @virtuoid/dice

> Fun with JavaScript - Dice classes

Latest version **1.0.5** (published 2024-07-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install @virtuoid/dice
pnpm add @virtuoid/dice
yarn add @virtuoid/dice
bun add @virtuoid/dice
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.5 |
| Published | 2024-07-19 |
| First published | 2022-07-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 32.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | TheVirtuoid <thevirtuoid@gmail.com> |
| Maintainers | thevirtuoid |
| Keywords | javascript, dice |

## Links

- npm: https://www.npmjs.com/package/@virtuoid/dice
- npm.io page: https://npm.io/package/@virtuoid/dice

## Recent versions

- 1.0.5 (latest) — 2024-07-19
- 1.0.4 — 2024-07-19
- 1.0.3 — 2024-05-07
- 1.0.2 — 2022-07-24
- 1.0.1 — 2022-07-05
- 1.0.0 — 2022-07-05

## README

# Fun With JavaScript - 'Dice' static class

This repository is for the 'Dice' static class used in the Fun with JavaScript series (https://funwithjavascript.com).

## Versions

1.0.5 : Updated README.md

1.0.4 : Added to internal monorepo

1.0.3 : Fixed 2 year old bug where it didn't load

1.0.2 : Fixed bug for multiple 'd' operators in equation.

1.0.0 : Initial Version

## Installation

```
npm install --save @virtuoid/dice
```

## Dependencies

No dependencies

## Usage

It is important to note that the Dice class is a **static** class. It cannot be instantiated. In fact, it will throw an error if you do!

```javascript
import Dice from '@virtuoid/dice';

// Roll a single six-sided die
const rollSix = Dice.roll('d6');
const rollOneSix = Dice.roll('1d6');

// Roll three six-sided die
const rollThreeSix = Dice.roll('3d6');

// How about three die and add 2?
const modifiedRoll = Dice.roll('3d6+2');

// How about a twenty-sided die?
const twentySides = Dice.roll('d20');

// Wait! There's more! Entire Equations
const strange = Dice.roll('3+(d30-4)*(4+3d3)-16');
```
#### Methods
| Name                                          | Returns     | Description                                                                                                                                     |
|-----------------------------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| roll(dieDescriptor: string) | Number | Rolls die according to the passed equation (see below).              |

## Equation Parser

The ```roll()``` method lets you pass an equation as the argument. This equation is then parsed and evaluated using normal mathematical precedence rules.

Addition, subtraction, multiplication, and division are supported. Parentheses are also supported.

There is a special operator called the Dice operator that, when used with a prefix and suffix, will roll a certain number of a certain type of die. The format is:

```xdy```

...where:

| Token | Required? | Default | Description                                                       |
|-------|-----------|---------|-------------------------------------------------------------------|
| x     | No        | 1       | The number of die to roll. Defaults to 1.                         | 
| d     | Yes       |         | The letter 'd'. This must always be there, as it is the operator. |
| y     | Yes       |         | The number of sides on the die                                    |

### Examples:
| Roll | Description |
| --- | --- |
| ```d6``` | Roll a single six-sided die |
| ```1d6``` | Roll a single six-sided die (same as first example) |
| ```3d6``` | Roll three six-sided die |
| ```d20``` | Roll a twenty-sided die |
| ```d100``` | Roll a hundred-sided die |
| ```10d100``` | Roll ten hundred-sided die |

---
_Source: https://npm.io/package/@virtuoid/dice · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._