DiceNotation Library

A .NET library for parsing, evaluating, and rolling dice using standard dice notation. Perfect for tabletop RPG applications, game development, or any project that needs flexible dice rolling mechanics.

What is Dice Notation?

Dice notation (also known as dice algebra or RPG dice notation) is a standardized system to represent dice combinations using simple algebra-like expressions. If you've ever played Dungeons & Dragons or other tabletop RPGs, you've used dice notation.

For example, 2d6+12 means "roll two six-sided dice and add 12 to the result."

d20Tek.DiceNotation brings this notation system to your .NET applications, handling all the parsing, evaluation, and random number generation for you.

Key Features

Standard Notation Parse expressions like 2d6, 4d6k3, d20+5

Fluent API Build dice expressions programmatically with method chaining

Multiple Rollers Random, Cryptographic, or custom dice rollers

Keep/Drop Keep highest/lowest N dice from a roll

Detailed Results See individual die values, not just totals

Testable ConstantDieRoller for predictable unit tests

Dice Notation Examples

Here are some common dice notation expressions and what they mean:

Expression	Description
`d20`	Roll a single 20-sided die
`2d6`	Roll two 6-sided dice and sum them
`d20+5`	Roll a d20 and add 5 to the result
`4d6k3`	Roll 4d6, keep the highest 3 dice (classic ability score roll)
`2d10+d6+4`	Roll 2d10 plus 1d6 plus 4
`8d6`	Roll eight 6-sided dice (fireball damage!)

Installation

Install the NuGet package using the Package Manager Console or .NET CLI:

dotnet add package d20Tek-DiceNotation

Quick Start

Using Dice Notation Strings

The simplest way to roll dice - just pass a notation string:

using d20Tek.DiceNotation;
using d20Tek.DiceNotation.DieRollers;

// Create a dice instance
IDice dice = new Dice();

// Roll using dice notation string
DiceResult result = dice.Roll("d20+4", new RandomDieRoller());

Console.WriteLine($"Roll result = {result.Value}");
// Output: Roll result = 17 (example)

Building Expressions Programmatically

Use the fluent API for more control over your dice expressions:

using d20Tek.DiceNotation;
using d20Tek.DiceNotation.DieRollers;

IDice dice = new Dice();

// Build expression: 4d6k3 + d8 + 5
// (Roll 4d6 keep highest 3, plus 1d8, plus 5)
var expression = DiceExpression.Create()
    .AddDice(6, 4, choose: 3)  // 4d6 keep 3
    .AddDice(8)                 // + 1d8
    .AddConstant(5);            // + 5

DiceResult result = dice.Roll(expression, new RandomDieRoller());

Console.WriteLine($"Roll result = {result.Value}");

Getting Detailed Results

Access individual die rolls, not just the total:

DiceResult result = dice.Roll("4d6k3", new RandomDieRoller());

Console.WriteLine($"Total: {result.Value}");
Console.WriteLine($"Dice rolled: {string.Join(", ", result.Results.Select(r => r.Value))}");

// Output example:
// Total: 14
// Dice rolled: 6, 5, 3 (the 2 was dropped)

Dice Rollers

Choose the random number generator that fits your needs:

Roller	Use Case
`RandomDieRoller`	Standard .NET Random - good for most applications
`CryptoDieRoller`	Cryptographically secure random numbers for high-stakes scenarios
`MathNetDieRoller`	Various RNG strategies via Math.NET library
`ConstantDieRoller`	Always returns the same value - perfect for unit testing

Custom Dice Rollers

Need something special? Implement the IDieRoller interface to create your own custom rolling logic.

public class MyCustomRoller : IDieRoller
{
    public int Roll(int sides)
    {
        // Your custom logic here
        return myRandomValue;
    }
}

Unit Testing with Dice

Use ConstantDieRoller to make your dice-dependent code fully testable:

[TestMethod]
public void Attack_WithHighRoll_ShouldHit()
{
    // Arrange - dice always roll max value
    var roller = new ConstantDieRoller(20);
    var dice = new Dice();
    
    // Act
    var result = dice.Roll("d20+5", roller);
    
    // Assert - predictable result: 20 + 5 = 25
    Assert.AreEqual(25, result.Value);
}

Sample Projects

Explore complete working examples in the GitHub repository:

DiceCli - Command-line dice roller application
DiceRoller Windows 10 - UWP application with visual dice rolling
DiceRoller ASP.NET MVC - Web-based dice roller

Perfect For

Tabletop RPG Apps - Character sheets, combat trackers, virtual tabletops
Game Development - Any game needing configurable random mechanics
Discord/Chat Bots - Dice rolling commands for gaming communities
Probability Analysis - Simulate thousands of rolls for statistical analysis

Ready to roll some dice?

View on GitHub View on NuGet