Struct RandomUtil.DeterministicRNG

A fast, seedable, replayable deterministic RNG suitable for gameplay simulation. This is a thin backwards-compatible wrapper around Xoshiro256StarStar using SplitMix64 seeding.

Implements

IRandomSource

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Scylla.Core.Util.Random

Assembly: ScyllaCore.dll

Syntax

[Serializable]
public struct RandomUtil.DeterministicRNG : IRandomSource

Remarks

This type is provided for backwards compatibility. New code should prefer Xoshiro256StarStar directly, or use the generic factory Create(RandomAlgorithm, ulong).

Because this is a struct, copies of a RandomUtil.DeterministicRNG are independent - each copy advances its own sequence. Passing by value implicitly forks the sequence.

Methods

Fork(ulong)

Creates a new RandomUtil.DeterministicRNG that is derived from the current instance and a user-supplied stream identifier. The resulting instance produces a completely independent sequence while remaining deterministic given the same parent state and streamID.

Declaration

public RandomUtil.DeterministicRNG Fork(ulong streamID)

Parameters

Type	Name	Description
ulong	streamID	An arbitrary value that distinguishes this fork from other forks of the same parent. Different values produce different independent sequences.

Returns

Type	Description
RandomUtil.DeterministicRNG	A new RandomUtil.DeterministicRNG whose sequence is deterministically derived from the current instance and `streamID`.

FromSeed(int)

Creates a RandomUtil.DeterministicRNG seeded with a 32-bit signed integer. The value is widened to 64 bits before SplitMix64 state expansion.

Declaration

public static RandomUtil.DeterministicRNG FromSeed(int seed)

Parameters

Type	Name	Description
int	seed	The seed value that fully determines the generated sequence. Identical seeds always produce identical sequences.

Returns

Type	Description
RandomUtil.DeterministicRNG	A new RandomUtil.DeterministicRNG instance initialized from `seed`.

FromSeed(long)

Creates a RandomUtil.DeterministicRNG seeded with a 64-bit signed integer. The value is reinterpreted as unsigned before SplitMix64 state expansion.

Declaration

public static RandomUtil.DeterministicRNG FromSeed(long seed)

Parameters

Type	Name	Description
long	seed	The seed value that fully determines the generated sequence. Identical seeds always produce identical sequences.

Returns

Type	Description
RandomUtil.DeterministicRNG	A new RandomUtil.DeterministicRNG instance initialized from `seed`.

FromSeed(uint)

Creates a RandomUtil.DeterministicRNG seeded with a 32-bit unsigned integer. The value is widened to 64 bits before SplitMix64 state expansion.

Declaration

public static RandomUtil.DeterministicRNG FromSeed(uint seed)

Parameters

Type	Name	Description
uint	seed	The seed value that fully determines the generated sequence. Identical seeds always produce identical sequences.

Returns

Type	Description
RandomUtil.DeterministicRNG	A new RandomUtil.DeterministicRNG instance initialized from `seed`.

FromSeed(ulong)

Creates a RandomUtil.DeterministicRNG seeded with a 64-bit unsigned integer. The seed is expanded to the 256-bit xoshiro256** state using SplitMix64.

Declaration

public static RandomUtil.DeterministicRNG FromSeed(ulong seed)

Parameters

Type	Name	Description
ulong	seed	The seed value that fully determines the generated sequence. Identical seeds always produce identical sequences.

Returns

Type	Description
RandomUtil.DeterministicRNG	A new RandomUtil.DeterministicRNG instance initialized from `seed`.

FromString(string)

Creates a RandomUtil.DeterministicRNG seeded by computing a stable hash of the given string. The same string always produces the same sequence regardless of platform or runtime version.

Declaration

public static RandomUtil.DeterministicRNG FromString(string seed)

Parameters

Type	Name	Description
string	seed	The string whose hash is used as the seed. Must not be `null`.

Returns

Type	Description
RandomUtil.DeterministicRNG	A new RandomUtil.DeterministicRNG instance seeded from the hash of `seed`.

GetState()

Retrieves a snapshot of the current internal state of this RNG. The returned value can be stored and later passed to SetState(DeterministicRNGState) to restore the generator to this exact position in its sequence.

Declaration

public RandomUtil.DeterministicRNGState GetState()

Returns

Type	Description
RandomUtil.DeterministicRNGState	A RandomUtil.DeterministicRNGState representing the four 64-bit components of the current xoshiro256** state.

NextBytes(byte[], int, int)

Fills a contiguous region of a byte array with pseudo-random bytes, one byte at a time, where each byte is independently and uniformly distributed in [0, 255].

Declaration

public void NextBytes(byte[] buffer, int offset = 0, int count = -1)

Parameters

Type	Name	Description
byte[]	buffer	The destination byte array. Must not be `null`.
int	offset	The zero-based starting index within `buffer` at which filling begins. Must be in the range `[0, buffer.Length]`. Defaults to `0`.
int	count	The number of bytes to fill starting at `offset`. Pass `-1` (the default) to fill all bytes from `offset` to the end of the array, equivalent to `buffer.Length - offset`. The sum `offset + count` must not exceed `buffer.Length`.

Exceptions

Type	Condition
ArgumentNullException	Thrown when `buffer` is `null`.
ArgumentOutOfRangeException	Thrown when `offset` is negative or greater than `buffer.Length`, when `count` is less than `-1`, or when `offset + count` exceeds `buffer.Length`.

NextUInt32()

Returns a uniformly distributed, unsigned 32-bit pseudo-random integer spanning the full range [0, 2^32).

Declaration

public uint NextUInt32()

Returns

Type	Description
uint	A random uint value in the range `[0, 4294967295]` (inclusive). All bit patterns are equally probable.

NextUInt64()

Returns a uniformly distributed, unsigned 64-bit pseudo-random integer spanning the full range [0, 2^64).

Declaration

public ulong NextUInt64()

Returns

Type	Description
ulong	A random ulong value in the range `[0, 18446744073709551615]` (inclusive). All bit patterns are equally probable.

Remarks

Implementations that are natively 32-bit (e.g. PCG32) compose this value from two successive 32-bit draws. Implementations that are natively 64-bit (e.g. Xoshiro256StarStar) return the value directly, making this the preferred primitive for high-throughput scenarios.

SetState(DeterministicRNGState)

Restores this RNG to a previously captured state, allowing the exact same sequence of values to be reproduced from that point forward.

Declaration

public void SetState(RandomUtil.DeterministicRNGState state)

Parameters

Type	Name	Description
RandomUtil.DeterministicRNGState	state	A RandomUtil.DeterministicRNGState previously obtained via GetState(). All four state components are restored verbatim.