Class RandomExtensions

Extension methods for IRandomSource implementations that provide convenient instance-style access to all major random operations without needing to call RandomUtil statically.

Inheritance

object

RandomExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Scylla.Core.Util.Random

Assembly: ScyllaCore.dll

Syntax

public static class RandomExtensions

Remarks

Every method in this class is a thin wrapper that delegates to a corresponding static method in RandomUtil or a feature class such as DiceRoll, RandomText, RandomID, or PoissonDiskSampler. No additional logic is performed.

Usage example:

<pre><code class="lang-csharp">var rng = RandomUtil.CreateXoshiro256(12345UL);

int damage = rng.NextInt(10, 20); bool isCrit = rng.NextBool(0.2f); string token = rng.GenerateHex(32); rng.Shuffle(itemList);

Methods

GenerateAlphanumericID(IRandomSource, int)

Generates a random alphanumeric string of exactly length characters, drawn uniformly from the set {a-z, A-Z, 0-9}. Delegates to GenerateAlphanumeric(IRandomSource, int).

Declaration

public static string GenerateAlphanumericID(this IRandomSource rng, int length = 16)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
int	length	The number of alphanumeric characters to generate. Must be at least 1. Defaults to 16.

Returns

Type	Description
string	A random alphanumeric string of exactly length characters.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if length is less than 1.

GenerateBase64(IRandomSource, int)

Generates a random URL-safe Base64 string derived from byteLength random bytes. The output uses - instead of + and _ instead of /, with padding stripped. The resulting string will be longer than byteLength characters due to Base64 encoding overhead (approximately 4/3 × byte length). Delegates to GenerateBase64(IRandomSource, int).

Declaration

public static string GenerateBase64(this IRandomSource rng, int byteLength = 12)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
int	byteLength	The number of raw random bytes to encode. Must be at least 1. Defaults to 12 (produces a 16-character output).

Returns

Type	Description
string	A random URL-safe Base64 string without padding.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if byteLength is less than 1.

GenerateGUID(IRandomSource)

Generates a random GUID (version 4, RFC 4122) using the underlying random source. The GUID is not cryptographically secure - if security is required use NewGuid() or a CryptoRandomSource instead. Delegates to GenerateGUID(IRandomSource).

Declaration

public static Guid GenerateGUID(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
Guid	A Guid with variant bits set to RFC 4122 and version bits set to 4. The remaining 122 bits are random, drawn from rng.

GenerateHex(IRandomSource, int)

Generates a random lowercase hexadecimal string of the specified character length. Each character is independently drawn from the set {0-9, a-f}. Delegates to GenerateHex(IRandomSource, int).

Declaration

public static string GenerateHex(this IRandomSource rng, int length = 16)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
int	length	The number of hex characters to generate. Must be at least 1. Defaults to 16.

Returns

Type	Description
string	A random lowercase hexadecimal string of exactly length characters.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if length is less than 1.

GenerateID32(IRandomSource)

Generates a random non-zero 32-bit unsigned integer suitable for use as a unique entity or object identifier. The zero value is always excluded. Delegates to Generate32(IRandomSource).

Declaration

public static uint GenerateID32(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
uint	A random non-zero uint ID.

GenerateID64(IRandomSource)

Generates a random non-zero 64-bit unsigned integer suitable for use as a unique entity or object identifier. The zero value is always excluded. Delegates to Generate64(IRandomSource).

Declaration

public static ulong GenerateID64(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
ulong	A random non-zero ulong ID.

InsideUnitCircle(IRandomSource)

Returns a point uniformly distributed inside the unit circle (magnitude < 1). Delegates to InsideUnitCircle(IRandomSource).

Declaration

public static Vector2 InsideUnitCircle(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
Vector2	A UnityEngine.Vector2 with magnitude strictly less than 1.

InsideUnitSphere(IRandomSource)

Returns a point uniformly distributed inside the unit sphere (magnitude < 1). Delegates to InsideUnitSphere(IRandomSource).

Declaration

public static Vector3 InsideUnitSphere(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
Vector3	A UnityEngine.Vector3 with magnitude strictly less than 1.

NextAlphanumeric(IRandomSource)

Returns a random alphanumeric character drawn uniformly from the set {a-z, A-Z, 0-9} (62 possible characters). Delegates to NextAlphanumeric(IRandomSource).

Declaration

public static char NextAlphanumeric(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
char	A random character from a-z, A-Z, or 0-9.

NextBool(IRandomSource)

Returns a random bool with equal probability of true and false. Equivalent to a fair coin flip.

Declaration

public static bool NextBool(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
bool	true or false, each with 50% probability.

See Also

NextBool(IRandomSource, float)

NextBool(IRandomSource, float)

Returns a random bool with a caller-specified probability of being true.

Declaration

public static bool NextBool(this IRandomSource rng, float probability)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
float	probability	The probability of returning true, in the range [0, 1]. A value of 0 always returns false; a value of 1 always returns true.

Returns

Type	Description
bool	true with probability probability; false otherwise.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if probability is outside [0, 1].

NextColor(IRandomSource)

Returns a UnityEngine.Color with random RGB components each in [0, 1] and alpha fixed at 1 (fully opaque).

Declaration

public static Color NextColor(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
Color	A fully opaque UnityEngine.Color with random hue, saturation, and brightness.

See Also

NextColor(IRandomSource, bool)

NextColor(IRandomSource, bool)

Returns a UnityEngine.Color with random RGB components each in [0, 1]. The alpha channel is either fully opaque (1) or also random, depending on randomAlpha.

Declaration

public static Color NextColor(this IRandomSource rng, bool randomAlpha)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
bool	randomAlpha	When true, the alpha channel is also drawn uniformly from [0, 1]. When false, alpha is fixed at 1 (fully opaque).

Returns

Type	Description
Color	A UnityEngine.Color with random RGB components, and optionally a random alpha.

NextDigit(IRandomSource)

Returns a random decimal digit character drawn uniformly from {0-9}. Delegates to NextDigit(IRandomSource).

Declaration

public static char NextDigit(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
char	A random character in the range '0' to '9'.

NextDirection2D(IRandomSource)

Returns a uniformly random normalized 2D direction vector. Equivalent to a point on the unit circle - use when you need a random heading or velocity direction in 2D space. Delegates to OnUnitCircle(IRandomSource).

Declaration

public static Vector2 NextDirection2D(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
Vector2	A UnityEngine.Vector2 with magnitude 1.

NextDirection3D(IRandomSource)

Returns a uniformly random normalized 3D direction vector. Equivalent to a point on the unit sphere - use when you need a random heading or velocity direction in 3D space. Delegates to OnUnitSphere(IRandomSource).

Declaration

public static Vector3 NextDirection3D(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
Vector3	A UnityEngine.Vector3 with magnitude 1.

NextDouble(IRandomSource)

Returns a uniformly distributed random double in the half-open range [0, 1). Delegates to NextDouble01(IRandomSource).

Declaration

public static double NextDouble(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
double	A double uniformly distributed in [0, 1). Never exactly 1.0.

NextDouble(IRandomSource, double, double)

Returns a uniformly distributed random double in the range [minInclusive, maxExclusive].

Declaration

public static double NextDouble(this IRandomSource rng, double minInclusive, double maxExclusive)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
double	minInclusive	The inclusive lower bound.
double	maxExclusive	The inclusive upper bound. Must be greater than or equal to minInclusive.

Returns

Type	Description
double	A double uniformly distributed in [minInclusive, maxExclusive].

Exceptions

Type	Condition
ArgumentException	Thrown if minInclusive is greater than maxExclusive.

NextEnum<T>(IRandomSource)

Returns a uniformly random value from all defined values of enum type T. Each defined enum value has an equal probability of being returned.

Declaration

public static T NextEnum<T>(this IRandomSource rng) where T : struct, Enum

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
T	A random value from the set of values returned by Enum.GetValues(typeof(T)).

Type Parameters

Name	Description
T	The enum type to sample from. Must be a struct that implements Enum.

Remarks

This method calls Enum.GetValues on every invocation, which allocates an array. Avoid calling it in hot paths; cache the values array externally if needed.

NextFloat(IRandomSource)

Returns a uniformly distributed random float in the half-open range [0, 1). Delegates to NextFloat01(IRandomSource).

Declaration

public static float NextFloat(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
float	A float uniformly distributed in [0, 1). Never exactly 1.0.

NextFloat(IRandomSource, float, float)

Returns a uniformly distributed random float in the range [minInclusive, maxExclusive].

Declaration

public static float NextFloat(this IRandomSource rng, float minInclusive, float maxExclusive)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
float	minInclusive	The inclusive lower bound.
float	maxExclusive	The inclusive upper bound. Must be greater than or equal to minInclusive.

Returns

Type	Description
float	A float uniformly distributed in [minInclusive, maxExclusive].

Exceptions

Type	Condition
ArgumentException	Thrown if minInclusive is greater than maxExclusive.

NextGaussian(IRandomSource, float, float)

Returns a random value sampled from a Gaussian (normal) distribution with the given mean and standard deviation, using the Box-Muller transform. Useful for naturally varying game values such as AI reaction time, damage spread, procedural stat generation, or particle velocities.

Declaration

public static float NextGaussian(this IRandomSource rng, float mean = 0, float standardDeviation = 1)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
float	mean	The center of the distribution (expected value). Defaults to 0.
float	standardDeviation	Controls the spread of the distribution. Approximately 68% of values fall within one standard deviation of the mean, 95% within two. Must be non-negative. Defaults to 1 (standard normal distribution).

Returns

Type	Description
float	A float sampled from the N(mean, standardDeviation²) distribution. The result is unbounded - extreme values are possible but rare.

Remarks

The Box-Muller transform is used: two independent uniform [0, 1) values are converted to a Gaussian sample. The first value is resampled if it falls at or below float epsilon to avoid taking the logarithm of zero. Only one of the two Box-Muller outputs is used per call; the other is discarded.

NextInt(IRandomSource, int)

Returns a uniformly distributed random int in the range [0, maxExclusive). Shorthand for NextInt(0, maxExclusive).

Declaration

public static int NextInt(this IRandomSource rng, int maxExclusive)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
int	maxExclusive	The exclusive upper bound. Must be greater than 0.

Returns

Type	Description
int	A random int in the range [0, maxExclusive).

Exceptions

Type	Condition
ArgumentException	Thrown if maxExclusive is less than or equal to 0.

NextInt(IRandomSource, int, int)

Returns a uniformly distributed random int in the range [minInclusive, maxExclusive).

Declaration

public static int NextInt(this IRandomSource rng, int minInclusive, int maxExclusive)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
int	minInclusive	The inclusive lower bound. May be negative.
int	maxExclusive	The exclusive upper bound. Must be strictly greater than minInclusive.

Returns

Type	Description
int	A random int n such that minInclusive <= n < maxExclusive.

Exceptions

Type	Condition
ArgumentException	Thrown if minInclusive >= maxExclusive.

NextLetter(IRandomSource, bool)

Returns a random letter from the English alphabet. Delegates to NextLetter(IRandomSource, bool).

Declaration

public static char NextLetter(this IRandomSource rng, bool uppercase = false)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
bool	uppercase	When true, returns an uppercase letter (A-Z). When false (default), returns a lowercase letter (a-z).

Returns

Type	Description
char	A random letter character in the range a-z or A-Z.

NextParagraph(IRandomSource)

Generates a random paragraph with a sentence count randomly chosen in the typical range of 3-6 sentences. Delegates to NextParagraph(IRandomSource).

Declaration

public static string NextParagraph(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
string	A random paragraph string.

NextParagraph(IRandomSource, int)

Generates a random paragraph composed of exactly sentenceCount random sentences, space-separated. Delegates to NextParagraph(IRandomSource, int).

Declaration

public static string NextParagraph(this IRandomSource rng, int sentenceCount)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
int	sentenceCount	The number of sentences in the paragraph. Must be at least 1.

Returns

Type	Description
string	A random paragraph string.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if sentenceCount is less than 1.

NextRotation(IRandomSource)

Returns a UnityEngine.Quaternion sampled uniformly at random from the group of all 3D rotations. Uses the Shoemake method via RotationUniform(IRandomSource). The result is unbiased - unlike sampling Euler angles uniformly, every orientation in 3D space has equal probability.

Declaration

public static Quaternion NextRotation(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
Quaternion	A normalized UnityEngine.Quaternion representing a uniformly random rotation.

NextSentence(IRandomSource)

Generates a random sentence with a word count randomly chosen in the typical range of 4-10 words. Ends with a period. Delegates to NextSentence(IRandomSource).

Declaration

public static string NextSentence(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
string	A random sentence string ending with a period.

NextSentence(IRandomSource, int)

Generates a random sentence composed of exactly wordCount random gibberish words. The first word is capitalized and the sentence ends with a period. Delegates to NextSentence(IRandomSource, int).

Declaration

public static string NextSentence(this IRandomSource rng, int wordCount)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
int	wordCount	The number of words in the sentence. Must be at least 1.

Returns

Type	Description
string	A random sentence string ending with a period.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if wordCount is less than 1.

NextSign(IRandomSource)

Returns -1 or +1 with equal probability. Useful for randomly flipping a direction, side, or multiplier. Delegates to NextSign(IRandomSource).

Declaration

public static int NextSign(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
int	-1 or +1, each with 50% probability.

NextVector2(IRandomSource)

Returns a UnityEngine.Vector2 with both components independently drawn from the uniform range [0, 1). Not a directional or positional sample - use InsideUnitCircle(IRandomSource) or OnUnitCircle(IRandomSource) for geometric sampling.

Declaration

public static Vector2 NextVector2(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
Vector2	A UnityEngine.Vector2 with X and Y each uniformly distributed in [0, 1).

NextVector2(IRandomSource, float, float)

Returns a UnityEngine.Vector2 with both components independently drawn from the uniform range [min, max].

Declaration

public static Vector2 NextVector2(this IRandomSource rng, float min, float max)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
float	min	The inclusive minimum value applied to each component.
float	max	The inclusive maximum value applied to each component.

Returns

Type	Description
Vector2	A UnityEngine.Vector2 with X and Y each uniformly distributed in [min, max].

Exceptions

Type	Condition
ArgumentException	Thrown if min > max.

NextVector3(IRandomSource)

Returns a UnityEngine.Vector3 with all three components independently drawn from the uniform range [0, 1). Not a directional sample - use InsideUnitSphere(IRandomSource) or OnUnitSphere(IRandomSource) for geometric sampling.

Declaration

public static Vector3 NextVector3(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
Vector3	A UnityEngine.Vector3 with X, Y, and Z each uniformly distributed in [0, 1).

NextVector3(IRandomSource, float, float)

Returns a UnityEngine.Vector3 with all three components independently drawn from the uniform range [min, max].

Declaration

public static Vector3 NextVector3(this IRandomSource rng, float min, float max)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
float	min	The inclusive minimum value applied to each component.
float	max	The inclusive maximum value applied to each component.

Returns

Type	Description
Vector3	A UnityEngine.Vector3 with X, Y, and Z each uniformly distributed in [min, max].

Exceptions

Type	Condition
ArgumentException	Thrown if min > max.

NextWord(IRandomSource, bool)

Generates a random gibberish word with a length randomly chosen in the typical range of 3-8 characters. Delegates to NextWord(IRandomSource, bool).

Declaration

public static string NextWord(this IRandomSource rng, bool capitalize = false)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
bool	capitalize	When true, the first character is uppercase. Defaults to false.

Returns

Type	Description
string	A random word string between 3 and 8 characters long.

NextWord(IRandomSource, int, bool)

Generates a random gibberish word of exactly length characters composed of lowercase letters, with an optional capitalized first letter. Delegates to NextWord(IRandomSource, int, bool).

Declaration

public static string NextWord(this IRandomSource rng, int length, bool capitalize = false)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
int	length	The exact character length of the word. Must be at least 1.
bool	capitalize	When true, the first character is uppercase. Defaults to false.

Returns

Type	Description
string	A random word string of exactly length characters.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if length is less than 1.

OnUnitCircle(IRandomSource)

Returns a point uniformly distributed on the perimeter of the unit circle (magnitude == 1). Equivalent to a normalized random 2D direction vector. Delegates to OnUnitCircle(IRandomSource).

Declaration

public static Vector2 OnUnitCircle(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
Vector2	A UnityEngine.Vector2 with magnitude exactly 1.

OnUnitSphere(IRandomSource)

Returns a direction uniformly distributed on the surface of the unit sphere (magnitude == 1). Delegates to OnUnitSphere(IRandomSource).

Declaration

public static Vector3 OnUnitSphere(this IRandomSource rng)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.

Returns

Type	Description
Vector3	A UnityEngine.Vector3 with magnitude exactly 1.

PickMultiple<T>(IRandomSource, IReadOnlyList<T>, int)

Selects count distinct elements from list without replacement and returns them in a new list. The selection order is random and each element can appear at most once in the result.

Declaration

public static List<T> PickMultiple<T>(this IRandomSource rng, IReadOnlyList<T> list, int count)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
IReadOnlyList<T>	list	The source list to pick from. Must not be null.
int	count	The number of distinct elements to select. Must be in the range [0, list.Count].

Returns

Type	Description
List<T>	A new List<T> containing exactly count elements drawn without replacement from list.

Type Parameters

Name	Description
T	The type of elements in the list.

Remarks

This method uses a partial Fisher-Yates approach operating on an index list to avoid modifying the original collection. Time complexity is O(count) but allocates a temporary index list of size list.Count.

Exceptions

Type	Condition
ArgumentNullException	Thrown if list is null.
ArgumentOutOfRangeException	Thrown if count is negative or greater than list.Count.

PickOne<T>(IRandomSource, IReadOnlyList<T>)

Selects and returns a single uniformly random element from list. Each element has an equal probability of being chosen.

Declaration

public static T PickOne<T>(this IRandomSource rng, IReadOnlyList<T> list)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
IReadOnlyList<T>	list	The list to pick from. Must not be null and must contain at least one element.

Returns

Type	Description
T	A randomly selected element from list.

Type Parameters

Name	Description
T	The type of elements in the list.

Exceptions

Type	Condition
ArgumentNullException	Thrown if rng or list is null.
ArgumentException	Thrown if list is empty.

PickOne<T>(IRandomSource, ReadOnlySpan<T>)

Selects and returns a single uniformly random element from a ReadOnlySpan<T>. Useful for picking from stack-allocated or slice-based collections without allocation.

Declaration

public static T PickOne<T>(this IRandomSource rng, ReadOnlySpan<T> span)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
ReadOnlySpan<T>	span	The span to pick from. Must not be empty.

Returns

Type	Description
T	A randomly selected element from span.

Type Parameters

Name	Description
T	The type of elements in the span.

Exceptions

Type	Condition
ArgumentException	Thrown if span is empty.

PickWeighted<T>(IRandomSource, IReadOnlyList<T>, IReadOnlyList<float>)

Selects and returns a random element from items using proportional weighted sampling. The element at index i is selected with probability weights[i] / sum(weights).

Declaration

public static T PickWeighted<T>(this IRandomSource rng, IReadOnlyList<T> items, IReadOnlyList<float> weights)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
IReadOnlyList<T>	items	The list of items to select from. Must not be null and must have the same number of elements as weights.
IReadOnlyList<float>	weights	A list of non-negative weights, one per element in items. The total weight sum must be greater than zero. Must not be null.

Returns

Type	Description
T	The element from items at the index selected by weighted sampling.

Type Parameters

Name	Description
T	The type of elements in the item list.

Exceptions

Type	Condition
ArgumentNullException	Thrown if rng, items, or weights is null.
ArgumentException	Thrown if items and weights have different lengths, or if the total weight sum is zero.

RollD10(IRandomSource, int)

Rolls one or more 10-sided dice (d10) and returns their sum. The result is in the range [diceCount, diceCount * 10]. diceCount is clamped to [1, MAX_DICE].

Declaration

public static int RollD10(this IRandomSource rng, int diceCount = 1)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
int	diceCount	The number of d10 dice to roll. Defaults to 1.

Returns

Type	Description
int	The sum of diceCount d10 rolls.

RollD100(IRandomSource, int)

Rolls one or more 100-sided percentile dice (d100) and returns their sum. The result is in the range [diceCount, diceCount * 100]. diceCount is clamped to [1, MAX_DICE].

Declaration

public static int RollD100(this IRandomSource rng, int diceCount = 1)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
int	diceCount	The number of d100 dice to roll. Defaults to 1.

Returns

Type	Description
int	The sum of diceCount d100 rolls.

RollD12(IRandomSource, int)

Rolls one or more 12-sided dice (d12) and returns their sum. The result is in the range [diceCount, diceCount * 12]. diceCount is clamped to [1, MAX_DICE].

Declaration

public static int RollD12(this IRandomSource rng, int diceCount = 1)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
int	diceCount	The number of d12 dice to roll. Defaults to 1.

Returns

Type	Description
int	The sum of diceCount d12 rolls.

RollD20(IRandomSource, int)

Rolls one or more 20-sided dice (d20) and returns their sum. The result is in the range [diceCount, diceCount * 20]. diceCount is clamped to [1, MAX_DICE].

Declaration

public static int RollD20(this IRandomSource rng, int diceCount = 1)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
int	diceCount	The number of d20 dice to roll. Defaults to 1.

Returns

Type	Description
int	The sum of diceCount d20 rolls.

RollD4(IRandomSource, int)

Rolls one or more 4-sided dice (d4) and returns their sum. The result is in the range [diceCount, diceCount * 4]. diceCount is clamped to [1, MAX_DICE].

Declaration

public static int RollD4(this IRandomSource rng, int diceCount = 1)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
int	diceCount	The number of d4 dice to roll. Defaults to 1.

Returns

Type	Description
int	The sum of diceCount d4 rolls.

RollD6(IRandomSource, int)

Rolls one or more 6-sided dice (d6) and returns their sum. The result is in the range [diceCount, diceCount * 6]. diceCount is clamped to [1, MAX_DICE].

Declaration

public static int RollD6(this IRandomSource rng, int diceCount = 1)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
int	diceCount	The number of d6 dice to roll. Defaults to 1.

Returns

Type	Description
int	The sum of diceCount d6 rolls.

RollD8(IRandomSource, int)

Rolls one or more 8-sided dice (d8) and returns their sum. The result is in the range [diceCount, diceCount * 8]. diceCount is clamped to [1, MAX_DICE].

Declaration

public static int RollD8(this IRandomSource rng, int diceCount = 1)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
int	diceCount	The number of d8 dice to roll. Defaults to 1.

Returns

Type	Description
int	The sum of diceCount d8 rolls.

RollDice(IRandomSource, int, int, int)

Rolls diceCount dice, each with faceCount faces, and returns the sum of all rolls plus modifier. Each individual die produces a result in the range [1, faceCount].

Declaration

public static int RollDice(this IRandomSource rng, int diceCount, int faceCount, int modifier = 0)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
int	diceCount	The number of dice to roll. Must be at least 1 and at most MAX_DICE.
int	faceCount	The number of faces on each die. Must be at least 2.
int	modifier	A flat integer added to the total of all dice. May be negative. Defaults to 0.

Returns

Type	Description
int	The sum of all dice rolls plus modifier.

RollDice(IRandomSource, string)

Parses a dice notation string such as "2d6+5" or "d20" into a DiceRoll and immediately rolls it, returning the total result. The total includes each die's individual roll (in range [1, faces]) plus the modifier.

Declaration

public static int RollDice(this IRandomSource rng, string notation)

Parameters

Type	Name	Description
IRandomSource	rng	The random source used for rolling. Must not be null.
string	notation	A standard RPG dice notation string (e.g., "2d6+5", "d20", "3d8-2"). Dice count defaults to 1 if omitted.

Returns

Type	Description
int	The sum of all dice rolls plus the notation's modifier value.

Exceptions

Type	Condition
ArgumentNullException	Thrown if notation is null.
FormatException	Thrown if notation is not valid dice notation.

See Also

TryRollDice(IRandomSource, string, out int)

DiceRoll

RollDie(IRandomSource, int, int)

Rolls one or more dice with the specified number of faces and returns their sum. The minimum face count is clamped to 2 and dice count is clamped to [1, MAX_DICE].

Declaration

public static int RollDie(this IRandomSource rng, int faces, int diceCount = 1)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
int	faces	The number of faces on each die. Values below 2 are clamped to 2.
int	diceCount	The number of dice to roll. Defaults to 1. Clamped to [1, MAX_DICE].

Returns

Type	Description
int	The sum of diceCount individual die rolls, each in [1, faces].

SampleCircle(IRandomSource, Vector2, float, float, int)

Generates a set of points within a circular region using Poisson disk sampling (Bridson's algorithm). Points are guaranteed to be at least minDistance apart, producing a more natural and even distribution than purely uniform random sampling. Useful for placing trees, enemies, collectibles, and other game objects without visible clustering. Delegates to SampleCircle(IRandomSource, Vector2, float, float, int).

Declaration

public static List<Vector2> SampleCircle(this IRandomSource rng, Vector2 center, float radius, float minDistance, int k = 30)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
Vector2	center	The world-space center of the circular sampling region.
float	radius	The radius of the circular region. Must be greater than 0.
float	minDistance	The minimum guaranteed distance between any two generated points. Must be greater than 0. Smaller values produce denser point distributions.
int	k	The number of candidate points tried per active sample before it is removed from the active list. Higher values fill the space more densely but are slower. The value 30 is a good default for most cases.

Returns

Type	Description
List<Vector2>	A List<T> of UnityEngine.Vector2 points distributed within the circle with at least minDistance between each pair.

Exceptions

Type	Condition
ArgumentNullException	Thrown if rng is null.
ArgumentOutOfRangeException	Thrown if radius, minDistance, or k are invalid.

SamplePoisson(IRandomSource, Vector2, BoundChecker, float, int)

Generates a set of points within an arbitrary region defined by a PoissonDiskSampler.BoundChecker delegate, using Poisson disk sampling (Bridson's algorithm). Points are guaranteed to be at least minDistance apart. Use this overload to sample irregular shapes such as polygons, terrains, or runtime-computed regions. Delegates to Sample(IRandomSource, Vector2, BoundChecker, float, int).

Declaration

public static List<Vector2> SamplePoisson(this IRandomSource rng, Vector2 startPoint, PoissonDiskSampler.BoundChecker isInBounds, float minDistance, int k = 30)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
Vector2	startPoint	The initial seed point from which sampling expands. Must be within the bounds defined by isInBounds.
PoissonDiskSampler.BoundChecker	isInBounds	A delegate that returns true if a given UnityEngine.Vector2 is within the valid sampling region. Must not be null.
float	minDistance	The minimum guaranteed distance between any two generated points. Must be greater than 0.
int	k	The number of candidate points tried per active sample before removal. Defaults to 30.

Returns

Type	Description
List<Vector2>	A List<T> of UnityEngine.Vector2 points distributed within the custom region with at least minDistance between each pair.

Exceptions

Type	Condition
ArgumentNullException	Thrown if rng or isInBounds is null.
ArgumentOutOfRangeException	Thrown if minDistance or k are invalid.

SampleRectangle(IRandomSource, Vector2, Vector2, float, int)

Generates a set of points within an axis-aligned rectangular region using Poisson disk sampling (Bridson's algorithm). Points are guaranteed to be at least minDistance apart. Delegates to SampleRectangle(IRandomSource, Vector2, Vector2, float, int).

Declaration

public static List<Vector2> SampleRectangle(this IRandomSource rng, Vector2 center, Vector2 halfExtents, float minDistance, int k = 30)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
Vector2	center	The world-space center of the rectangular sampling region.
Vector2	halfExtents	The half-width (X) and half-height (Y) of the rectangle. Both components must be greater than 0.
float	minDistance	The minimum guaranteed distance between any two generated points. Must be greater than 0.
int	k	The number of candidate points tried per active sample before removal. Defaults to 30.

Returns

Type	Description
List<Vector2>	A List<T> of UnityEngine.Vector2 points distributed within the rectangle with at least minDistance between each pair.

Exceptions

Type	Condition
ArgumentNullException	Thrown if rng is null.
ArgumentOutOfRangeException	Thrown if halfExtents, minDistance, or k are invalid.

Shuffle<T>(IRandomSource, IList<T>)

Randomly reorders the elements of list in-place using the Knuth (Fisher-Yates) shuffle. Every permutation is equally likely. Lists with zero or one element are returned unchanged.

Declaration

public static void Shuffle<T>(this IRandomSource rng, IList<T> list)

Parameters

Type	Name	Description
IRandomSource	rng	The random source. Must not be null.
IList<T>	list	The mutable list to shuffle in-place. Must not be null.

Type Parameters

Name	Description
T	The type of elements in the list.

Exceptions

Type	Condition
ArgumentNullException	Thrown if rng or list is null.

TryRollDice(IRandomSource, string, out int)

Attempts to parse a dice notation string and roll it, returning whether the operation succeeded. Does not throw on invalid notation - returns false instead.

Declaration

public static bool TryRollDice(this IRandomSource rng, string notation, out int result)

Parameters

Type	Name	Description
IRandomSource	rng	The random source used for rolling. Must not be null.
string	notation	A standard RPG dice notation string (e.g., "2d6+5"). See DiceRoll for the supported format.
int	result	When this method returns true, contains the total dice roll result. When this method returns false, contains 0.

Returns

Type	Description
bool	true if notation was valid and the roll succeeded; false if the notation could not be parsed.

See Also

RandomUtil

IRandomSource