/dice-parser

Try it out on the command line: `curl https://api.diceroll.dev`

Primary LanguageKotlinApache License 2.0Apache-2.0

Maven Central License

Dice Notation Parser for Kotlin and Java

Java Usage:

import dev.diceroll.parse.Dice;
...

// evaluate an expression and return an integer 
        int result=Dice.roll("2d6");

// or

// evaluate an expression and return a tree, which contains the values of the individual dice rolled 
        ResultTree resultTree=Dice.detailedRoll("2d6");
        int result=resultTree.value();

Kotlin Usage:

import dev.diceroll.parser.roll
import dev.diceroll.parser.detailedRoll

...

// evaluate an expression and return an integer 
val result: Int = roll("2d6")

// or

// evaluate an expression and return a tree, which contains the values of the individual dice rolled 
val resultTree: ResultTree = detailedRoll("2d6")
val result: Int = resultTree.value()

Supported Notation

Name Notation Example Description
Single Die d<numberOfFaces> d6 roll one, six-sided die
Multiple Dice <numberOfDice>d<numberOfFaces> 3d20 roll three, twenty-sided dice
Keep Dice <numberOfDice>d<numberOfFaces>k<numberOfDiceKept> 3d6k2 keeps the the highest values out of three, six-sided dice
Keep Low Dice <numberOfDice>d<numberOfFaces>l<numberOfDiceKept> 3d6l2 keeps the the lowest values out of three, six-sided dice
Multiply Dice <numberOfDice>d<numberOfFaces>X 4d10X multiplies the result of 4d10 * 4d10
Fudge Dice dF dF roles a single "fudge" die (a six sided die, 1/3 chance of -1, 1/3 chance of 0, and 1/3 chance of 1)
Multiple Fudge Dice <numberOfDice>dF 3dF roles multiple fudge dice
Weighted Fudge Die dF.<weight> dF.1 A weighted fudge die with 1/6 chance of a 1, 2/3 chance of a 0 and 1/6 chance of a -1
Multiple Weighted Fudge Dice <numberOfDice>dF.<weight> 2dF.1 multiple weighted fudge dice.
Exploding Dice <numberOfDice>d<numberOfFaces>! 4d6! any time the max value of a die is rolled, that die is re-rolled and added to the total
Exploding Dice (Target) <numberOfDice>d<numberOfFaces>!><target> 3d6!>5 Same as exploding dice, but re-roll on values greater than or equal to the target (note, less than works too)
Compounding Dice <numberOfDice>d<numberOfFaces>!! 3d6!! similar to exploding dice, but ALL dice are re-rolled
Compounding Dice (Target) <numberOfDice>d<numberOfFaces>!!><target> 3d6!!>5 similar as exploding dice (target), but all dice are re-rolled and added.
Target Pool Dice <numberOfDice>d<numberOfFaces>[>,<,=]<target> 3d6=6 counts the number of dice that match the target (NOTE: greater & less than also match equals, i.e >= and <=)
Target Pool Dice (Expression) (<expression>)[>,<,=]<target> (4d8-2)>6 A target pool roll, but where the expression is evaluated to the target.
Integer <int> 42 typically used in math operations, i.e. 2d4+2
Math <left> <operation> <right>
Add <left> + <right> 2d6 + 2
Subtract <left> - <right> 2 - 1
Multiply <left> * <right> 1d4 * 2d6
Divide <left> / <right> 4 / 2
Negative -<diceExpression> -1d6 multiplies the result of the dice expression with -1
Oder <diceExpression>[asc, desc] 10d10asc ordering the results of the dice ascending (asc) or descending (desc)
Min/Max <diceExpression>[min, max]<diceExpression> 2d6min(1d6+3) returns the minimum or maximum of two dice expressions, e.g. 2d6min(1d6+3) returns the smaller value of 2d6 and 1d6+3

Dependency Information

Maven:

<dependency>
    <groupId>dev.diceroll</groupId>
    <artifactId>dice-parser</artifactId>
    <version>${version}</version>
</dependency>

Gradle

implementation 'dev.diceroll:dice-parser:${version}'