Class UnityRandomSource

An IRandomSource adapter that delegates random number generation to Unity's built-in global RNG (UnityEngine.Random), allowing Unity's random state to participate in the Scylla random subsystem.

Inheritance
object
UnityRandomSource
Implements
Inherited Members
Namespace: Scylla.Core.Util.Random
Assembly: ScyllaCore.dll
Syntax
public sealed class UnityRandomSource : IRandomSource
Remarks

UnityEngine.Random maintains a single, process-wide mutable state. Using this source has the following consequences:

  • Every call to NextUInt32(), NextUInt64(), or NextBytes(byte[], int, int) advances the global Unity random state, which will affect any other Unity code that also uses UnityEngine.Random in the same frame.
  • Only call this source from the main Unity thread. UnityEngine.Random is not thread-safe and will throw or produce incorrect results from background threads.
  • The global state can be captured and restored via GetState() and SetState(State), or scoped automatically with WithState(State, Action), to avoid cross-contaminating other systems.

For deterministic, seed-controlled gameplay randomness, prefer Xoshiro256StarStar or PCG32, which have no global state and support explicit state save/restore via typed state structs.

The output of this source is not cryptographically secure. For security-sensitive use cases, use CryptoRandomSource instead.

Methods

GetState()

Returns a snapshot of the current global UnityEngine.Random state.

Declaration
public static Random.State GetState()
Returns
Type Description
Random.State

A UnityEngine.Random.State value representing the exact internal state of the Unity random number generator at the moment of the call. Pass the returned value to SetState(State) or WithState(State, Action) to restore or temporarily apply this state.

NextBytes(byte[], int, int)

Fills a contiguous region of a byte array with pseudo-random bytes produced by successive calls to Range(int, int), one byte at a time.

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. Pass -1 (the default) to fill all bytes from offset to the end of the array. The sum offset + count must not exceed buffer.Length.
Remarks

Each byte is generated by a separate call to UnityEngine.Random.Range(0, 256), meaning this method advances the global Unity random state by count steps. For bulk byte generation, a source such as Xoshiro256StarStar is significantly faster because it produces 8 bytes per state-advance rather than one.

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 an unsigned 32-bit pseudo-random integer produced by calling Range(int, int) with [int.MinValue, int.MaxValue) and reinterpreting the result as an unsigned value.

Declaration
public uint NextUInt32()
Returns
Type Description
uint

A uint uniformly distributed across [0, 2^32). Internally advances the global UnityEngine.Random state by one step.

NextUInt64()

Returns an unsigned 64-bit pseudo-random integer composed from two successive 32-bit draws via NextUInt32().

Declaration
public ulong NextUInt64()
Returns
Type Description
ulong

A ulong uniformly distributed across [0, 2^64). Internally advances the global UnityEngine.Random state by two steps.
Remarks

Because UnityEngine.Random is natively 32-bit, this method requires two draws. The high 32 bits are filled first, followed by the low 32 bits: result = (hi << 32) | lo. Callers that consume many 64-bit values should consider switching to a native 64-bit source such as Xoshiro256StarStar for better throughput.

SetState(State)

Replaces the global UnityEngine.Random state with the specified snapshot, causing all subsequent calls to Unity's random API to produce output as if the generator had been running from that state.

Declaration
public static void SetState(Random.State state)
Parameters
Type Name Description
Random.State state

The UnityEngine.Random.State snapshot to apply. Typically obtained from a prior call to GetState().
Remarks

Because UnityEngine.Random is a global singleton, setting its state affects all code that consumes it in the same process. Consider using WithState(State, Action) to scope the state change and guarantee it is reverted even if an exception occurs.

WithState(State, Action)

Temporarily applies the specified UnityEngine.Random state for the duration of action, then unconditionally restores the previous state even if the action throws an exception.

Declaration
public static void WithState(Random.State state, Action action)
Parameters
Type Name Description
Random.State state

The UnityEngine.Random.State to activate while action runs. Typically obtained from a prior call to GetState().
Action action

The delegate to invoke while the specified state is active. Must not be null.
Remarks

This method uses a try/finally block to ensure the previous state is restored regardless of whether action completes normally or throws. Use this to produce a deterministic sub-sequence of random values without permanently altering the global Unity random stream.

Exceptions
Type Condition
ArgumentNullException

Thrown when action is null.

Implements

Extension Methods

See Also