Struct DiceRoll

Represents an immutable dice roll configuration using standard RPG notation (e.g., "2d6+5"). Encapsulates the number of dice, face count, and flat modifier that define a roll expression, and provides methods to execute that roll against any IRandomSource.

Implements

IEquatable<DiceRoll>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Scylla.Core.Util.Random

Assembly: ScyllaCore.dll

Syntax

[Serializable]
public readonly struct DiceRoll : IEquatable<DiceRoll>

Remarks

Supported dice notation formats:

• d6 or 1d6 - Roll one 6-sided die.
• 2d6 - Roll two 6-sided dice and sum the results.
• 2d6+5 - Roll two 6-sided dice and add a flat modifier of 5.
• 3d8-2 - Roll three 8-sided dice and subtract 2.

Because DiceRoll is a readonly struct, it is stack-allocated, allocation-free, and safe for use as a field in other value types. The [Serializable] attribute makes it compatible with Unity's Inspector and serialization pipeline.

To create a DiceRoll from a notation string, use Parse(string) or TryParse(string, out DiceRoll). To roll, pass any IRandomSource to Roll(IRandomSource) or Roll(IRandomSource, out int[]).

Constructors

DiceRoll(int, int, int)

Initializes a new DiceRoll with the specified dice count, face count, and modifier.

Declaration

public DiceRoll(int diceCount = 1, int faceCount = 6, int modifier = 0)

Parameters

Type	Name	Description
int	diceCount	The number of dice to roll simultaneously. Must be at least 1. Defaults to 1.
int	faceCount	The number of faces on each die, which determines the per-die result range [1, faceCount]. Must be at least 2. Defaults to 6.
int	modifier	A flat integer value added to the sum of all dice after rolling. May be any integer value, including negative. Defaults to 0.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if diceCount is less than 1, or if faceCount is less than 2.

Fields

MAX_DICE

The maximum number of dice allowed in a single roll expression. Parsing or constructing a DiceRoll with a DiceCount exceeding this value will fail validation.

Declaration

public const int MAX_DICE = 100

Field Value

Type	Description
int

Properties

AverageResult

Gets the statistical expected (mean) result from this dice roll configuration. Computed as DiceCount * (FaceCount + 1) / 2 + Modifier, which is the arithmetic mean of a uniform distribution over [1, FaceCount] multiplied by the number of dice, plus the modifier.

Declaration

public float AverageResult { get; }

Property Value

Type	Description
float	The average total result as a floating-point value.

DiceCount

The number of dice included in this roll expression. Always at least 1.

Declaration

public int DiceCount { get; }

Property Value

Type	Description
int	The positive integer count of dice to roll simultaneously.

FaceCount

The number of faces on each individual die in this roll expression. Always at least 2.

Declaration

public int FaceCount { get; }

Property Value

Type	Description
int	The face count that defines the per-die result range of [1, FaceCount].

MaxResult

Gets the maximum possible total result from this dice roll configuration. This occurs when every die rolls its highest value (FaceCount), giving DiceCount * FaceCount + Modifier.

Declaration

public int MaxResult { get; }

Property Value

Type	Description
int	The largest integer value this roll expression can produce.

MinResult

Gets the minimum possible total result from this dice roll configuration. This occurs when every die rolls its lowest value (1), giving DiceCount + Modifier.

Declaration

public int MinResult { get; }

Property Value

Type	Description
int	The smallest integer value this roll expression can produce.

Modifier

The flat integer modifier added to the sum of all dice results after rolling. May be positive, negative, or zero.

Declaration

public int Modifier { get; }

Property Value

Type	Description
int	The modifier applied to the total after summing all die results.

Methods

Equals(DiceRoll)

Declaration

public bool Equals(DiceRoll other)

Parameters

Type	Name	Description
DiceRoll	other

Returns

Type	Description
bool

Equals(object)

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
object	obj

Returns

Type	Description
bool

Overrides

ValueType.Equals(object)

GetHashCode()

Declaration

public override int GetHashCode()

Returns

Type	Description
int

Overrides

ValueType.GetHashCode()

Parse(string)

Parses a dice notation string into a DiceRoll instance. Throws if the notation is null or does not conform to the expected format. Use TryParse(string, out DiceRoll) for non-throwing parsing.

Declaration

public static DiceRoll Parse(string notation)

Parameters

Type	Name	Description
string	notation	The dice notation string to parse (e.g., "2d6+5", "d20", "3d8-2"). Leading and trailing whitespace is trimmed automatically. The dice count prefix is optional and defaults to 1 when omitted (e.g., "d6" is equivalent to "1d6").

Returns

Type	Description
DiceRoll	A DiceRoll representing the parsed notation.

Exceptions

Type	Condition
ArgumentNullException	Thrown if notation is null.
FormatException	Thrown if notation is empty, whitespace-only, or does not match the expected dice notation pattern.

Roll(IRandomSource)

Executes the dice roll and returns the total result, discarding individual die values. Each die produces a uniformly random result in [1, FaceCount], and all die results are summed together with Modifier to form the total.

Declaration

public int Roll(IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source to use for rolling. Using a seeded IRandomSource (e.g., CreateXoshiro256(ulong)) makes rolls fully deterministic and reproducible for a given seed.

Returns

Type	Description
int	The integer sum of all individual die results plus Modifier. The result is always in the range [MinResult, MaxResult].

Exceptions

Type	Condition
ArgumentNullException	Thrown if rng is null.

See Also

Roll(IRandomSource, out int[])

Roll(IRandomSource, out int[])

Executes the dice roll and returns both the total result and the individual die values. Each die produces a uniformly random result in [1, FaceCount]. The individual results allow callers to inspect per-die outcomes (e.g., for critical-hit detection, exploding dice, or display purposes) without re-rolling.

Declaration

public int Roll(IRandomSource rng, out int[] results)

Parameters

Type	Name	Description
IRandomSource	rng	The random source to use for rolling. Using a seeded IRandomSource makes rolls fully deterministic and reproducible.
int[]	results	When this method returns, contains a newly allocated array of length DiceCount where each element is the raw result of one die in the range [1, FaceCount]. The Modifier is not included in these individual values - only in the returned total.

Returns

Type	Description
int	The integer sum of all individual die results plus Modifier. Equivalent to results.Sum() + Modifier.

Exceptions

Type	Condition
ArgumentNullException	Thrown if rng is null.

ToString()

Returns the standard dice notation string representation of this roll configuration. The format follows these rules:

• If DiceCount is 1, the count prefix is omitted (e.g., "d6" instead of "1d6").
• If Modifier is 0, no modifier suffix is appended (e.g., "2d6").
• A positive modifier is prefixed with + (e.g., "2d6+5").
• A negative modifier is written with its natural leading minus sign (e.g., "3d8-2").

The output of this method is valid input for Parse(string) and TryParse(string, out DiceRoll).

Declaration

public override string ToString()

Returns

Type	Description
string	A string representing this dice roll in standard dice notation (e.g., "2d6+5").

Overrides

ValueType.ToString()

TryParse(string, out DiceRoll)

Attempts to parse a dice notation string into a DiceRoll without throwing. Returns false and sets roll to default for any invalid input, including null, empty strings, whitespace, and malformed notation.

Declaration

public static bool TryParse(string notation, out DiceRoll roll)

Parameters

Type	Name	Description
string	notation	The dice notation string to parse (e.g., "2d6+5", "d20", "3d8-2"). Leading and trailing whitespace is tolerated.
DiceRoll	roll	When this method returns true, contains the parsed DiceRoll. When this method returns false, contains default(DiceRoll).

Returns

Type	Description
bool	true if the notation was successfully parsed; otherwise, false.

Operators

operator ==(DiceRoll, DiceRoll)

Returns true if left and right represent the same roll configuration (equal DiceCount, FaceCount, and Modifier).

Declaration

public static bool operator ==(DiceRoll left, DiceRoll right)

Parameters

Type	Name	Description
DiceRoll	left	The left operand.
DiceRoll	right	The right operand.

Returns

Type	Description
bool	true if both operands are equal; otherwise, false.

operator !=(DiceRoll, DiceRoll)

Returns true if left and right do not represent the same roll configuration.

Declaration

public static bool operator !=(DiceRoll left, DiceRoll right)

Parameters

Type	Name	Description
DiceRoll	left	The left operand.
DiceRoll	right	The right operand.

Returns

Type	Description
bool	true if the operands differ in any component; otherwise, false.

Implements

IEquatable<T>