# Dice Specification

### Math-Only Rolls

You can do math-only rolls by using the operators: `+`, `-`, `*` (multiply), and `/` (divide).

You can also use `%` for modulus division (the result of `a % b` is the remainder of `a / b`) and `**` for exponentiation.

You can also use some mathematical functions:

• `floor(x)`: Round a number downward to its nearest integer
• `round(x)`: Round a number to the nearest integer (downward if < 0.5 and upward if >= 0.5)
• `ceil(x)`: Round a number upward to its nearest integer
• `abs(x)`: Return the absolute value of a number
• `log(x, base)`: Calculate the logarithm of a value. If no base is provided, uses `e`

### Simple Dice Rolls

Write the roll using the format `NdX`, where N is the number of times to roll (limited to 20) and X the sides of the die (limited to 1000). N must be greater than or equal to 0 and X must be greater than or equal to 1. You can omit N to roll a single die.

### Exploding Dice

mRPG supports exploding dice – you may also know it as "rule of 6", "rule of 10s", or "acing" depending on your game system. With exploding dice, if you roll the maximum number on the dice (a 6 with a d6, a 10 with a d10, etc.) you get to re-roll again and add the additional roll to your total for that roll. If the additional roll is also a maximum number, you get to keep rolling!

To perform a roll with exploding dice, just add an exclamation point after the number of sides in the formula. For example, `3d6!` would roll 3 d6 dice with exploding re-rolls. You can also define the exploding point for the dice using the greater-than and less-than symbols. For example, `3d6!>4` would explode on any dice greater-than or equal-to 4. `3d6!3` would explode only if a 3 is rolled.

### Penetrating Exploding Dice

HackMaster (and some other systems) use a special style of exploding dice where the the additional rolls for each dice have 1 subtracted from the roll. To do this, add a p after the exclamation mark. So for example to roll 5 d6's, you would do `5d6!p`

### Drop/Keep

Some game systems ask you to roll a large number of dice, and then either drop or keep only a certain number of the highest or lowest rolls. mRPG supports this type of roll through the `dl` (drop lowest), `dh` (drop highest), `kl` (keep lowest) and `kh` (keep highest) commands. `d` is a shortcut for `dl` and `k` is a shortcut for `kh`. You can also specify the number of rolls to keep.

For example, you might roll 8 d100 dice and only be allowed to keep the top 4 rolls. In mRPG this would be expressed with `8d100k4`. When mRPG prints the output from that roll, you'll see each individual d100's rolled value, and all but the top 4 rolls will be considered for the final result. Doing a roll to drop the 3 lowest rolls would be very similar: `8d100d3`.

### Target Number (Successes)

Normally when you perform a roll, mRPG reports back the total value of all the dice rolled, plus any modifiers. Some game systems, though, work by rolling a set of dice versus a target number, and then adding up the total number of successes instead. For example, you might be performing an action that requires a target number of 3, and you get to roll 3 d6's to see how many successes you have. In mRPG, you would do `3d6>=3`.

### Rerolling Dice

Several systems require that certain dice be reroll, effectively not allowing results lower than an minimum value.

To use reroll, just do `2d8r<=2`. mRPG will roll 2 d8 and reroll any 1s or 2s, dropping the original die value. `2d8r=8` will reroll any 8s. < and > can be used as comparisons and the r suffix can be specified multiple times. `2d8r=1r=3r=5r=7` would roll 2d8 and re-roll any odd number.

### FATE Dice’,

mRPG also supports FATE dice (used for FATE, FUDGE, and other systems). mRPG accurately simulates FATE dice as 6-sided dice in which two sides are `0`, two sides are `+1`, and two sides are `-1`.

To roll 4 FATE dice, just do `4dF`. mRPG will show you the result of each individual FATE dice roll, then give you the total of all the dice rolls added up together. You can also add a modifier onto the total, with `4dF+1`.

### Sorting Dice Results

You may want to see your results in either ascending or descending order. The sorting modifier does just this. The order parameter is optional and specifies the order to sort with `a` for ascending and `d` for descending. Sorting defaults to ascending if order is not specified.

### Conditionals and Logical Operations

You can use special functions to make conditional executions and logical operations. But first you need to understand what mRPG will consider as "true" (or 1):

• Any number higher than 0;
• Any string (`"some text"`) that is not empty;
• Dice rolls that reached the configured target number (successes);
• Successful relational math operations (`1 = 1`, `4 >= 1`, etc);

Anything other than that is considered as "false" (or 0).

These are the logical functions you can use:

• `if(condition, success, failure)`: If condition is true, return the second parameter, otherwise return the third parameter;
• `and(x1, x2, x3, ...)`: Return 1 if all parameters are true;
• `or(x1, x2, x3, ...)`: Return 1 if at least one parameter is true;
• `not(x)`: Inverts a logical result turning a 1 into a 0 and a 0 into a 1;

You can also use some number comparison functions: * `eq(n1, n2)`: Return 1 if numbers are equal; * `gt(n1, n2)`: Return 1 if n1 is greater than n2; * `gte(n1, n2)`: Return 1 if n1 is greater than or equal to n2; * `lt(n1, n2)`: Return 1 if n1 is less than n2; * `lte(n1, n2)`: Return 1 if n1 is less than or equal to n2;

OBS: You must use those functions to compare the result of a dice roll to a number. See the difference in the following example:

• `gt(2d20, 20)`: If the roll result is `[10, 15]` the sum is `25` , which is higher than `20`. So the result is `1` (true)

• `2d20 > 20`: If the roll result is `[10, 15]`, each die that is higher than `20` counts as a success. So the result is `0` (no successes) {ln}

You can mix and match these functions to get the result you want! For example: `if(or(d20>10,gt(3d6, 10)),d20+:damage:,"help")`

### Named Rolls (variables)

Register and retrieve values by name in the same expression. Very useful when writing conditional logic (use `IF`)

• `set(value, "name")`: Store `value` in `name`. The `value` can be a dice roll or the result of a previous function. This function returns the value stored (good for dice rolls);
• `get("name")`: Retrieve the value stored in `name`;

OBS: Be careful with the precedence of operators to not retrieve a value before it is set.

Some examples:

• `set(d20, "roll") + get("roll")`: `set(, "roll") + get("roll") = 26`

• `if( set(D20, "v") > 10, get("v"), "❌" )`: `if(set([<s>16</s>], "v") > 10, get("v"), "❌") = 16`

### Random value from a list

Get a random value from a list. Useful to simulate dice with custom faces or roll tables

• `pick(value1, value2, value3, ...)`: select a random item from the list;