Getting Started

This guide will help you quickly get up and running with Wolfgang.D20.Dice.

Prerequisites

  • The .NET 10.0 SDK is required to build the highest TFM.
  • Building the net462 target additionally requires the .NET Framework 4.6.2 reference assemblies / targeting pack (typically installed via Visual Studio's ".NET desktop development" workload on Windows; the SDK alone does not include them, and net462 builds are Windows-only).
  • The netstandard2.0 and net8.0 targets build with the .NET 10 SDK alone on any OS.

The library ships against net462, netstandard2.0, net8.0, and net10.0.

Installation

Via NuGet Package Manager

dotnet add package Wolfgang.D20.Dice

Via Package Manager Console

Install-Package Wolfgang.D20.Dice

Quick Start

using Wolfgang.D20;

// Roll a single d20
var d20 = new Dice(dieCount: 1, sideCount: 20);
int result = d20.Roll();
Console.WriteLine($"Rolled {d20}: {result}");  // e.g. "Rolled 1d20: 14"

// Roll 2d6 with a +3 modifier
var attackRoll = new Dice(dieCount: 2, sideCount: 6, modifier: 3);
Console.WriteLine($"Attack ({attackRoll}): {attackRoll.Roll()}");
Console.WriteLine($"Range: {attackRoll.MinValue}–{attackRoll.MaxValue}");

// Parse dice notation from a string
var parseResult = Dice.TryParse("1d20+5");
if (parseResult.Succeeded)
{
    Console.WriteLine($"Parsed: {parseResult.Value} → {parseResult.Value.Roll()}");
}

Next Steps

Common Issues

Parsing fails for valid-looking notation

Dice.TryParse expects the format XdY, XdY+Z, or XdY-Z where X is optional (defaults to 1). The die count must be at least 1 and the side count at least 2. Check result.ErrorMessage for details on why parsing failed.

Modifier can be negative

A negative modifier is valid — new Dice(1, 20, -2) creates 1d20-2. The MinValue property accounts for the modifier, so it may be less than 1.

Additional Resources

Edit this page