# Rolls

> The grammar of RPG Desk's rolls: dice, numbers, Fudge, ordering, successes against a difficulty, the roll's name, the limits and the error messages.

Page: https://docs.rpgdesk.com/en/referencia/rolagens/

Every roll is drawn by the RPG Desk server, wherever it comes from: `/r` in the chat, the quick dice, the sheets’ buttons (`data-roll` and `RPGDesk.dice.roll`) and the combat initiative. For everyday use, see [Dice and rolls](https://docs.rpgdesk.com/en/mesa/dados/).

## The parts of a roll

| Part        | Example          | What it is                                                                                   |
| ----------- | ---------------- | -------------------------------------------------------------------------------------------- |
| `NdF`       | `2d6`, `d20`     | N dice with F faces. Without the N, it is one die: `d20` is `1d20`. The `d` can be uppercase |
| `NdF` Fudge | `4dF`            | Fudge (Fate) dice: each one gives −1, 0 or +1                                                |
| number      | `5`              | a fixed value                                                                                |
| `+` and `-` | `1d20 + 5 - 1d4` | add and subtract                                                                             |
| `ord`       | `ord 4d6`        | shows each group’s dice in ascending order (the sum does not change)                         |
| `> K`       | `5d10 > 7`       | counts successes against difficulty K (see below)                                            |
| `: name`    | `1d20+5: Attack` | the roll’s name, which shows up in the chat                                                  |

Spaces do not count: `2d6+3` and `2d6 + 3` are the same roll. In the chat, the roll shows up like this:

```text
Davi rolled 1d20 + 5 = 17 {[12] + 5} Attack
```

## Successes (`> K`)

With `> K` at the end, the roll counts successes instead of adding up:

- each die that rolls **K or more** is a success;
- each die that rolls a **1** takes one success away;
- fixed numbers do not count.

| Result               | When                                                       |
| -------------------- | ---------------------------------------------------------- |
| **N successes**      | at least one success is left                               |
| **Failure**          | none is left, but some die reached K, or no die rolled a 1 |
| **Critical failure** | no die reached K and at least one rolled a 1               |

For example, `5d10 > 7` with the dice `[9, 7, 3, 1, 10]` gives **2 successes** (three successes, minus one for the 1). On a sheet, `RPGDesk.dice.roll` returns the count in `successes`.

## Limits

- From **1 to 255** dice per group, and from **1 to 255** faces. A number outside that is brought inside: `300d6` rolls 255 dice, and `0d6`, one.
- Up to **300** dice and fixed numbers, adding up every group.
- At least **one die**: `/r 5` does not roll.
- There is only the `>` comparator, once per roll.
- In the chat, the expression shows up with up to 120 characters, and the roll’s name, with up to 80.

## On sheets

In `data-roll`, `{path}` becomes the field’s number: `data-roll="1d20 + {str_mod}"`. An empty field becomes `0`, and a negative one comes out right (`1d20 + -2` becomes `1d20 - 2`). A field with text (`"3a"`) goes into the roll as it is, and the roll fails with the message “The roll has a character that is not allowed”. See [Rolls, chat and card](https://docs.rpgdesk.com/en/fichas/rolagens-e-chat/).

## The error messages

| Message                                                | Example                     | What to do                                                              |
| ------------------------------------------------------ | --------------------------- | ----------------------------------------------------------------------- |
| The roll is empty.                                     | `/r : Attack`               | put the dice before the `:`                                             |
| The roll has a character that is not allowed: “x”.     | `1d20 + STR`, `2d6 < 4`     | before the `:`, only numbers, `d`, `F`, `+`, `-`, `>`, `ord` and spaces |
| The die is missing its number of faces (d20, d8, d6…). | `2d`                        | write the faces: `2d6`                                                  |
| That dice roll does not exist (an extra “d”?).         | `2dd6`                      | one `d` per group                                                       |
| Unknown comparator: “>>”.                              | `4d10 >> 7`, `4d10 > 7 > 8` | a single `>`, with a number                                             |
| A roll can only have one comparator (>).               | `2d10 > 7 + 1d6 > 8`        | roll twice                                                              |
| The roll needs at least one die.                       | `5`, `3 + 2`                | add a die                                                               |
| Roll too large: up to 300 dice and numbers.            | `255d6 + 255d6`             | split the roll                                                          |

In the chat, the error shows up only to you. On a sheet, the `RPGDesk.dice.roll` promise is rejected with the same message, and `data-roll` shows the notice “The roll … failed”.

## How often

- Each person can roll up to **60 times per minute**.
- Each open sheet, up to **10 rolls every 10 seconds**.