A die-roll macro is comprised of two parts: literal text and at least one (or more) dice expressions. Dice expressions must be put within square brackets ([, ]) and can be placed anywhere within the macro, mixed in with the literal text. Anything outside of the brackets will remain unchanged in the end result. Here is an example of a dice expression:
A dice expression has four main parts, outlined below. Some are mandatory, and some are optional:
- The number of dice to roll. In this example, 4. This is a mandatory component of a valid dice expression.
- The number of sides the rolled dice should have. In this example, 6. Again, this is a mandatory component of a valid dice expression.
- An additional (optional) command, specified by the following characters: c, k, r and l. This must be followed by a number. This is an optional component of a valid dice expression. See the chart below for explanations of each additional command.
- A modifier (optional). In this example, the modifier is +1. This is an optional component. There can only be one modifier in a dice expression. Modifiers can be + (add), - (subtract), and x (multiply). If it is to be used, the modifier must be at the end of the dice expression.
- The underscore (_) character. Prepend your dice expression with the underscore character (_) to show all dice results in a multi-dice expression, like this: [_3d6]. If it is to be used, this must be at the beginning of the dice expression.
All numbers in a dice expression should be integer (whole) numbers. Numbers with decimals will be rounded up or down, and not simply dropped. Keep that in mind if you use decimals in your dice expression.
Let's look at an entire die-roll macro with literal text and dice expressions:
This die-roll macro tells the system to make two die rolls. The first rolls a 20-sided die and adds one (1) to the result. The second rolls one six-sided die, adding two (2) to the result. The output of the above die-roll macro would look like this:
As you can see, the die-roll macro text remains basically the same. The literal text and the dice expressions are there, as well as the results of the dice rolls. The roll results, with modifier applied (+, -, or x) are shown in bold red text.
A die-roll macro can contain as many dice expressions as the user sees fit, but the entire expression cannot be longer than 220 characters. If the syntax of a dice expression within a die-roll macro is not correctly defined, the result of that expression will be 'err', indicating that an error was encountered. Other dice expressions in the die-roll macro will still be processed, and as long as they are constructed correctly, you will get valid dice rolls in the output.
To try out macros without committing them to the database, go to the Dice Rolling sandbox.
If you have further questions, issues with the system, or suggestions for improvement, please join our forums.
Following is a table outlining the syntax of various dice expressions, with examples and explanations:
Dice expression syntax and examples| Expression | Function | Description | Example |
| [XdY] | n/a |
Roll X dice with Y sides each. | [1d20] rolls one twenty-sided die. |
| [XdYcN] | Cut | Roll X dice with Y sides each, and cut (drop) the lowest N dice afterwards. | [4d6c1] rolls four six-sided dice, and cuts (drops) the lowest roll. |
| [XdYkN] | Keep | Roll X dice with Y sides each, and keep the highest N dice afterwards. | [4d6k3] rolls four six-sided dice, keeping the highest 3 rolls. |
| [XdYrL] | Re-roll | Roll X dice with Y sides each, rerolling any results lower than L. | [3d8r2] rolls three eight-sided dice, rerolls any dice that are lower than 2, and then sums the result. |
| [XdYsT] | Success | Roll X dice with Y sides each, and count any rolls that meet or exceed T (the "target number"). | [4d6s4] rolls four six-sided dice and counts any individual roll that meets or exceeds 4, presenting the number of "successes" in the result. |
Modifiers
| Modifier | Function | Description | Example |
| _ | Show all dice |
Show all results in a multi-dice roll. | [_3d6] rolls three six-sided dice, shows all dice results AND sums the result. |
| + | Add |
Add the specified integer to the roll result. | [1d8+1] rolls one eight-sided die then adds one (1) to the result. |
| - | Subtract |
Subtract the specified integer from the roll result. | [1d12-2] rolls one twelve-sided die then subtracts two (2) from the result. |
| x | Multiply |
Multiply the roll by the specified integer. | [4d6x10] rolls four six-sided die then multiplies the result by ten (10). |