Command aliases: r, roll
Rolls dice based on a string input, giving output via a reply box in the channel the command was run.
The input syntax is standardised to aid in ease of use between Reggy’s dice rolling abilities and those of other software.
Input may occur in the following syntax: QdS(kdhlX)(modifier).
Q = quantity of dice to roll.
S = number of sides per-die.
(kdhlX) = Keep or drop highest or lowest X number of dice.
modifier = Modifier to apply to the roll.
Example die rolls:
1d20, 2d4+4, 1d20+1d4, 1d20+3, 1d4*2, 4d6dl1, 4d6kh3, 2d20a
Certain common dice rolls have been built in to Reggy as shortcuts, making it easier to roll them by their common names. Each common roll built in is provided below, with its name on the left and the rolled dice on the right.
simple = 2d6,
check = 1d20,
advantage = 2d20a,
disadvantage = 2d20d,
dnd\\s*start\\s*stats = 4d6dl1 4d6dl1 4d6dl1 4d6dl1 4d6dl1 4d6dl1,
In some dice rolling operations, you will need to roll a set number of die and either keep or drop some of them. These functions allow you to do this easily and naturally, without going through a lot of extra effort.
To roll using this, the syntax must first be broken down.
a = Advantage.
d = Disadvantage.
kX = Keep X.
dX = Drop X.
Xh = X highest.
Xl = X lowest.
Using the above, we can form all options where keeping or dropping certain numbers of dice can be achieved. Typical advantage, a, consists of rolling two of a given die and dropping the lowest. Disadvantage is the opposite—rolling two of a given die an dropping the highest (or keeping the lowest).
There are cases where this may not be useful, such as when rolling for starting player hit points in Dungeons and Dragons. To allow this mechanism of rolling, we can use the KDHL syntax. There are two letter groups, which we can split into function and qualifier. The function determines whether we are keeping (K) or dropping(D), and the second determines whether this applies to the highest (H) or lowest (L) rolls. Rolling our example, we would use 4d6kh3 or 4d6dl1. These produce the same output.
On failure to roll a dice for any reason, a DiceError is thrown with a corresponding error code, starting with the character D. All DiceError instances are accompanied by a stacktrace in the console.
D0Error title: Unknown dice error!
Error message: I don't know what happened! Contact my operator!\n-# Irredeemable...
This error code is given when the error cause is not able to be determined or has not been signalled. If this error is thrown, the debug console should be consulted and the stacktrace followed to identify and address the cause.
D1Error title: Too few dice!
Error message: Irredeemable! You can't roll fewer than ONE dice, silly!\n-# I should tell leader about this...
Dice rolls require a minimum of one dice, otherwise we are simply doing basic maths and that’s what people have calculators for.
D2Error title: Too many dice!
Error message: Irredeemable! You have asked for too many rolls! Don't try make me roll more than 100, otherwise I will tell leader!
To avoid Reggy consuming excessive resources or posting messages that may exceed Discord’s message character limits, Reggy is hard-limited to roll no more than 100 dice in any single roll. This does not, however, stop people from rolling 80d4+80d4, for example, to roll 160 dice.
D3Error title: I need a dice with sides!
Error message: Irredeemable! All dice rolled must have at least TWO sides!
A user attempted to roll a dice with two or fewer sides, or never specified a number of sides.
D4Error title: Too many sides!
Error message: At least one die has too many sides. You can have 1000 sides, at most!
To avoid excessive calculations, dice are limited to having 1000 sides.
D5Error title: Modifier out of bounds!
Error message: One or more roll modifiers are too high or too low.
The modifier exceeds acceptable bounds. This error is currently unimplemented, but exists in case circumstances arises that require it.
D6Error title: Unknown math error!
Error message: Irredeemable! Somehow your maths created infinity!\n-# Make sure you are not dividing by zero!
An error occurred during the evaluation of mathematical sums. This error will always be accompanied by a stacktrace on the debug console. To attempt to resolvet this error, the debug console should be reviewed.
D7Error title: Incorrect dice quantity!
Error message: Rolling with advantage or disadvantage requires exactly TWO dice! No more, no less!
This error occurs when using the advantage or disadvantage dice rolling syntax with any quantity of dice that is not exactly two. Advantage or disadvantage works by rolling two dice, and dropping one of them.
D8Error title: KDHL invalid!
Error message: You must drop at least one die when rolling keep/drop-highest/lowest (KDHL) clauses.
In KDHL clauses, at least one die must be dropped in order for the clause to be valid. If the user does not want to drop or keep any die, either they should not use KDHL or they should not roll any dice.
D9Error title: Too few dice!
Error message: You need to roll TWO or more dice when doing rolling advantage, disadvantage, or keep/drop-highest/lowest (KDHL) clauses.
This error triggers when it is detected that someone is rolling advantage, disadvantage, or a KDHL clause, but has not rolled a minimum of two dice. This is the first gateway error in the KDHL handling chain and occurs when either advantage/disadvantage or KDHL is detected. As a minimum of two dice are needed for any set of rolls, this check occurs before determining which of these type of roll will be performed.
D10Error title: KDHL invalid!
Error message: You cannot keep or drop more dice than you're rolling when rolling keep/drop-highest/lowest (KDHL) clauses.
D11Error title: Invalid roll operator!
Error message: You tried to run a mathematical operation on a roll result which does not exist!
This error is currently unused.
D12Error title: Nothing was done!
Error message: None of your input seems to contain rollable dice. Check it's all correct and valid syntax!
To prevent abusing Reggy as a calculator, Reggy will not perform any operation that does not directly involve rolling dice.
D13Error title: Calculation failure.
Error message: I couldn't perform this roll. I'm sorry... I don't know what happened...
An unknown error occurred during the calculation and resolution phase of mathematical sums. This error occurs only when another exception is caught that is not a DiceError. In this case, the error is also dumped to the console.
D14Error title: No input!
Error message: You didn't give me anything to do!\n-# That is *absolutely* irredeemable!
A dice roll was attempted with no input.
D15Error title: Output too large!
Error message: The total number of output lines is too many for me to show!
Discord has a hard limit on the quantity of output lines a message can have. If the compiled output exceeds this line count, it is replaced with this error instead.