Class RandomSeeder

Provides static seeding and bit-manipulation utilities used internally by all RNG algorithm implementations in the Scylla random subsystem.

Inheritance
object
RandomSeeder
Inherited Members
Namespace: Scylla.Core.Util.Random
Assembly: ScyllaCore.dll
Syntax
public static class RandomSeeder
Remarks

SplitMix64 is used as the canonical seed-expansion algorithm because it satisfies two important requirements: (1) any non-zero 64-bit input produces a high-quality, well-distributed output, and (2) successive outputs from incrementing a counter by the Weyl constant are statistically independent, making it ideal for populating multi-word states from a single seed.

The FNV-1a hash exposed by HashString(string) converts arbitrary string seeds into stable 64-bit values suitable for passing to the SplitMix64 expander. It is deterministic across platforms and runtime versions because it operates directly on char code units rather than relying on GetHashCode(), which is not stable across runs.

RotL(ulong, int) is a general-purpose helper exposed publicly so algorithm implementations can call it without duplicating the bit-rotation pattern.

Methods

EnsureNonZero(ulong[])

Ensures that a state array is not entirely composed of zero values, as required by the xoshiro and xoroshiro algorithms which produce invalid (all-zero) output sequences when their state is all-zeros.

Declaration
public static void EnsureNonZero(ulong[] state)
Parameters
Type Name Description
ulong[] state

The state array to validate and potentially repair. If null or empty, the method returns without taking any action. If all elements are 0, the last element is set to 1 to break the degenerate state.
Remarks

In practice this situation arises only when a seed of 0 is used with a seed-expansion path that happens to produce all-zero outputs - an extremely rare edge case. The fix of setting the last element to 1 is the same convention used by the reference xoshiro256** implementation.

ExpandSeed(ulong, int)

Expands a single 64-bit seed into an array of count independent 64-bit state values using sequential SplitMix64 steps.

Declaration
public static ulong[] ExpandSeed(ulong seed, int count)
Parameters
Type Name Description
ulong seed

The initial seed. Any value including 0 is valid; the SplitMix64 step immediately adds the Weyl increment before mixing, so a seed of 0 is treated as distinct from a seed of 1.
int count

The number of state values to generate. Must be greater than 0.
Returns
Type Description
ulong[]

A newly allocated ulong array of length count containing the expanded state values. Each element is the output of a successive call to SplitMix64Next(ref ulong) starting from seed. The caller should pass the result to EnsureNonZero(ulong[]) before using it to initialize a xoshiro or xoroshiro generator.
Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown when count is less than or equal to 0.
See Also

HashString(string)

Computes a stable, platform-independent 64-bit FNV-1a hash from a string, suitable for converting human-readable seed strings into numeric seeds.

Declaration
public static ulong HashString(string s)
Parameters
Type Name Description
string s

The input string to hash. Must not be null. An empty string returns the FNV-1a offset basis value (14695981039346656037).
Returns
Type Description
ulong

A 64-bit hash value that is deterministic across platforms and .NET versions because it operates on raw UTF-16 code units (char values) rather than relying on GetHashCode(). The same string always produces the same seed.
Remarks

Pass the returned value to ExpandSeed(ulong, int) or directly to an algorithm's FromSeed(ulong) factory method to create a reproducible generator from a human-readable identifier such as a level name or world seed string.

Exceptions
Type Condition
ArgumentNullException

Thrown when s is null.

RotL(ulong, int)

Performs a circular left bit-rotation of a 64-bit unsigned integer by k positions.

Declaration
public static ulong RotL(ulong x, int k)
Parameters
Type Name Description
ulong x

The 64-bit value to rotate.
int k

The number of bit positions to rotate left. Must be in the range [0, 63]. Passing values outside this range produces undefined results due to the shift arithmetic.
Returns
Type Description
ulong

The result of rotating x left by k bits, equivalent to (x << k) | (x >> (64 - k)).
Remarks

This operation is used extensively in the xoshiro256** and xoroshiro128+ update steps. It is exposed publicly so algorithm implementations can share a single, inlineable helper rather than each duplicating the expression.

SplitMix64Mix(ulong)

Applies the SplitMix64 finalizer (mixing) function to an arbitrary 64-bit value, producing a well-distributed output regardless of the input's bit pattern.

Declaration
public static ulong SplitMix64Mix(ulong z)
Parameters
Type Name Description
ulong z

The 64-bit input value to mix. Any value is acceptable, including structured or low-entropy inputs such as sequential integers.
Returns
Type Description
ulong

A 64-bit value with strongly avalanching bit distribution. The mix is an invertible bijection, so the output space is the full range [0, 2^64) with no collisions.
Remarks

The three XOR-and-multiply rounds (with the constants 0xBF58476D1CE4E5B9 and 0x94D049BB133111EB) are derived from the MurmurHash3 finalizer and are known to pass the SMHasher test suite. This function is also used standalone in Fork(ulong) to mix stream IDs into independent seeds.

SplitMix64Next(ref ulong)

Advances a SplitMix64 counter state by one step and returns the corresponding high-quality 64-bit output value.

Declaration
public static ulong SplitMix64Next(ref ulong state)
Parameters
Type Name Description
ulong state

The mutable counter state, passed by reference. Incremented by Scylla.Core.Util.Random.RandomSeeder.SPLITMIX_INCREMENT (the golden-ratio Weyl constant) before the mix function is applied. The caller is responsible for storing the updated value.
Returns
Type Description
ulong

A 64-bit pseudo-random value produced by passing the advanced counter through SplitMix64Mix(ulong). Successive calls with any starting state produce statistically independent outputs suitable for initializing multi-word RNG states.
See Also

See Also