The @RollButler is a random dice simulator with connection possibilities to various platforms like Discord, Telegram, Slack, Twitter, Facebook Messenger etc. The complete manual is currently only available in German language and correspondingly extensive due to its wide range of functions, so that only a quick guide is provided here.

Eine deutschsprachige Kurzanleitung findet sich hier.

How do I integrate the @RollButler or where can I use it?

• Discord (*)
• Telegram (*)
• Facebook Messenger
• Twitter
• Slack
• Alexa
• RollButler.net (*)

The interfaces marked with (*) are the preferred variants.

How do I use the @RollButler?

The @RollButler listens to text input (except for Alexa) and responds to messages that start with one of its commands. Commands start with a slash ‘/’ or a dot ‘.’. The most important commands are:

• /r (or /roll) to roll a dice or do some mathematics
• /pr (or /privateroll) to make a private (secret) roll
• /rev (or /reveal) to show the results of your last (secret) roll
• /rr (or /reroll) to repeat the last roll
• /cr to make a roll on a character skill
• /pcr to make a secret roll on a character skill
• /c (or /create) to create a random object
• /pc (or /privatecreate) to create a private (secret) random object
• /char to use a character sheet
• /x to play a x-card (safety mechanism)

Upper/lower case is generally irrelevant, both for the commands and the subsequent instructions. Also “/r” and “.r” lead to the same result.

For the purposes of this manual, the shortest possible spelling of commands is always used with the slash.

How do I roll with the @RollButler? (/roll command)

To let the @RollButler make a dice roll, the command /r (or /pr for a private roll) followed by a space is always placed before the actual dice instruction.

/r d

lets the @RollButler throw a six-sided dice. Alternatively, instead of ‘d’ (dice) you can also choose the German variant ‘w’ (Würfel).

/r w

For several cubes or cubes with a different side number, the values must be explicitly given. If you do not specify a number before the ‘d’ (or ‘w’), the system always assumes one cube. If no amount of sides is specified after the ‘d’ (or ‘w’), a six-sided cube is always assumed.

/r 2d10

rolls two ten-sided dice and returns the sum of the results, e.g. 11.

/r 4xd8

rolls four eight-sided dice and gives the results of the individual rolls, e.g. 2, 7, 1, 6.

/r 3d(0..9)

throws three dice with the values 0 to 9. The “…” instruction allows the sequence of numbers to be continued, so in this case it is replaced by 0;1;2;3;4;5;6;7;8;9.

/r 2d(0;2x1;2)

rolls two dice with four sides, with 0 and 2 on one side and a 1 on the other two sides. The “x” instruction repeats the value specified after the x according to the number specified before the x. 2×1 is therefore replaced by 1;1.

/r d{-3..3}

throws a die with the values -3 to 3, whereby a move without putting it back is practiced here, so each value occurs only once in the result.

/r d%

This is a special die, the percentage die. Two ten-sided dice are simulated, which when put together (tens and ones) give a value between 1 and 100.

/r d((1;"a");2;"a";3;2x(1;"b"))

describes a cube that partly has several values on one side:

1. 1 and a
2. 2
3. a
4. 3
5. 1 and b
6. 1 and b

Cube parameters

/r 10ds5

rolls 10 six-sided dice and counts each roll of 5 (and higher) as success

/r 10ds

If no value is given to a parameter (here: ‘s’), the highest possible (or lowest) dice result is automatically assumed. Here, 10 six-sided dice are thrown and only 6 are considered a success.

Possible parameters, which can be combined as desired, are

• s for success (greater or equal)
• t for trigger, special success (greater or equal)
• f for failure (less or equal)
• m for miss, special failure (less or equal)
• i to invert the evaluation of the following parameters (without value)
• g to group the dice results (without value)
• ! for single exploding dice (greater or equal)
• !! for recursively exploding dice (greater or equal)
• p to determine the number of even/odd dice results (without value)
• h to use only the highest values (amount)
• b to use only the lowest values (amount)

/r 8ds5tf

rolls eight six-sided dice, evaluates 5 and 6 as success, 6 as trigger and 1 as failure.

/r 5d10is2f

throws five ten-sided dice, evaluates (attention: inverted!) 1 and 2 as success and 10 as failure.

/r 4ds5!!

rolls four six-sided dice, counts 5 and 6 as a success and then repeats each roll with a 6 until there is no 6 left.

/r 10d4h5

rolls 10 four-sided dice, but only evaluates the 5 highest scores.

Inner rolls

The number of sides of a cube can be given additional options in round brackets to influence the number of throws and the selection of the result.

/r d10(2;H)

throws two ten-sided dice, but scores only the highest (H) value. The selection of the highest value is the default setting, so that the specification of “H” can also be omitted.

/r d%(1;3;L)

makes a percentage cast, using the ones digit only once, the tens digit three times and returns then the lowest (L = low) value

The fourth parameter that can be specified here is how a thrown 0/00 is to be interpreted: 0 or 100. 0/00 is interpreted as 100 if not specified.

/r d%(1;2;H;0)

does a percentage roll with one digit, two throws to the tens digit, selection of the highest value and 0/00 is counted as 0.

Comments

It is useful to add a comment to an instruction to be able to understand later what kind of roll it was. Comments can be introduced with a # or a ” and continue until the end of the instruction.

/r 3d12 # This is a comment
/r 2d8 " This is also a comment

Mathematical operators and comparisons

The @RollButler understands a variety of mathematical operators and functions that can be used with the cube instructions.

/r 1+1

Sum one and one, that’s two…

/r 2d8+3

rolls two eight-sided dice and adds 3 to the total.

/r 2d12-d4

rolls two twelve-sided dice and subtracts from the total the result of a four-sided die roll.

Possible calculation operators are

• + addition
• – subtraction
• * multiplication
• / division
• ^ power

/r d12+d>=7

rolls a twelve-sided and a six-sided die and compares the sum (greater or equal) to 7.

Possible comparison operators are

• < less
• <= less or equal
• == equal
• <> or != unequal
• >= greater or equal
• > greater

Functions

With numerous functions the calculation and evaluation of complex instructions can be realized. A function always consists of the function name followed by parameters enclosed in round brackets.

/r max(d4;d;d8;d10;d12;d20)

determines the highest value of throws with different dice.

Possible functions are

• above() Difference between two values or 0 (two parameters)
• abs() Absolute value (one parameter)
• avg() Average of values (at least one parameter)
• below() Difference between two values or 0 (two parameters)
• bmi() Body mass index (at least two parameters)
• ceil() Rounding up (one parameter)
• char() Using a value from the character sheet (at least one parameter)
• count() Amount of values (at least one parameter)
• countif() Number of values corresponding to x (at least two parameters)
• diff() Range between minimum and maximum value (at least two parameters)
• digitsum() Cross sum of values (at least one parameter)
• div() Division (two parameters)
• exactcollate() Number of groups that result in exactly x (at least two parameters)
• exp() Exponential function (one parameter)
• first() the first x values (at least two parameters)
• floor() Round off (one parameter)
• grade() Determine degree of success (two to five parameters)
• hash() Hash function (two parameters)
• if() If then branching (three parameters)
• kill() Suppression of the output (one parameter)
• last() the last x values (at least two parameters)
• lookup() Look-up function with exact match (at least three parameters)
• max() Maximum (at least one parameter)
• maxcollate() Number of groups with a maximum of x (at least two parameters)
• maxlookup() Lookup function with highest match (at least three parameters)
• md5() MD5 hash function (one parameter)
• med() Median (at least one parameter)
• min() Minimum (at least one parameter)
• mincollate() Number of groups that result in at least x (at least two parameters)
• minlookup() Look-up function with smallest match (at least three parameters)
• mix() Merge list (at least one parameter)
• mod() Modulus, remainder of an integer division (two parameters)
• or() Random selection from a list (at least two parameters)
• pow() Power function (two parameters)
• random() Random number (two parameters)
• rot13() Character rotation (one parameter)
• round() commercial rounding (one parameter)
• rsort() Sort list in descending order (at least one parameter)
• sha1() SHA1 hash function (one parameter)
• sort() Sort list (at least one parameter)
• sqrt() Square root function (one parameter)
• sum() Sum of values (at least two parameters)
• text() Text function (at least one parameter)
• xmax() the x largest values (at least two parameters)
• xmin() the x smallest values (at least two parameters)
• yahtzee() Evaluates parameters according to Kniffel/Yahtzee rules (five parameters)

Many of the functions also have a German language equivalent. Please refer to the complete documentation for this and for detailed instructions on the individual functions. The following is a small selection of examples of the most relevant functions.

/r above(d12;10)

if the result of the die roll (d12) is greater than 10, the difference is returned, otherwise 0.

/r countif(2;10xd;2xd8)

counts the number of 2 occurring in a roll of 10 six-sided dice and a roll of two eight-sided dice.

/r first(3;sort(12xd))

returns the first three values of an ascending sorted list of 12 six-sided dice.

/r if(3d>10;"large";"small")

throws three six-sided dice (3d) and compares the result with 10; if the result is larger, “large” is returned, otherwise “small”.

/r mincollate(10;12xd)

throws 12 six-sided dice (12xd) and tries to combine the individual results in such a way that as many groups as possible with a sum of at least 10 each are formed. Then returns the number of groups.

/r maxlookup(d4;2;"small";3;"medium";"else")

throws a four-sided die (d4) and compares the result with the following parameters. If the result is 2 or less, “small” is returned, if it is 3 or less, it is “medium”, and otherwise “else”. The last parameter is optional and is always used if no match was found in the previous comparison values.

/r text("Hello World!")

outputs the text “Hello World!”. The real power of this function, however, comes from the optional parameters.

/r text("Successes: $1 Trigger: $2";s(3ds5t);t($1))

rolls three six-sided dice and counts successes (5 and 6) and triggers (6). Then outputs the text “Successes: $1 Trigger: $2”, where $1 and $2 are replaced by the parameters 1 (number of successes: s(3ds5t)) and 2 (number of triggers: t($1)).

The placeholders $1, $2… in the text template reference the subsequent parameters of the function and should not be mistaken for the variables (see below) which are valid outside the text template. This may be a bit confusing, so here is a graphical explanation …

/r c("STA")

executes the instruction for the skill or the shortcut STA stored in the character sheet (see /char)

Dice functions

The dice instructions could be given various parameters to determine successes, failures, etc. To access these values, functions are used that require rolls as parameters. In addition, the dice instruction must at least have been given the corresponding parameter.

/r s(4ds5)+2

rolls four six-sided dice, evaluates 5 and 6 as successes, then returns only the number of successes and adds 2.

Possible dice functions are

• s() successes, requires parameter s
• f() failures, requires parameter f
• t() Trigger (trigger), requires parameter t
• m() Misses, requires parameter m
• p() Number of even (pair) results, requires parameter p
• o() Number of odd results, requires parameter p
• effective() Number of successes minus the number of failures, requires parameters s and f
• sum() Eye sum of the dice roll (standard)
• null() returns a 0, ignores the results of the dice roll
• g() returns the number of occurrences of identical numbers (group), requires the parameter g in the cube instruction and the value to be counted as the first value in brackets
• l() converts a dice roll into a list

/r g(2;10dg)

rolls 10 six-sided dice (10dg), but returns only the number of 2.

Variables

Variables are temporary storage areas where values may be stored. Variable identifiers always begin with a $ followed by a name.

/r $a=(3d10)

assigns the executed die roll 3d10 to the variable $a. Note that the assignment requires parentheses.

To retrieve the value of the variable again, only the variable identifier must be specified. This allows the same roll to be evaluated several times.

/r s($a=(3d10s8t))+t($a)

rolls three ten-sided dice with 8, 9 and 10 as success and 10 as trigger (3d10s8t). The roll is assigned to the variable $a. Then the number of successes (s()) and the number of triggers (t()) are summed and returned as result.

The @RollButler automatically assigns the throws to the variables $1, $2 … in the order in which they occur. Therefore the previous statement might also be used like:

/r s(3d10s8t)+t($1)

The character sheet option (see /char) can also be used to predefine variables. For example, if a skill value STA was created, it is available in the variable $STA.

/r d%<=$STA

runs a sample with a percentage roll (W100) against the value in $STA.

Logical operations

Especially in the context of the decision function if() logical operations can be relevant to connect several conditions with an “and” or “or”. The operators & (and) and | (or) are available for this purpose.

/roll (if(3ds>6&s($1);"Success";"no success")

In this case the message “Success” is only displayed if the sum of the dice roll (3ds) is greater than 6 and there was at least one six.

Internally, truth values are stored as 1 (true) and 0 (false). In the evaluation, every value deviating from 0 is interpreted as true.

How do I use a character sheets in @RollButler? (/char command)

The @RollButler can persistently save character sheets for each user. This is done with the command /char.

The easiest way to create a character sheet is to import a CSV file. The file can be created and edited e.g. in spreadsheet programs or text editors and should have the following format:

Shortcut,Name,Value,Formula

This can also represent the header line of the table. The values below it then look like this:

STA,Stability,45,d%<=$$

• The first field (here: STA) contains the shortest possible designation of the value, which is used for later function and value calls.
• The second field (here: Stability) contains a textual description for better readability.
• The third column (here: 45) contains the value itself.
• In the fourth column you can store a dice instruction that is used to test the skill. The special variable $$ is automatically replaced by a reference to the skill value of this row (here: $STA).

All other columns are ignored.

With the command

/char import() <CSV or JSON content>

the character sheet is then imported, where should be replaced with the content of the CSV (or JSON) file

Alternatively, or if it is necessary to adjust values of the character sheet, the following command can be used.

/char set STA=55

Here the skill value STA is set to 55.

/char export()

outputs the character sheet in JSON format. In this format it can be edited with a text editor or imported back into the @RollButler at a later time.

/rc STA

executes the dice instruction given in the character sheet at STA.

Alternatively the call also works via

/r c("STA")

You can access the skill value within your own roll instructions with the variable $STA, thus $:

/r d%<=$STA