feat(game): add SquidStd.Game library with dice-notation parser

Introduce a new SquidStd.Game NuGet library that hosts game mechanics on top
of SquidStd.Core, keeping Core focused on infrastructure.

- feat(game): add DiceExpression (readonly record struct) parsing [N]dS[±M]
  notation, pure constants, and the wrapped dice(...) form; whitespace-tolerant
  and case-insensitive on the d separator
- feat(game): expose Min/Max/Average bounds and Roll() reusing the existing
  RandomUtils.Dice engine and BuiltInRng, so a fixed seed is reproducible
- feat(game): scaffold SquidStd.Game.csproj (PublishNuget, references Core),
  register it in SquidStd.slnx, and reference it from SquidStd.Tests
- test(game): cover parsing of all notation forms, invalid inputs (TryParse
  false / Parse throws), Min/Max/Average bounds, and Roll range + reproducibility

Author: tgiachi

SquidStd.slnx

@@ -1,6 +1,7 @@
 <Solution>
     <Folder Name="/src/">
         <Project Path="src/SquidStd.Abstractions/SquidStd.Abstractions.csproj"/>
+        <Project Path="src/SquidStd.Game/SquidStd.Game.csproj"/>
         <Project Path="src/SquidStd.Generators/SquidStd.Generators.csproj"/>
         <Project Path="src/SquidStd.Telemetry.Abstractions/SquidStd.Telemetry.Abstractions.csproj"/>
         <Project Path="src/SquidStd.Telemetry.OpenTelemetry/SquidStd.Telemetry.OpenTelemetry.csproj"/>

src/SquidStd.Game/Dice/DiceExpression.cs

@@ -0,0 +1,129 @@
+using System.Globalization;
+using SquidStd.Core.Utils;
+
+namespace SquidStd.Game.Dice;
+
+/// <summary>
+/// A parsed dice-notation expression of the form <c>[N]dS[±M]</c> (for example <c>2d4+1</c>,
+/// <c>d6</c>) or a pure constant <c>N</c>. Rolling reuses the ambient
+/// <see cref="RandomUtils.Dice(int, int, int)" /> engine, so a fixed <see cref="BuiltInRng" />
+/// seed yields reproducible sequences.
+/// </summary>
+/// <param name="Count">Number of dice; <c>0</c> for a pure constant.</param>
+/// <param name="Sides">Sides per die; <c>0</c> for a pure constant.</param>
+/// <param name="Modifier">Flat bonus added to (or, for a constant, equal to) the total.</param>
+public readonly record struct DiceExpression(int Count, int Sides, int Modifier)
+{
+    private bool IsConstant => Count <= 0 || Sides <= 0;
+
+    /// <summary>The lowest total this expression can produce (every die shows 1).</summary>
+    public int Min => IsConstant ? Modifier : Count + Modifier;
+
+    /// <summary>The highest total this expression can produce (every die shows its max face).</summary>
+    public int Max => IsConstant ? Modifier : (Count * Sides) + Modifier;
+
+    /// <summary>The expected (mean) total of this expression.</summary>
+    public double Average => IsConstant ? Modifier : (Count * (Sides + 1) / 2.0) + Modifier;
+
+    /// <summary>Rolls the expression, returning a random total in <c>[Min, Max]</c>.</summary>
+    /// <returns>The rolled total, or <see cref="Modifier" /> for a pure constant.</returns>
+    public int Roll()
+        => IsConstant ? Modifier : RandomUtils.Dice(Count, Sides, Modifier);
+
+    /// <summary>
+    /// Parses dice notation such as <c>2d4+1</c>, <c>d6</c>, <c>5</c>, or the wrapped form
+    /// <c>dice(2d4+1)</c>. Whitespace is ignored and the <c>d</c> separator is case-insensitive.
+    /// </summary>
+    /// <param name="input">The notation to parse.</param>
+    /// <returns>The parsed <see cref="DiceExpression" />.</returns>
+    /// <exception cref="FormatException">The input is not valid dice notation.</exception>
+    public static DiceExpression Parse(string input)
+    {
+        if (TryParse(input, out var result))
+        {
+            return result;
+        }
+
+        throw new FormatException($"Invalid dice notation: '{input}'.");
+    }
+
+    /// <summary>Attempts to parse dice notation without throwing.</summary>
+    /// <param name="input">The notation to parse; may be wrapped in <c>dice( ... )</c>.</param>
+    /// <param name="result">The parsed expression on success; otherwise <c>default</c>.</param>
+    /// <returns><c>true</c> if <paramref name="input" /> was valid dice notation.</returns>
+    public static bool TryParse(string? input, out DiceExpression result)
+    {
+        result = default;
+
+        if (string.IsNullOrWhiteSpace(input))
+        {
+            return false;
+        }
+
+        var text = input.Trim();
+
+        if (text.StartsWith("dice(", StringComparison.OrdinalIgnoreCase) && text.EndsWith(')'))
+        {
+            text = text[5..^1];
+        }
+
+        text = text.Replace(" ", string.Empty, StringComparison.Ordinal);
+
+        if (text.Length == 0)
+        {
+            return false;
+        }
+
+        var dIndex = text.IndexOf('d', StringComparison.OrdinalIgnoreCase);
+
+        if (dIndex < 0)
+        {
+            if (int.TryParse(text, NumberStyles.AllowLeadingSign, CultureInfo.InvariantCulture, out var constant))
+            {
+                result = new DiceExpression(0, 0, constant);
+                return true;
+            }
+
+            return false;
+        }
+
+        var countPart = text[..dIndex];
+        var count = 1;
+
+        if (countPart.Length > 0 &&
+            !int.TryParse(countPart, NumberStyles.None, CultureInfo.InvariantCulture, out count))
+        {
+            return false;
+        }
+
+        if (count <= 0)
+        {
+            return false;
+        }
+
+        var rest = text[(dIndex + 1)..];
+
+        if (rest.Length == 0)
+        {
+            return false;
+        }
+
+        var signIndex = rest.IndexOfAny(['+', '-']);
+        var sidesPart = signIndex >= 0 ? rest[..signIndex] : rest;
+        var modifier = 0;
+
+        if (signIndex >= 0 &&
+            !int.TryParse(rest[signIndex..], NumberStyles.AllowLeadingSign, CultureInfo.InvariantCulture, out modifier))
+        {
+            return false;
+        }
+
+        if (!int.TryParse(sidesPart, NumberStyles.None, CultureInfo.InvariantCulture, out var sides) || sides <= 0)
+        {
+            return false;
+        }
+
+        result = new DiceExpression(count, sides, modifier);
+        return true;
+    }
+}

src/SquidStd.Game/SquidStd.Game.csproj

@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <TargetFramework>net10.0</TargetFramework>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <Nullable>enable</Nullable>
+        <PublishNuget>true</PublishNuget>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <InternalsVisibleTo Include="SquidStd.Tests"/>
+    </ItemGroup>
+
+    <ItemGroup>
+        <ProjectReference Include="..\SquidStd.Core\SquidStd.Core.csproj"/>
+    </ItemGroup>
+
+</Project>

tests/SquidStd.Tests/Game/Dice/DiceExpressionTests.cs

@@ -0,0 +1,115 @@
+using SquidStd.Core.Utils;
+using SquidStd.Game.Dice;
+
+namespace SquidStd.Tests.Game.Dice;
+
+public class DiceExpressionTests
+{
+    [Theory]
+    [InlineData("2d4", 2, 4, 0)]
+    [InlineData("2d4+1", 2, 4, 1)]
+    [InlineData("2d4-1", 2, 4, -1)]
+    [InlineData("d6", 1, 6, 0)]
+    [InlineData("D6", 1, 6, 0)]
+    [InlineData(" 2 d 4 + 1 ", 2, 4, 1)]
+    [InlineData("dice(2d4+1)", 2, 4, 1)]
+    [InlineData("DICE(3d6-2)", 3, 6, -2)]
+    public void Parse_ValidDiceNotation_ReturnsComponents(string input, int count, int sides, int modifier)
+    {
+        var expression = DiceExpression.Parse(input);
+
+        Assert.Equal(count, expression.Count);
+        Assert.Equal(sides, expression.Sides);
+        Assert.Equal(modifier, expression.Modifier);
+    }
+
+    [Fact]
+    public void Parse_PureConstant_HasZeroDice()
+    {
+        var expression = DiceExpression.Parse("5");
+
+        Assert.Equal(0, expression.Count);
+        Assert.Equal(0, expression.Sides);
+        Assert.Equal(5, expression.Modifier);
+    }
+
+    [Theory]
+    [InlineData("2d4", 2, 8, 5.0)]
+    [InlineData("2d4+1", 3, 9, 6.0)]
+    [InlineData("2d4-1", 1, 7, 4.0)]
+    [InlineData("d6", 1, 6, 3.5)]
+    public void MinMaxAverage_MatchExpectedBounds(string input, int min, int max, double average)
+    {
+        var expression = DiceExpression.Parse(input);
+
+        Assert.Equal(min, expression.Min);
+        Assert.Equal(max, expression.Max);
+        Assert.Equal(average, expression.Average, 3);
+    }
+
+    [Fact]
+    public void MinMaxAverage_Constant_AllEqualModifier()
+    {
+        var expression = DiceExpression.Parse("7");
+
+        Assert.Equal(7, expression.Min);
+        Assert.Equal(7, expression.Max);
+        Assert.Equal(7.0, expression.Average, 3);
+    }
+
+    [Fact]
+    public void Roll_StaysWithinMinMax()
+    {
+        var expression = DiceExpression.Parse("3d6+2");
+        BuiltInRng.Reset(1234);
+
+        for (var i = 0; i < 1000; i++)
+        {
+            var roll = expression.Roll();
+            Assert.InRange(roll, expression.Min, expression.Max);
+        }
+    }
+
+    [Fact]
+    public void Roll_IsReproducibleWithSameSeed()
+    {
+        var expression = DiceExpression.Parse("2d20+3");
+
+        BuiltInRng.Reset(42);
+        var first = expression.Roll();
+        BuiltInRng.Reset(42);
+        var second = expression.Roll();
+
+        Assert.Equal(first, second);
+    }
+
+    [Fact]
+    public void Roll_Constant_ReturnsModifier()
+    {
+        var expression = DiceExpression.Parse("9");
+
+        Assert.Equal(9, expression.Roll());
+    }
+
+    [Theory]
+    [InlineData("")]
+    [InlineData("   ")]
+    [InlineData(null)]
+    [InlineData("abc")]
+    [InlineData("2d")]
+    [InlineData("d")]
+    [InlineData("0d6")]
+    [InlineData("2d0")]
+    [InlineData("-1d6")]
+    [InlineData("2d4+x")]
+    public void TryParse_InvalidInput_ReturnsFalse(string? input)
+    {
+        Assert.False(DiceExpression.TryParse(input, out _));
+    }
+
+    [Fact]
+    public void Parse_InvalidInput_Throws()
+    {
+        Assert.Throws<FormatException>(() => DiceExpression.Parse("not-a-dice"));
+    }
+}

tests/SquidStd.Tests/SquidStd.Tests.csproj

@@ -36,6 +36,7 @@
 
     <ItemGroup>
         <ProjectReference Include="..\..\src\SquidStd.Core\SquidStd.Core.csproj"/>
+        <ProjectReference Include="..\..\src\SquidStd.Game\SquidStd.Game.csproj"/>
         <ProjectReference Include="..\..\src\SquidStd.Abstractions\SquidStd.Abstractions.csproj"/>
         <ProjectReference Include="..\..\src\SquidStd.Generators\SquidStd.Generators.csproj"/>
         <ProjectReference Include="..\..\src\SquidStd.Telemetry.Abstractions\SquidStd.Telemetry.Abstractions.csproj"/>