Welcome Guest
Register | Login
Die-roll macro syntax and rules

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:

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:

To hit: [1d20+1], damage with mace: [1d6+2]

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:

To hit: [1d20+1] = 16+1 = 17, damage with mace: [1d6+2] = 6+2 = 8

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


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 exceeds 4, presenting the number of "successes" in the result.


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 the specified integer to the roll result. [1d8+1] rolls one eight-sided die then adds one (1) to the result.


Subtract the specified integer from the roll result. [1d12-2] rolls one twelve-sided die then subtracts two (2) from the result.


Multiply the roll by the specified integer. [4d6x10] rolls four six-sided die then multiplies the result by ten (10).
The Unseen Servant
© 2020 Smash-Co Communications
By using this site you agree to our Terms of use and our Privacy Policy.
Current UTC time: 11/23/2020 6:58:54 PM
Home | Donate | Forums
Users Guide | Macro Syntax | Dice Rolling Sandbox | API Stats