Descent.RngKit 0.1.0

Descent.RngKit

A zero-allocation, never-throw dice expression engine for high-concurrency virtual tabletops.

This is the core engine — tokenizer, Superpower AST parser, CSPRNG, AST caching, and all generic primitives. It is deliberately free of game-specific rules; those live in Descent.RngKit.Mechanics.

dotnet add package Descent.RngKit --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.

Quick start

using Descent.RngKit;
using Descent.RngKit.Abstractions;

var engine = new RngEngine();

RngAuditPacket result = await engine.RollAsync("4d6kh3");

result.TotalValue;                     // 14
result.Details[^1].Rolls.ToArray();    // [6, 2, 5, 3]  every physical die
result.Details[^1].Labels.ToArray();   // ["6", "~~2~~", "5", "3"]  dropped die struck through

Variables carry an @ sigil, and the engine can tell you which ones a formula needs before you roll — so the host can load them in one batch and keep the roll itself fully synchronous:

using Descent.RngKit.Ast;   // GetVariableRequirements

var ast = engine.ParseString("1d100 <= @cthulhu_mythos + @target.armor");
var required = ast.GetVariableRequirements();

required.Names;        // { "cthulhu_mythos", "target.armor" }
required.IsComplete;   // false only when the formula contains meta_eval("...")

// Hydrate a snapshot that answers synchronously, then roll — the await chain never suspends.
var options = new RngRollOptions { VariableStore = new SnapshotProvider(await LoadAsync(required.Names)) };
var packet = await engine.RollAsync("1d100 <= @cthulhu_mythos + @target.armor", options);

A provider that actually awaits I/O costs roughly 849 bytes per variable instead of 81, because every frame of the evaluator's async chain boxes its state machine. Resolving up front avoids that entirely. Traversal covers nodes from Descent.RngKit.Mechanics and third-party rulesets too, since each AST node declares its children via Expression.ForEachChild.

In ASP.NET Core, register it as a singleton so the parser and AST caches are shared:

builder.Services.AddRngKit(options =>
{
    options.HotPaths = ["1d20", "3d6+5", "4d6kh3"];   // precompiled zero-allocation L1 cache
});

What this package understands

Arithmetic with overflow and divide-by-zero guards · @-prefixed variables, blocks, let, statement sequences · lazily-evaluated if · meta_eval for macros held in strings · dice (NdS, Fudge, coins) · keep/drop · exploding (normal, compounding, cascading, penetrating) · rerolls · criticals and fumbles · sorting · count, opposed, sets, mos, step, distinct, buckets, repeat · chance, range, gauss, spin, pick, shuffle · table lookups · deck operations (draw, tutor, extract, mulligan).

Game-system mechanics — Hope/Fear, glitch, stunt, stress pools, usage dice, tension pools, scatter, hit location, Markov chains, procedural noise, Monte-Carlo simulate — are not here. An expression using one returns a SyntaxError packet unless you register it. See the syntax reference.

Design guarantees

Never-throw. RollAsync does not throw for a bad expression. Syntax errors, integer overflow, division by zero, recursion bombs, and dice-count abuse return an RngErrorCode on the packet, with a source position. Only OperationCanceledException propagates, so a host can distinguish a timeout from a rejected expression.

Fair by default. CsprngProvider (the default) wraps System.Security.Cryptography.RandomNumberGenerator with rejection sampling to remove modulo bias. FastPrngProvider is available when throughput matters more than tamper resistance, and IRandomProvider lets you supply deterministic seeds for tests or a hardware source.

Zero allocation on the hot path. Evaluating an AST node allocates 0 bytes in Release. Dice pools come from ArrayPool<int> and are released per iteration inside repeat, so per-run cost does not grow with formula complexity. SIMD (Vector256) is used for pool summation and threshold counting, guarded by IsHardwareAccelerated with scalar fallbacks.

Sandboxed. Formula length, AST depth, nodes evaluated, dice count, dice sides, explosions, and rerolls are all capped. Cancellation is checked on entry to every node.

Thread-safe. One RngEngine instance serves unlimited concurrent RollAsync calls; all per-roll state lives in an EvaluationContext created per call.

Native AOT compatible. No reflection, no runtime codegen; verified at zero trim/AOT warnings.

Extending

Register your own AST nodes and evaluators through RngParserBuilder — the same public seam Descent.RngKit.Mechanics uses:

var builder = new RngParserBuilder()
    .RegisterModifier(unit => myCustomSyntax(unit))   // add grammar
    .RegisterEvaluator(new MyEvaluator())             // add behaviour
    .RegisterEvaluator<MyDiEvaluator>();              // ... or resolve from the DI container

var engine = new RngEngine(builder);

The engine is a singleton, so an evaluator must only depend on singletons. Pass request-scoped state per roll via RngRollOptions.Items and read it with context.GetItem<T>(...).

Full walkthrough: Extending.

Links

• 📘 Syntax reference
• ⚡ Performance
• 🏛 Architecture
• 📦 Descent.RngKit.Abstractions — contracts only
• 📦 Descent.RngKit.Serialization — opt-in System.Text.Json support
• 📦 Descent.RngKit.Mechanics — the standard ruleset library

MIT © DescentVTT Team