https://github.com/diceroll-dev/dice-parser
Try it out on the command line: `curl https://api.diceroll.dev`
https://github.com/diceroll-dev/dice-parser
dice java kotlin
Last synced: 5 months ago
JSON representation
Try it out on the command line: `curl https://api.diceroll.dev`
- Host: GitHub
- URL: https://github.com/diceroll-dev/dice-parser
- Owner: diceroll-dev
- License: apache-2.0
- Created: 2020-04-02T22:23:53.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2025-11-21T14:09:37.000Z (7 months ago)
- Last Synced: 2025-11-21T16:08:01.166Z (7 months ago)
- Topics: dice, java, kotlin
- Language: Kotlin
- Homepage:
- Size: 266 KB
- Stars: 9
- Watchers: 1
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[
](https://github.com/diceroll-dev/dice-parser/)
[](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22dev.diceroll%22%20a%3A%22dice-parser%22)
[](https://opensource.org/licenses/Apache-2.0)
# Dice Notation Parser for Kotlin and Java
Java Usage:
```java
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:
```kotlin
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` | `d6` | roll one, six-sided die |
| Multiple Dice | `d` | `3d20` | roll three, twenty-sided dice |
| Keep Dice | `dk` | `3d6k2` | keeps the the highest values out of three, six-sided dice |
| Keep Low Dice | `dl` | `3d6l2` | keeps the the lowest values out of three, six-sided dice |
| Multiply Dice | `dX` | `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 | `dF` | `3dF` | roles multiple fudge dice |
| Weighted Fudge Die | `dF.` | `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 | `dF.` | `2dF.1` | multiple weighted fudge dice. |
| Exploding Dice | `d!` | `4d6!` | any time the max value of a die is rolled, that die is re-rolled and added to the total |
| Exploding Dice (Target) | `d!>` | `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 | `d!!` | `3d6!!` | similar to exploding dice, but ALL dice are re-rolled |
| Compounding Dice (Target) | `d!!>` | `3d6!!>5` | similar as exploding dice (target), but all dice are re-rolled and added. |
| Target Pool Dice | `d[>,<,=]` | `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) | `()[>,<,=]` | `(4d8-2)>6` | A target pool roll, but where the expression is evaluated to the target. |
| Integer | `` | `42` | typically used in math operations, i.e. `2d4+2` |
| Math | ` ` |
| Add | ` + ` | `2d6 + 2` | |
| Subtract | ` - ` | `2 - 1` | |
| Multiply | ` * ` | `1d4 * 2d6` | |
| Divide | ` / ` | `4 / 2` | |
| Negative | `-` | `-1d6` | multiplies the result of the dice expression with -1 |
| Oder | `[asc, desc]` | `10d10asc` | ordering the results of the dice ascending (`asc`) or descending (`desc`) |
| Min/Max | `[min, max]` | `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:
```xml
dev.diceroll
dice-parser
${version}
```
Gradle
```
implementation 'dev.diceroll:dice-parser:${version}'
```