 |
Summary | Dice Roller adds a well-featured dice roller to your Discourse posts, for your forum-based game needs! |
 |
Repository Link | https://github.com/discourse/discourse-dice |
 |
New to Discourse Themes? | Beginner’s guide to using Discourse Themes |
Install this theme component
Admins: Consider disabling the
discourse narrative bot disable public repliessetting after installing, as this theme component entirely supersedes the bot’s dice rolling behavior.
Basic Usage
The theme component interprets rolls formatted as [wrap=dice].
[wrap=dice]d20[/wrap]
[wrap=dice]d100[/wrap]
[wrap=dice]2d6[/wrap]
You can roll multiple dice of the same type, apply additive modifiers, and automatically check the result against a success threshold:
[wrap=dice]2d6+3t12[/wrap]
Advanced Features: Crits, Split Rolls
You can specify specific natural rolls to be treated as “critical hits” with the crit= option. Critical hits are checked before the additive modifier.
[wrap=dice crit=1,100]1d100[/wrap]
[wrap=dice crit=1,20]d20+3[/wrap]
If particular crit values are notable on your forum, an admin can add extra CSS to emphasize them. In this example, crits that roll a
1are colored in red.
If you’re allowing multiple rolls to be checked against the same threshold, you can add the i Individual modifier in conjunction with t Thresholds. The number of successful dice that passed the threshold will be summarized at the end.
[wrap=dice]5d100t60i[/wrap]
[wrap=dice]3d20-5t0i[/wrap]
Restrictions
To avoid griefing with large post bodies, a maximum number of dice per roll is available in the theme settings for the admin to adjust. The default is 80 dice.
0-sided and 1-sided dice are not allowed. Rolling 0 dice is not allowed, and dice with more than ~67 million faces are not allowed for performance reasons.
Technical Details, and Cheating
Rolls are calculated in JavaScript using a RNG seeded by the post’s ID and creation timestamp, going in order through the post body. Roll values are not visible before the post is created.
Several special formatting styles are applied to rolls, to distinguish them from normal text in posts. This doesn’t stop people from posting images!
Roll values are not saved in the post body automatically. This presents a problem for archival needs. Solutions to this will require use of a plugin.
If you need to edit additional die rolls into your post, they must be added at the bottom to preserve the results of all previous rolls. Adding new die rolls at the top of a post will randomize the results of all the rolls. For this reason, having any erroneous rolls in a post will prevent all subsequent rolls from functioning.
The composer preview will tell you if your dice specification is correct or 
erroneous.
While these measures can help prevent accidental cheating, a determined cheater can try to predict when they should submit their post. If you’re considering this for anything valuable, have a trusted user who cannot receive the reward author the post, or use an independent source like https://random.org , which offers paid services for auditable drawings and raffles.
Remember to have fun!
Settings
| Name | Description |
|---|---|
| max dice |
| Translation | Default |
|---|---|
| dice.result.success_count.one | (%{count} Success) |
| dice.result.success_count.other | (%{count} Successes) |
| dice.excessive.quantity.one | Excessive dice quantity (max %{count}) |
| dice.excessive.quantity.other | Excessive dice quantity (max %{count}) |
| dice.excessive.faces | Number of die faces cannot exceed 67,000,000 |
| dice.missing.faces | Invalid die specification: missing number of faces |
| dice.invalid.generic | Invalid die specification. Format: 2d20+3 |
| dice.invalid.quantity | Number of dice cannot be 0 |
| dice.invalid.faces | Number of die faces cannot be 0 or 1 |
| dice.invalid.modifier | Modifier cannot be 0 |
| dice.invalid.threshold | Threshold cannot be 0 |
| dice.invalid.crits | Bad numbers in crits attribute. (Should be crits=4,5,6) |
| dice.invalid.halt_after_error | Rolling halted due to earlier error. Fix errors to view results. |
Last edited by @david 2025-06-16T09:11:30Z
Check document
Perform check on document: