DiscordDiceBot

= Button Dice Roller :toc: macro

https://www.gnu.org/licenses/agpl-3.0[image:https://img.shields.io/badge/License-AGPL_v3-blue.svg[License: AGPL v3]] https://codecov.io/gh/twonirwana/DiscordDiceBot[image:https://codecov.io/gh/twonirwana/DiscordDiceBot/branch/main/graph/badge.svg?token=OLH7L312D7[codecov]] image:https://img.shields.io/github/actions/workflow/status/twonirwana/DiscordDiceBot/codeCov.yml?branch=main[GitHub Workflow Status] image:https://img.shields.io/discord/898657305883725834[link="https://discord.gg/e43BsqKpFr"] image:https://dcbadge.limes.pink/api/shield/812381127943782502?bot=true&style=flat&theme=clean-inverted[link="https://discord.com/oauth2/authorize?client_id=812381127943782502"] image:https://ko-fi.com/img/githubbutton_sm.svg[link="https://ko-fi.com/Y8Y21FG71V",height=20px]

This bot is for rolling dice in discord. The bot needs to be configured with a slash command in a channel and then provides a message with buttons. Upon clicking on a button the bot will roll the stored dice expression for the button, post the result and move the message with the buttons to the bottom of the channel. This allows user to roll dice without typing commands and thereby improves usability, especially for touchscreen users.

If the message is pined, then it will only be copied and not moved. The bot supports Discord thread (the button message must be added after the thread creation), forum, Text in Voice, direct messages, and it is possible to send the answer in a different channel. It can provide images of the dice roll results and it is possible to configure channel or user specific aliases.

The bot can be user installed, this allows a user to use the slash commands (but no buttons) in server where the bot is not installed

image:image/example.webp[image] Add to Discord channel by following this link: https://discord.com/oauth2/authorize?client_id=812381127943782502[Bot invite link]

Discord Server for trying the bot, questions and feature suggestions: https://discord.gg/e43BsqKpFr[Button Dice Roller Discord Server]

The bot need the following permission:

• create application commands (which are needed to control the bot)
• send message and send message in threads (for the dice buttons and results)
• embed links (display of structured answers)
• attach files (add images with the dice result)
• read message history (to detect if a button message was pinned)

toc::[]

== Known Problems

If you can’t see the bots messages: The link preview in the discord setting must be activated to see the roll results

If you can’t use slash commands: Disable User Settings > Accessibility > Use the legacy chat input

== Quickstart

The bot has list a ready to play list of presets for many RPG systems. Simple select a system out of the list or keep typing to search and filter in the list. All these presets are realised with the user available commands and dice expression and can be adapted and extended. Please let me know if you have a good new preset or an improved version for an existing preset. The quickstart will show a user also all named commands other user have created at the same server and all named commands the user himself has created in any server.

[cols="1,1"] |=== |A Song of Ice and Fire |Blades in the Dark - Detail |Blades in the Dark without Dice Images |Blades in the Dark |Bluebeard's Bride |Call of Cthulhu 7th Edition |Candela Obscura v2 |Candela Obscura |City of Mist |Cyberpunk Red |Daggerheart |Dice Calculator |Dungeon & Dragons 5e Calculator 2 |Dungeon & Dragons 5e Calculator |Dungeon & Dragons 5e without Dice Images |Dungeon & Dragons 5e |Dungeon Crawl Classics |EZD6 |Exalted 3ed |Fallout |Fate without Dice Images |Fate |Forbidden Lands |Ghostbusters: A Frightfully Cheerful Roleplaying Game First Edition & Spooktacular |Heroes of Cerulea |Hunter 5ed |Ironsworn |Kids on Brooms |OSR |Oathsworn |One-Roll Engine |Otherscape |Paranoia: Red Clearance Edition |Powered by the Apocalypse |Prowlers & Paragons Ultimate Edition |Public Access |Rebellion Unplugged |Risus The Anything RPG "Evens Up" |Rêve de Dragon |Salvage Union BDR-V1.0 |Savage Worlds |Shadowdark |Shadowrun without Dice Images |Shadowrun |Star Wars - West End Games D6 Rules, 2nd Edition REUP |The Expanse |The Marvel Multiverse Role-Playing Game |The One Ring |Tiny D6 |Traveller |Vampire 5ed |Warhammer Age of Sigmar: Soulbound |Year Zero Engine: Alien |nWod / Chronicles of Darkness |oWod / Storyteller System |🪙Coin Toss |===

The quickstart command can also set alias to make direct rolls more comfortable. You can also set channel config default for the answer format to without_expression to hide the complex expression in the answers. See <<_channel_config>> for channel config

[cols="1,1"] |=== | Alias Name | Alias Function

|Cyberpunk Red - Alias | roll with cp |Dungeon & Dragons 5e - Alias | roll advantage with adv and disadvantage with dis |Fate - Alias | roll four fate dice with 4dF |nWod / Chronicles of Darkness - Alias | roll with w e.g. 8w |oWod / Storyteller System - Alias | roll with r e.g. 8r6 for 8 dice against target 6 and re for rolling with rerolling on 10 |Shadowrun - Alias | roll with sr e.g 8sr |Savage Worlds - Alias | roll exploding dice with r e.g. r10 for an exploding d10 and sw for a roll with wildcard dice e.g. sw8 |Blades in the Dark - Alias | roll with b e.g. 4b for 4 dice |Otherscape - Alias | roll with o + power e.g. o+1 for roll with power 1. |===

== Options

=== Language

The bot supports multiple languages (currently English, German, Brazilian Portuguese and French). The bot will use the discord client language for the slash command and options. Each button message has a language configuration and will return its answers always in the language of its configuration. All existing button messages are default in English. Button messages are per default created in the language of the discord client but that can be overwritten with the language option of the slash commands. The direct roll messages are using the language that is configured with the channel_config command and not the discord client language. The dice expressions are currently not translated. Contributions of additional language and improvements are very welcome.

=== Target Channel

All button configurations can be used with the target_channel option. If this option is used then the answer of a roll will be posted in the provided channel. The target channel must be a text channel and need the bot need the usual permissions. If a message sends the answer to another channel, it will not be moved to the end of its own channel.

=== Answer Format

It is possible to create line breaks in expression results (not in the button labels). For adding a line break add \n in the text.

For example /custom_dice start buttons: '\n Attack: ' _ 1d20 + 10= _ '\n Damage: ' _ 2d6+3= @Attack&Damage answer_format: without_expression produces the following result:

image:image/multiLineResult.png[image,320]

All commands have an answer_format option that determines how the answer of a dice roll is shown. In the case of the direct roll command r the answer_format can be configured for the current channel with the channel_config command. There are the following options: full, without_expression, only_result, only_dice, compact and minimal.

==== Full

full is the default and shows result as multiline with avatar of the user, color coding and all details. Will show result images, if they are configured.

image:image/full.png[image,320]

==== Without expression

without_expression is the same as full but don't show the dice expression in the result. This is useful if the expression is very long and it is recommended to add a label. Will show result images, if they are configured.

image:image/without_expression.png[image,320]

==== Only Result

only_result shows only the calculated result and if configured the dice images. The expression, static modifier and the dice results as text will not be shown. This option is useful for buttons that only produce a text or emoji

image:image/only_result.png[image,320]

==== Only Dice

only_dice shows only dice results, if configured as images. The expression, static modifier and calculated results beside the dice will not be shown.

image:image/only_dice.png[image,320]

==== Compact

compact shows the result as single line (if there are multiple expressions in on roll, they will be displayed in multiple lines) and all details. Will not show result images, even if they are configured.

image:image/compact.png[image,320]

==== Minimal

minimal shows the result as single line with only the expression (or if available the label instate of the expression) and result, without the details like the result of each die. Will not show result images, even if they are configured.

image:image/minimal.png[image,320]

=== Dice Images

All commands have a dice_image_style and a dice_image_color option that can be configured to add an image of the rolled dice. To configure dice images for the direct roll, use the /channel_config save_direct_roll_config command. The color of specific dice can be overwritten, with valid colors for the style, in the expression. For example:

/custom_dice start buttons: 2d6+2d10 col 'red_and_gold' + 2d20 col 'green_and_gold'@color roll answer_format: without_expression dice_image_style: polyhedral_alies_v2 dice_image_color: blue_and_gold

produces:

image:image/colorRoll.png[image,320]

For the direct rolls it can be configured with the channel_config command. The images will only be shown if the following conditions are met:

• The answer_format is set to full, only_dice, only_result or without_expression
• No set of dice with more than 30 dice
• If the color of the dice is not