API Reference: Visual Dice Roller (Blazor)

This reference documents the public types in the d20Tek.DiceNotation.Blazor package, which animates completed dice rolls in a two-dimensional tray drawn on an HTML canvas. For the core library types, see the main API Reference, and for dependency injection in the core library, see the Dependency Injection reference. The descriptions are derived from the package's XML documentation comments.

For a conceptual overview see the Blazor introduction, and for a step-by-step walkthrough see the Blazor getting started guide.

The package never rolls dice. The application rolls through IDice, then hands the finished DiceResult to the component, so the faces that come to rest always match the result the application already calculated.

Table of Contents

• Getting started
• Namespace: d20Tek.DiceNotation.Blazor.Components
  • VisualDiceRoller
• Namespace: d20Tek.DiceNotation.Blazor.Models
  • DiceRollerOptions
  • DiceTraySize
  • DiceTheme
  • DiceVisualSettings
  • DiceSimulationSettings
  • DiceRollSummary
  • VisualDie
• Namespace: Microsoft.Extensions.DependencyInjection
  • DiceRollerServiceCollectionExtensions
• Namespace: d20Tek.DiceNotation.Blazor.DependencyInjection
  • DiceRollerOptionsBuilder
• Die shapes
• Accessibility and reduced motion
• Supported targets
• Known limitations

Getting started

Register the services once during application startup. The call also registers the core dice notation services, so no separate AddDiceNotation call is required.

builder.Services.AddDiceNotationBlazor();

Add the component to a page and supply a result:

@inject IDice Dice

<VisualDiceRoller Result="_result" OnRollCompleted="OnCompleted" />

<button @onclick="Roll">Roll</button>

@code {
	private DiceResult? _result;
	private DiceRollSummary? _summary;

	private void Roll() => _result = Dice.Roll("4d6k3+2");

	private void OnCompleted(DiceRollSummary summary) => _summary = summary;
}

The component renders only the canvas. The application renders its own result text, which keeps the markup under the application's control and avoids fighting the component's styling.

Namespace: d20Tek.DiceNotation.Blazor.Components

VisualDiceRoller

Animates a completed dice roll in a two-dimensional tray drawn on an HTML canvas. Each instance owns its own simulation, renderer, and canvas, so several rollers can appear on one page. The component draws through the browser's own frame scheduler and does not re-render itself per frame.

Parameters

Properties

Methods

Animation triggers

The component animates declaratively whenever the Result parameter is set to a different instance. Because each roll produces a new result instance, this covers the normal case. Rolling the same values twice produces a different instance as well, so the animation still restarts. Use ReplayAsync when you want to replay the exact result you already have without rolling again.

Namespace: d20Tek.DiceNotation.Blazor.Models

DiceRollerOptions

Provides the configuration used by the VisualDiceRoller component. This groups the tray, theme, presentation, and physics settings into a single object so the component's parameter list stays small and can evolve without breaking consumers. Nothing in this type can influence a die result.

Properties

Methods

DiceTraySize

Represents the logical dimensions of the dice tray in simulation units. The canvas is sized by the browser, and the renderer scales these logical units to fit, so the tray keeps its proportions at any display size.

DiceTheme

Describes the colors and shapes used to draw the tray and dice.

DiceVisualSettings

Provides the presentation values used to turn physical state into drawing instructions. These values affect appearance only.

DiceSimulationSettings

Provides the physics values used by the dice simulation, including body properties, stepping, and settlement detection. These values affect motion and timing only.

DiceRollSummary

Represents a completed roll prepared for display alongside the animation. The Total is the value reported by the notation library and is never recomputed from Dice, because notation features such as dropped dice, scalars, and bounded results mean the visible faces do not always sum to the result.

VisualDie

Represents a single die that has been prepared for animation. The assigned Value is determined before the animation begins and is never changed by the simulation.

Namespace: Microsoft.Extensions.DependencyInjection

DiceRollerServiceCollectionExtensions

Provides extension methods for registering the visual dice roller services with an IServiceCollection.

Example with configuration:

builder.Services.AddDiceNotationBlazor(
	roller =>
	{
		roller.Theme = DiceTheme.Parchment;
		roller.TraySize = new DiceTraySize(10f, 7f);
	},
	dice => dice.UseCryptoDieRoller());

The configured options are validated during registration, so an invalid value is reported at startup rather than during a component's first render.

Namespace: d20Tek.DiceNotation.Blazor.DependencyInjection

DiceRollerOptionsBuilder

Builds the default DiceRollerOptions used by components that do not supply their own options. DiceRollerOptions is an immutable record, so this mutable builder gives registration code a simple assignment style without exposing settable state to the components that later read the options.

Die shapes

Each die is drawn with a silhouette matching its type rather than as a generic square, so a handful of mixed dice can be told apart at a glance:

A die type without a conventional shape falls back to a regular polygon, so an unusual die still renders and simulates sensibly.

A d2 is a coin rather than a many-sided die. It is built as an octagon with its corners rounded as far as each edge allows, which reads as a circle on screen while remaining a convex polygon that the physics engine can simulate.

Shapes are resolved in C# and sent to the renderer as plain vertex data, which keeps the shape rules in one testable place and leaves the JavaScript layer to trace what it is given. The physics bodies are built from the same outlines, so a die never collides as one shape while being drawn as another.

Outlines are normalized to approximately equal area rather than equal width. A hexagon inscribed in the same square as a triangle looks considerably larger, so without this correction a d20 would dwarf a d4 sitting beside it in the same tray.

Accessibility and reduced motion

The canvas is given a role of img and an accessible label. The label is generated from the settled result, so the outcome is available to assistive technology without reading the canvas.

Set ReducedMotion to disable face churn, implied height, and motion smear. This is an explicit option rather than an automatic media-query check, because an application usually already knows its own accessibility preferences and can apply them consistently across its UI.

A rendering or interop failure never changes a die value. Failures are surfaced through OnRollFailed, and the already-determined results remain valid, so an application should keep displaying them.

Supported targets

The component draws through the browser's own frame scheduler and batches each frame into a single interop call. On Blazor Server, frame data still travels over the circuit, so a high-latency connection produces a less smooth animation than WebAssembly does. Reducing the die count or enabling ReducedMotion helps in that case.

Known limitations

• The simulation is two-dimensional. Dice slide and spin in a flat tray rather than tumbling in three dimensions, and a die face shows its value as drawn text rather than as pips on a solid.
• Die values are fixed metadata rather than an outcome of the physics. A die comes to rest wherever the simulation puts it, and the assigned value is drawn on it throughout. This is deliberate, as it keeps a result auditable, but it means the settled orientation carries no meaning.
• Shapes are convex polygons of at most eight vertices, which is what the physics engine supports. A d2 is therefore an octagon with fully rounded corners rather than a true circle, and a die type without a conventional shape falls back to a regular polygon.
• A very large number of dice in one roll increases both simulation and drawing cost. Keep rolls to a reasonable die count for smooth animation on low-powered devices.
• The component renders only the canvas. An application supplies its own result text, totals, and roll history markup.
• A backgrounded browser tab pauses frame callbacks. Elapsed time is clamped and catch-up steps are capped, so returning to the tab resumes cleanly rather than fast-forwarding the whole animation.