Descent.RngKit.Mechanics 0.1.0

Descent.RngKit.Mechanics

The standard ruleset library for Descent.RngKit, plus a batteries-included engine factory.

The engine core stays free of game-specific rules. This package adds them as pluggable evaluators, registered through the core's public RngParserBuilder seams. Reference it when you want the full TRPG feature set immediately.

dotnet add package Descent.RngKit.Mechanics --version 0.1.0

Pre-1.0. Below 1.0.0 the public API is unstable by declaration — SemVer permits breaking changes in any 0.x minor release — so pin an exact version rather than a floating range.

This transitively brings in Descent.RngKit and Descent.RngKit.Abstractions.

Quick start

using Descent.RngKit.Mechanics;

var engine = RngEngineFactory.CreateStandard();   // every mechanic below is registered

var packet = await engine.RollAsync("hope_fear(1d12, 1d12)");
Console.WriteLine(string.Join(", ", packet.Details[^1].Flags ?? []));   // e.g. "WITH_HOPE"

Prefer to opt in only to what you use:

using Descent.RngKit;
using Descent.RngKit.Mechanics;

var builder = new RngParserBuilder()
    .AddHopeFear()
    .AddScatter();          // or .AddStandardMechanics() for everything

var engine = new RngEngine(builder);

In ASP.NET Core:

builder.Services.AddRngKit(o => o.Builder.AddStandardMechanics());

Included mechanics

Names are case-insensitive and most have aliases.

Exact argument shapes and every alias are in the syntax reference.

Some mechanics need a host provider via RngRollOptions: hit_loc uses IHitLocationProvider, markov and matrix use ITableProvider, and tension_pool persists its counter through IVariableProvider. Without one, they return a specific error code rather than throwing.

simulate is cheap

simulate suppresses per-run telemetry and releases pooled buffers on every iteration, so allocation does not scale with the run count or the formula's complexity. A 10,000-run simulation of 3d6+4 costs roughly 40 KB — essentially just the int[] holding the results. It returns the rounded mean and attaches median, standard deviation, min, max, and the 25th/75th/95th percentiles as SimulateMetadata.

Writing your own ruleset

This package is not privileged. It uses exactly the public seams available to you: an AST record, an IRngCustomEvaluator, a parser modifier, and a builder.AddYourMechanic() extension method. If your table has a house rule, ship it as your own package — no fork required.

MechanicsParsing offers reusable grammar helpers: Function(names, build) for plain comma-separated arguments, PoolOpTarget(names, build) for name(pool, OP target), and Named(names, body) for bespoke grammars.

Walkthrough: Extending.

Links

• 📘 Syntax reference
• 🧩 Extending
• 📦 Descent.RngKit — the engine
• 📦 Descent.RngKit.Abstractions — contracts only
• 📦 Descent.RngKit.Serialization — opt-in System.Text.Json support

MIT © DescentVTT Team