Bonar.DiceParser 1.0.0

.NET 10.0

dotnet add package Bonar.DiceParser --version 1.0.0

NuGet\Install-Package Bonar.DiceParser -Version 1.0.0

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="Bonar.DiceParser" Version="1.0.0" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="Bonar.DiceParser" Version="1.0.0" />
                    

                            Directory.Packages.props

<PackageReference Include="Bonar.DiceParser" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add Bonar.DiceParser --version 1.0.0

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: Bonar.DiceParser, 1.0.0"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package Bonar.DiceParser@1.0.0

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=Bonar.DiceParser&version=1.0.0
                    

                            Install as a Cake Addin

#tool nuget:?package=Bonar.DiceParser&version=1.0.0
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

DiceParser

A .NET library that interprets and rolls tabletop RPG dice expressions.

Parse strings like 4d6kh3 or 2d20dl1, roll them, and get a numeric total. Swap in different randomizers when you want fair dice, guaranteed crits, or stranger distributions.

Requirements

.NET 10 SDK

Quick start

using DiceParser;
using DiceParser.Randomizers;

var parser = new DiceParser();

if (parser.IsValidRoll("4d6kh3"))
{
    int total = parser.Roll("4d6kh3");
}

// Inject a randomizer (default is a fair die)
var alwaysCrit = new DiceParser(Randomizer.CriticalDie());
int maxed = alwaysCrit.Roll("d20"); // 20

Roll throws ArgumentException when the expression is empty or cannot be evaluated.

Dice syntax

Expressions are case-insensitive. Whitespace is ignored.

Expression	Meaning
`d20`	One twenty-sided die (`d` with no count is one die)
`4d6`	Four six-sided dice, summed
`4d6dl1`	Roll 4d6, drop the lowest 1, sum the rest
`4d6dh2`	Roll 4d6, drop the highest 2, sum the rest
`4d6kh3`	Roll 4d6, keep the highest 3
`4d6kl1`	Roll 4d6, keep the lowest 1
`2d20kh`	Keep/drop count defaults to 1 when omitted
`12`	A constant value

Standard polyhedral sizes work (d2, d4, d6, d8, d10, d12, d20, d100) as well as any other positive face count.

Keep and drop are complements: 4d6kh3 is the same as 4d6dl1.

Randomizers

DiceParser rolls through an IRandomizer. The default constructor uses a fair die. Pass another implementation to change how each face is chosen:

public interface IRandomizer
{
    int Roll(int max); // returns a value from 1 to max, inclusive
}

Factory methods live on DiceParser.Randomizers.Randomizer:

Randomizer	Behavior
`FairDie()`	Uniform `1..N` (default)
`FailDie()`	Always `1`
`CriticalDie()`	Always `N`
`DeckDie()`	Shuffles a deck of faces `1..N` and deals without replacement until a cut card (15–50% of the deck remaining), then reshuffles. Separate decks are tracked per die size.
`GamblersAxionDie()`	Drawing a face removes every copy of it from the pool, then one of each face is added back. Recently drawn faces go “cold”; others get hotter. Separate pools are tracked per die size.

Use FailDie and CriticalDie in tests when you need a known minimum or maximum total.

You can also implement IRandomizer yourself (for example, to replay a fixed sequence of rolls).

Building and testing

dotnet test DiceParser.slnx

The test project (DiceParser.Test) covers syntax validation, keep/drop results, and the deck and gambler’s-axiom randomizers.

Project layout

DiceParser/                 Library
  DiceParser.cs             Parse and evaluate expressions
  Randomizers/              Die implementations
  Tools/                    Tokenizer and roll evaluation
DiceParser.Test/            NUnit tests
DiceParser.slnx             Solution

License

MIT

Product	Compatible and additional computed target framework versions.
.NET	net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net10.0
- No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
1.0.0	95	9/8/2026