dart_dice_parser
A dart library for parsing dice notation (e.g. "2d6+4"). Supports advantage/disadvantage, exploding die, and other variations.
Example
import 'package:dart_dice_parser/dart_dice_parser.dart';
void main() {
// Create a roller for D20 advantage (roll 2d20, keep highest).
final d20adv = DiceExpression.create('2d20 kh');
stdout.writeln(d20adv.roll());
// outputs:
// ((2d20)kh) => RollResult(total: 15, results: [15] , metadata: {dropped: [8], rolled: [8, 15]})
stdout.writeln(d20adv.roll());
// outputs:
// ((2d20)kh) => RollResult(total: 20, results: [20] , metadata: {dropped: [5], rolled: [5, 20]})
}
Random Number Generator
By default, Random.secure() is used. You can select other RNGs at when creating the dice expression. Random.secure() is slower, so if you're doing lots of rolls for use cases where security doesn't matter, you may want to use Random() instead.
// uses Random.secure()
final diceExpr1 = DiceExpression.create('2d20 kh');
// uses supplied RNG.
final diceExpr2 = DiceExpression.create('2d20 kh', Random());
Dice Notation
Examples:

1d20 #cf #cs
 roll 1d20, result will include counts of successes, failures (1)

advantage/disadvantage in 5E
 There's a couple ways to roll advantage
2d20L
 roll 2d20, drop lowest (advantage)2d20k
,2d20kh
 roll 2d20 keep highest
 Similarly for disadvantage:
2d20H
 drop highest2d20kl
 keep lowest
 There's a couple ways to roll advantage

(2d10+3d20)L3
 roll 2d10 and 3d20, combine the two results lists, and drop lowest 3 results 
20d10<3>8#
 roll 20 d10, drop any less than 3 or greater than 8 and count the number of remaining dice
Supported notation

2d6
 roll2
dice of6
sides 
special dice variations:
4dF
 roll4
fudge dice (sides:[1, 1, 0, 0, 1, 1]
)1d%
 roll1
percentile dice (equivalent to1d100
)1D66
 roll1
D66, aka1d6*10 + 1d6
 NOTE: you must use uppercase
D66
, lowercased66
will be interpreted as 66sided die
 NOTE: you must use uppercase

exploding dice
4d6!
 roll4
6
sided dice, explode if max (6
) is rolled (reroll and include in results)4d6!=5
or4d6!5
 explode a roll if equal to 54d6!>=4
 explode if >= 44d6!<=2
 explode if <=24d6!>5
 explode if > 54d6!<2
 explode if <2 To limit to a single explosion, use syntax
!o
(otherwise, dice rolls will explode at most 1000 times)4d6!o<5

compounding dice (Shadowrun, L5R, etc). Similar to exploding, but the additional rolls for each dice are added together as a single "roll"
5d6!!
 roll5
6
sided dice, compound5d6!!=5
or5d6!5
 compound a roll if equal to 55d6!!>=4
 compound if >= 45d6!!<=4
 compound if <= 45d6!!>5
 compound if > 55d6!!<3
 compound if < 3 To limit to a single compound, use syntax
!!o
(otherwise, dice rolls compound at most 1000 times)5d6!!o<2

rerolling dice:
4d4 r2
 roll 4d4, reroll any result = 24d4 r=2
 roll 4d4, reroll any result = 24d4 r<=2
 roll 4d4, reroll any <= 24d4 r>=3
 roll 4d4, reroll any >= 34d4 r<2
 roll 4d4, reroll any < 24d4 r>3
 roll 4d4, reroll any > 3 To limit to a single reroll, use syntax
!!o
(otherwise, dice rolls reroll at most 1000 times)4d4!!o<2

keeping dice:
3d20 k 2
 roll 3d20, keep 2 highest3d20 kh 2
 roll 3d20, keep 2 highest3d20 kl 2
 roll 3d20, keep 2 lowest

dropping dice:
4d6 H
 roll 4d6, drop 1 highest4d6 L
 roll 4d6, drop 1 lowest4d6 H2
 roll 4d6, drop 2 highest4d6 L2
 roll 4d6, drop 2 lowest4d6 >5
 roll 4d6, drop any results > 54d6 <2
 roll 4d6, drop any results < 24d6 >=5
 roll 4d6, drop any results >= 54d6 <=2
 roll 4d6, drop any results <= 24d6 =1
 roll 4d6, drop any results equal to 1 NOTE: the drop operators have higher precedence than
the arithmetic operators;
4d10L2+2
is equivalent to(4d10L2)+2
 cap/clamp:
4d20 C<5
 roll 4d20, change any value < 5 to 54d20 C>15
 roll 4d20, change any value > 15 to 15

operations on dice rolls:
 counting:
4d6 #
 how many results? For example, you might use this to count # of dice above a target.
(5d10<6)#
 roll 5 d10, drop any 5 or under, count results
 For example, you might use this to count # of dice above a target.
4d6 #>3
 roll 4d6, count any > 34d6 #<3
 roll 4d6, count any < 34d6 #>=5
 roll 4d6, count any >= 54d6 #<=2
 roll 4d6, count any <= 24d6 #=5
 roll 4d6, count any equal to 5
 counting (critical) success/failures
 A normal count operation
#
discards the rolled dice and changes the result to be the count For example,
2d6#<=3
rolls[3,4]
then counts which results are<=3
, returning[1]
 For example,
 But, sometimes you want to be able to count successes/failures without discarding the rolls.
In this case, use modifiers
#s
,#f
,#cs
,#cf
to add metadata to the results.6d6 #f<=2#s>=5#cs6
 roll 6d6, count results <= 2 as failures, >= 5 as successes, and =6 as critical successes. returns a result like:
RollResult(total: 22, results: [6, 2, 1, 5, 3, 5] {failures: {count: 2, target: #f<=2}, successes: {count: 3, target: #s>=5}, critSuccesses: {count: 1, target: #cs6}})
 returns a result like:
 A normal count operation
 counting:

arithmetic operations
 parenthesis for order of operations
 addition is a little special  could be a sum of ints, or it can be used to aggregate results of multiple dice rolls
 Addition of integers is the usual sum
4+5
2d6 + 1
 Addition of roll results combines the results (use parens to ensure the order of operations is as you expect)
(5d6+5d10)L2
 roll 5d6 and 5d10, and from aggregate results drop the lowest 2.5d6+5d10L2
 roll 5d6 and 5d10, and from only the 5d10 results drop the lowest 2. equivalent to5d6+(5d10L2)
 Addition of integers is the usual sum
*
for multiplication
for subtraction numbers must be integers
 division is not supported.
CLI Usage
There's no executable in bin, but there's an example CLI at example/main.dart
.
❯ dart example/main.dart '3d6'
(3d6) => RollResult(total: 9, results: [4, 3, 2])
# run N number of rolls
❯ dart example/main.dart n6 '3d6'
(3d6) => RollResult(total: 14, results: [6, 6, 2])
(3d6) => RollResult(total: 8, results: [2, 5, 1])
(3d6) => RollResult(total: 12, results: [3, 5, 4])
(3d6) => RollResult(total: 16, results: [5, 5, 6])
(3d6) => RollResult(total: 15, results: [3, 6, 6])
(3d6) => RollResult(total: 6, results: [1, 1, 4])
# show statistics for a dice expression
❯ dart example/main.dart s '3d6'
{mean: 10.5, stddev: 2.97, min: 3, max: 18, count: 10000, histogram: {3: 49, 4: 121, 5: 273, 6: 461, 7: 727, 8: 961, 9: 1153, 10: 1182, 11: 1272, 12: 1151, 13: 952, 14: 733, 15: 486, 16: 289, 17: 154, 18: 36}}
Features and bugs
Please file feature requests and bugs at the issue tracker.
Libraries
 dart_dice_parser
 A Parser for dice notation