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. If the message is pined, then it will only be copied and not moved. This allows user to roll dice without typing commands and thereby improves usability, especially for touchscreen users. The bot supports Discord thread (the button message must be added after the thread creation), forum, Text in Voice, 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.
Add to Discord channel by following this link: Bot invite link
Discord Server for trying the bot, questions and feature suggestions: 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)
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
Some example for commands, many more systems can be mapped, please see in the detail’s description below for further options
/quickstart system:Dungeon & Dragons 5e with Dice Images
or
/custom_dice buttons: 1d4;1d6;1d8;1d10;1d12;1d20;1d100;2d20k1@D20 Advantage;2d20L1@D20 Disadvantage;2d4=@2d4;2d6=@2d6;2d8=@2d8;2d10=@2d10;2d12=@2d12;2d20=@2d20 answer_format: without_expression dice_image_style: polyhedral_RdD dice_image_color: default
/quickstart system:OSR
or
/custom_dice start buttons:1d20@D20;1d6@D6;2d6@2D6;1d4@D4;1d8@D8;6x3d6=@Stats;(3d6=)*10@Gold;1d100@D100;1d10@D10;1d12@D12
/quickstart system: Fate with Dice Images
or
/custom_dice expression: 4d[-1,0,1]+{Modifier:-4<=>10}= answer_format: without_expression dice_image_style: fate dice_image_color: black
/quickstart system: nWod / Chronicles of Darkness
or
/custom_parameter start expression: {Number of Dice}d!10>=8c
/quickstart system: oWod / Storyteller System
or
/custom_parameter start expression:val('$diceNumber',{Number of Dice}) val('$target', {Target Number:2<=>10}) val('$reroll', {Reroll on 10:0@No/1@Yes}) val('$roll', if('$reroll'=?0, '$diceNumber’d10,'$diceNumber’d!10)) ('$roll'>='$target’c) - ('$roll'==1c)=
/quickstart system: Shadowrun
or
/custom_parameter start expression:/val('$roll',{number of dice:1<=>20}d6) concat('$roll'>4c, if('$roll'==1c >? '$roll’c/2,' - Glitch!'))
/quickstart system: Savage Worlds
or
/custom_parameter start expression: (d!!{Dice:4@D4/6@D6/8@D8/12@D12/20@D20} + {Type: 0@Regular/1d!!6@Wildcard})k1
/quickstart system: Traveller
or
/sum_custom_set start buttons:+2d6;+(3d6k2)@Boon;+(3d6l2)@Bane;+1d6;+1;+2;+3;+4;-1;-2;-3;-4
/quickstart system: Blades in the Dark
or
/custom_dice start buttons: ifE(2d[0/0/0/1/1/3]l1,3,'Success',1,'Partial','Failure')@Zero;ifE(1d[0/0/0/1/1/3],3,'Success',1,'Partial','Failure')@1d6;ifG(2d[0/0/0/1/1/3]k2=,5,'Critical',2,'Success',0,'Partial','Failure')@2d6;ifG(3d[0/0/0/1/1/3]k2=,5,'Critical',2,'Success',0,'Partial','Failure')@3d6;ifG(4d[0/0/0/1/1/3]k2=,5,'Critical',2,'Success',0,'Partial','Failure')@4d6;ifG(5d[0/0/0/1/1/3]k2=,5,'Critical',2,'Success',0,'Partial','Failure')@5d6;ifG(6d[0/0/0/1/1/3]k2=,5,'Critical',2,'Success',0,'Partial','Failure')@6d6;ifG(7d[0/0/0/1/1/3]k2=,5,'Critical',2,'Success',0,'Partial','Failure')@7d6
/quickstart system: Call of Cthulhu 7th Edition
or
/custom_dice start buttons: 1d100; 2d100L1@1d100 Advantage; 2d100K1@1d100 Penalty; 1d3; 1d4; 1d6; 1d8; 1d10; 1d12; 1d20; 3d6
/quickstart system: Dice Calculator
or
/sum_custom_set start buttons: 7;8;9;+;-;4;5;6;d;k;1;2;3;0;l always_sum_result: true
/quickstart system: Exalted 3ed
or
/custom_parameter start expression: val('$1', cancel(double({number of dice:1<=>24}d10,10),1,[7/8/9/10])), ifE'$1'>=7)c,0,ifG(('$1'<=1)c,0,'Botch'
/quickstart system: Vampire 5ed
or
/custom_dice expression: val('$r',{regular dice:1<=>16}d10 col 'blue') val('$h',{hunger dice:0<=>5}d10 col 'purple_dark') val('$s',('$r''$h')>=6c) val('$rt','$r'==10c) val('$ht','$h'==10c) val('$ho','$h'==1c) val('$2s',((('$rt''$ht'=))/2)*2) val('$ts',('$s'+'$2s'=)) concat('successes: ', '$ts', ifE('$ts',0,ifG('$ho',1,' bestial failure' , ''),''), ifE('$rt' mod 2, 1, ifE('$ht' mod 2, 1, ' messy critical', ''), '')) answer_format: without_expression dice_image_style: polyhedral_knots dice_image_color: blue
/quickstart system: One-Roll Engine
or
/custom_parameter start expression: groupc({Number of Dice:1<=>10}d10+({Number of Extra Die:0@0/10@1/2r10@2/3r10@3/4r10@4})>={Difficulty:1<=>10})
/quickstart system: Rêve de Dragon
or
/custom_dice start buttons: 1d4@D4;1d6@D6;2d6=@2D6;1d7@D7;1d8@D8;val('roll',1d!8 col 'special') val('diceCount','roll' c) 'roll'-'diceCount'+7=@DDR;2d10=@2D10;1d12@D12;val('$r',1d12 col 'special'),if('$r'=?1,'vaisseau','$r'=?2,'sirène','$r'=?3,'faucon','$r'=?4,'couronne','$r'=?5,'dragon','$r'=?6,'épées','$r'=?7,'lyre','$r'=?8,'serpent','$r'=?9,'poisson acrobate','$r'=?10,'araignée','$r'=?11,'roseaux','$r'=?12,'château dormant')@DAS;1d20@D20;1d100@D100 answer_format: without_expression dice_image_style: polyhedral_RdD
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.
The bot supports multiple languages (currently English, German and Brazilian Portuguese).
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 additonal language and improvements are very welcome.
Type `/quickstart system' and the bot will offer a list of ready to play dice sets. Simple select a system out of the list or keep typing to search and filter in the list. Please let me know if you’re missing an RPG system in the quickstart list.
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, compact and minimal.
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.
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.
only_dice shows only dice results, if configured as images.
The expression, static modifier and calculated results beside the dice will not be shown.
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.
The custom_dice, sum_custom_dice and custom_parameter commands have a dice_image_style and a dice_image_color option that can be configured to add an image of the rolled dice.
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:
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_formatis set tofullorwithout_expression -
No set of dice with more than 30 dice
-
No multi line result
There are the following options:
Valid for d4, d6, d10, d8, d12, d20, d100 and the only supported color is: red_and_white
Valid for d6 and the only supported color is: white and black_and_gold
The by black_and_gold was adapted from Dicier.
Valid for d4, d6, d10, d8, d12, d20, d100 and the supported colors are: white, gray, black, red, pink, orange, yellow, green, magenta, cyan, blue and indigo.
Valid for d4, d6, d10, d8, d12, d20, d100 and the only supported color is: black_and_gold
This set was designed and contributed by alieinbeanland.
Valid for d4, d6, d10, d8, d12, d20, d100 and supported colors are: black_and_gold, blue_and_silver, blue_and_gold, green_and_gold, orange_and_silver, red_and_gold, purple_and_silver
This set was designed and contributed by alieinbeanland.
Valid for d4, d6, d10, d8, d12, d20, d100 and the supported color is: blue, purple_dark and purple_white
This set was designed and contributed by Myrynvalona.
The style has two "colors": default and special.
The default "color" contains universal images for d4, d6, d7, d10, d8, d12, d20, d100.
The special "color" contains only images for Draconic d8 (image values are 0 to 7 and a dragon for the 8) and Astral d12 with only special symbols.
This set was designed and contributed by scriptarium.org.
Use the slash command: custom_dice start and add up to 25 custom buttons, each with its own dice expression (see the section Dice Expression Notation).
The expressions for the buttons are seperated by ;.
For example /custom_dice start buttons:3d6@Attack;10d10;3d20 will produce three buttons, one with 3d6 (and the label Attack), one with 10d10 and one with 3d20.
Clicking on a button provides the results of the button dice expression.
It is possible to use alias with custom dice buttons.
The alias must be created before the button is created.
A usage example would be:
Create the server alias attack modifier with the value 0.
Then create a custom dice button with the expression d20+attack modifier@Attack and each player create a user alias for attack modifier with the attack modifier of its character.
This will provide a button called Attack which rolls with a personalized modifier for each player.
Use for example the slash command /custom_parameter expression:{numberOfDice:1<=>10}d{sides:4@D4/6@D6/8@D8/12@D12/20@D20} to create a message with a dice expression, where the user can fill the parameter with buttons.
For the dice expression see the section Dice Expression Notation.
The parameter have the format {name}.
If there is no range given, then button for the values 1-15 are presented.
There are two parameter range notations:
-
{numberOfDice:1<=>10}: Provides the buttons for the given range (including). The maximum are 23 buttons. -
{sides:4/6/8/10/12/20}: Provides each value, seperated be a slash up to 23 buttons. It is possible to add an optional label to each value in the formatvalue@label. For example{bonus:0@None/3@Small Bonus/5@Big Bonus}will show on the buttons 'None', 'Small Bonus' and 'Big Bonus' but apply the values 0, 3 or 5 to the expression
An expression can have up to 4 parameter.
The user can click on the buttons to fill all open parameter of the expression.
If all parameter are selected then the expression will be rolled.
The first user that clicks on a button add his name to the message and only this user can select further parameter.
Every user can still use the Clear button.
The command uses the without_expression as default answer format.
Use the slash command /sum_custom_set start buttons:+1d6;+1d20;+1@Boon;-1@Bane to create a message with a custom dice set.
In this case it will create four buttons: 1d6,1d20,+1@Boon and -1@Bane.
The user can click on a button to add it to the set, even multiple times.
The first user that clicks on a button add his name to the message and only this user can add, remove or roll dice.
Every user can still use the Clear button.
Clicking on the Roll button will roll the dice the message and copy a clear button message to the end.
The Roll can only be clicked if the expression is valid. Back will undo the last addition and Clear reset all.
The buttons can be created with the dice notation, see the section Dice Expression Notation and are seperated by ;.
The text after an optional @ will be used as label for the button.
If the option always_sum_result is true (the default) then the result of the dice will be added together, the equivalent of adding = at the end of the expression.
If the option hide_expression is true (the default) then the result and the message with the current expression will show the label of the buttons and the expression only if the button has now specific label.
If it is set to false then it will show always the expression.
This command can also use alias (see the channel_config command).
The substitution of the alias name with its value happen upon pressing the Roll button.
If there is no valid alias then the expression can be invalid and it is not possible to press the Roll button.
With the command /r it is possible to directly call the dice expression (see Dice Expression Notation) without the usage of buttons.
For example /r expression:3d6 will simply roll 3d6 and post the result without showing any buttons.
The result of the dice will be summed up per default.
The output can be configured with the channel_config command.
Hidden Direct Roll
With the command /h it is possible to directly call the dice expression (see Dice Expression Notation) like Direct Roll but the answer is initial only visible to the user and can be revealed to other user by pressing on the button "Reveal".
For example /h expression:3d6 will simply roll 3d6 and show only the current user the result.
The result of the dice will be summed up per default.
The output can be configured with the channel_config command.
This command is used create a channel specific configuration. It is possible to configure alias and the output for the direct rolls:
The command can be configured for a channel by using the /channel_config save_direct_roll_config command.
The configuration will be used for all /r in this channel until it is overwritten or deleted with /channel_config delete_direct_roll_config.
There are the following options:
-
answer_format: see the Answer Format for details, the default value isfull. -
always_sum_result: if the result should always sum together. If set to false the3d6would return the result for each die, not the sum of all three. This can still be done by using the sum operator=e.g.3d6=. The default value is true -
image_result: see Dice Images for details, the default value ispolyhedral_3d_red_and_white
It is possible to configure alias in a channel. Alias can be used with direct roll and custom dice. If a custom dice button is created that should use an alias, the alias musst exist before the button is created.
For example /channel_config user_channel_alias save name: att value: (2d20k1)+10+1d4 creates an attack alias for the user.
Each time the user uses the slash command /r expression: att, the att will automatically replaced with (2d20k1)+10+1d4
An alias has a name and a value and will replace each occurrence in the dice expression of its name with its value. There are two types of alias, channel alias and user channel alias. A channel alias will be applied to each roll in a channel, for every user. The user channel alias will only apply to for the user who created the alias in the channel. The user channel alias will be applied first. Three are four commands for each type.
-
savecreates or overwrites an alias -
multi_savecreates or overwrites multiple alias. Alias are seperated by;and the name and the value are seperated by:. For example:/channel_config channel_alias multi_save aliases: att:2d20;dmg:2d6+4=saves two alias:-
attwith2d20 -
dmgwith2d6+4=
-
-
deleteremoves an alias by its name -
listprovides a list of all alias
The clear command removes all button configuration in a channel from the bot and deletes the button messages.
This command can be used to develop new expressions and get a fast feedback if the expression has the correct syntax. Upon typing the autocomplete will be open and show the typed expression if it has a valid syntax and can be executed. If the expression is invalid it will show the first 100 characters of the error message. To get the complete error message press enter twice (even if the autocomplete will replace the expression with the error text). The autocomplete validation will not apply alias. This command will change when discord improves the autocomplete.
see https://github.com/twonirwana/DiceEvaluator for all details.
The evaluator processes dice expression and returns a list of rolls, each containing a list of elements.
Elements have a value (a number or a text) and can have a color.
For example 2d6 rolls two six-sided dice and returns a list with two elements, each with a value between 1 and 6. To get the sum of the roll, simple add a = at the end, for example in this case 2d6=.
The same applies to numbers 3 + 5 has as result a list with the elements 3 and 5, only if written as 3 + 5= the result is 8.
All non-functional text must be surrounded (escaped) by '. For example 1d('head' + 'tail') will flip a coin.
List can be included into the expression by using square brackets.
An empty list [] or empty literal '' are non value.
For example 1d[2,2,4,4,6,6] will a die which has two sides with 2, two sides with 4 and two sides with 6. The roll will be a list with one element, which has a value of 2, 4 or 6. Lists also escape characters, so 1d[head,tail] will also flip a coin.
Multiple expression can be separated by ,.
For example 3d6, 4d8 will roll two six-sided dice and return a list with two rolls, the first one containing the roll elements of the 3d6 and the second one the roll of the 4d8.
Operators have a precedent, which is defined by the order of the operators in the table below.
Operators with a higher precedence are evaluated first.
Brackets can be used to change the order of evaluation.
For example 1d4+3d6 is the appending of roll of 1d4 and 3d6, but (1d4+3=)d6) gets first the sum of the roll of 1d4 and 3 and then rolls this number of d6.
The number of dice is limited to 1000 and every number approve 10 digits or with more than 10 digit after the decimal dot result in an error.
Boolean values will be represented by 'true' and 'false'.
It is possible to set tags and color. Colors have no direct effect and will be also set to all random elements of the expression. Tags on the other hand wil change the interaction of with other operators, in most cases operators will work only on elements with the same tag.
All operators are case insensitiv.
| Name | Notation | Example | Description | Precedent | Associativity | Left parameter | Right parameter |
|---|---|---|---|---|---|---|---|
Repeat |
|
|
Repeats the expression separately a number of times given in <number>. This should be used outside other expressions and will not work inside most expressions |
0 |
left |
a single integer number between 1-10 |
a expression |
List Repeat |
|
|
Repeats the expression a number of times given in <number> and combines the results in one list. |
1 |
left |
a single integer number between 0-10 |
a expression |
Concat |
|
|
Combines the result of both expression into on single element |
2 |
left |
one or more elements |
one or more elements |
Or |
|
|
Boolean or operation of the two boolean values |
3 |
left |
boolean value |
boolean value |
And |
|
|
Boolean and operation of the two boolean values |
4 |
left |
boolean value |
boolean value |
And |
|
|
Negates the boolean value right from it |
5 |
right |
boolean value |
|
Equal |
|
|
Compare the left and the right and returns true if equal and false otherwise |
6 |
left |
one or more elements |
one or more elements |
Lesser |
|
|
Compare the left and the right and returns true if |
7 |
left |
a single number |
a single number |
Lesser Equal |
|
|
Compare the left and the right and returns true if |
8 |
left |
a single number |
a single number |
Greater |
|
|
Compare the left and the right and returns true if |
9 |
left |
a single number |
a single number |
Greater Equal |
|
|
Compare the left and the right and returns true if |
10 |
left |
a single number |
a single number |
In |
|
|
Returns true if every element in left is contained in right otherwise false |
11 |
left |
a one or more elements |
one or more elements |
Sum |
|
|
Sums the list of on the left side of the symbol |
12 |
left |
a list of numbers |
- |
Modulo |
|
|
returns the remainder of the division |
13 |
left |
a single integer number |
a single non zero integer number |
Multiply |
|
|
Multiplies the right number with the left number |
14 |
left |
a single number |
a single number |
Divide |
|
|
Divides the right number with the left number and rounds down to the next full number |
15 |
left |
a single integer number |
a single integer number |
Decimal Divide |
|
|
Divides the right number with the left number and provides a decimal number with up to 5 decimal digital |
16 |
left |
a single number |
a single number |
Count |
|
|
Counts the number of elements in a list |
17 |
left |
a list |
- |
Greater Then Filter |
|
|
Keeps only the elements of the left list that are bigger as the right number. Applies only to elements with the same tag. |
18 |
left |
one or more numbers |
a single number |
Lesser Then Filter |
|
|
Keeps only the elements of the left list that are lesser as the right number. Applies only to elements with the same tag. |
19 |
left |
one or more numbers |
a single number |
Greater Equal Then Filter |
|
|
Keeps only the elements of the left list that are bigger or equal as the right number. Applies only to elements with the same tag. |
20 |
left |
one or more numbers |
a single number |
Lesser Equal Then Filter |
|
|
Keeps only the elements of the left list that are lesser or equal as the right number. Applies only to elements with the same tag. |
21 |
left |
one or more numbers |
a single number |
Equal Filter |
|
|
Keeps only the elements of the left list that are equal to the element. Applies only to elements with the same tag. |
22 |
left |
one or more elements |
a single elements |
Keep Highest |
|
|
keeps the highest values out a list, like the roll of multiple dice. Applies only to elements with the same tag. |
23 |
left |
one or more elements |
a single number |
Keep Lowest |
|
|
keeps the lowest values out a list, like the roll of multiple dice. Applies only to elements with the same tag. |
24 |
left |
one or more elements |
a single number |
Appending |
|
|
Combines the rolls of both sides to a single list. If used as unary operator, it will be ignored e.g. |
25 (max for unary) |
left for binary and right for unary |
none or more elements |
one or more elements |
Negative Appending |
|
|
Combines the rolls of both sides to a single list. The right side is multiplied by -1. |
26 |
left for binary and right for unary |
none or more elements |
one or more numbers |
Reroll |
|
|
Reroll the whole |
27 |
left |
one or more elements |
one or more elements |
Tag |
|
|
Set a tag to all elements of an expression, most operator work on elements with the same tag. The tag will be appended to the name but a number remains a number, even with a text tag. |
28 |
left |
one or more elements |
a single text |
Color |
|
|
Set a color to all elements, and all in it involved random elements, of an expression. The color will not directly given in the result and has no effect on other operations |
29 |
left |
one or more elements |
a single text |
Exploding Add Dice |
|
|
Throws dice and any time the max value of a die is rolled, that die is re-rolled and added to the die previous resul total. A roll of the reroll the sum of the value. |
30 |
left for binary and right for unary |
none or a single positiv integer number (max 1000) |
a single integer number |
Exploding Dice |
|
|
Throws dice and any time the max value of a die is rolled, that die is re-rolled and added to the dice set total. A reroll will be represented as two dice roll elements |
31 |
left for binary and right for unary |
none or a single integer number (max 1000) |
a single positiv integer number |
Regular Dice |
|
|
Throws a number of dice given by the left number. The number sides are given by the right number. If the right side a list, an element of the list is randomly picked. The roll is a list with the dice throw |
32 |
left for binary and right for unary |
none or a single integer number (max 1000) |
a single positiv number or multiple elements |
All functions are case insensitiv.
| Name | Notation | Example | Description |
|---|---|---|---|
min |
|
|
returns the smallest elements (multiple if the smallest is not unique) of one or more inner expressions. Text is compared alphabetically |
max |
|
|
returns the largest elements (multiple if the largest is not unique) of one or more inner expressions. Text is compared alphabetically |
sort asc |
|
|
sorts all elements ascending of one or more inner expressions. Text is compared alphabetically |
sort desc |
|
|
sorts all elements descending of one or more inner expressions. Text is compared alphabetically |
chancel |
|
|
the elements of listA and listB (can also be single elements) chancel each other and remove each other from the result. |
replace |
|
|
each element in |
if |
|
|
if |
group count |
|
|
counts all elements of with the same value and provides the results as list in the format of |
concatenate |
|
|
Joining all expressions together to a single result. |
value |
|
|
Defining a value (that get evaluated once) that can be used in multiple times in the same expression. The value name must be surrounded by two |
-
Special thank to alieinbeanland for the design of the dice images for
polyhedral_alies_v1andpolyhedral_alies_v2 -
Special thank to Myrynvalona for the design of the dice images for
polyhedral_knots -
Special thank to scriptarium.org for creating the dice images for
polyhedral_RdD -
Special thank to igorteuri for the brazilian prologuise translation
-
The
polyhedral_3ddice images where adapted from https://blendswap.com/blend/16634 -
The
d6_dotinwhitedice images are from https://game-icons.net/ -
The
d6_dotinblack_and_golddice images are adapted from https://speakthesky.itch.io/typeface-dicier and the Infinite Revolution RPG