Struct Xoshiro256StarStar

A fast, seedable, replayable RNG suitable for deterministic gameplay simulation. Implements the xoshiro256** algorithm with SplitMix64 seeding. This is the default and recommended algorithm for most gameplay scenarios in Scylla.

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 Xoshiro256StarStar : IRandomSource

Remarks

xoshiro256** (Vigna/Blackman, 2018) is a high-quality 64-bit PRNG with:

256-bit internal state (four 64-bit words)
Period of 2^256 - 1 - effectively inexhaustible for any game application
Excellent statistical quality with no known failures in PractRand or TestU01
Very fast generation: one multiply, one rotation, and a few XOR/shift operations
All 64 output bits are of uniformly high quality (unlike xoroshiro128+)

The algorithm is the best overall choice for:

Gameplay mechanics (damage rolls, loot tables, AI decisions)
Procedural generation (terrain, dungeons, content)
Deterministic simulations that must reproduce identically from a saved seed
Any scenario requiring a single high-quality general-purpose RNG

For memory-constrained scenarios where 16 bytes of state is preferable to 32 bytes, see Xoroshiro128Plus. For multi-stream deterministic systems with compact serializable state, see PCG32.

The generator is a value type (struct) with a 32-byte footprint. Be aware that assigning a Xoshiro256StarStar value copies its state; two copies seeded identically will produce the same sequence. Use Fork(ulong) to derive independent child streams without duplicating sequences.

State can be captured and restored with GetState() and SetState(Xoshiro256State), enabling deterministic replay and save/load functionality.

Methods

Fork(ulong)

Creates a new independent child Xoshiro256StarStar RNG derived from this instance's current state and the provided stream ID. The parent generator's state is not advanced by this call.

Declaration

public Xoshiro256StarStar Fork(ulong streamID)

Parameters

Type	Name	Description
ulong	streamID	A 64-bit identifier that distinguishes the forked stream from other forks of the same parent. Different stream IDs produce statistically independent child generators. Passing the same stream ID from the same parent state always produces the same child.

Returns

Type	Description
Xoshiro256StarStar	A new Xoshiro256StarStar instance with an independent state derived from the parent state and `streamID`.

Remarks

The fork mixes all four 64-bit state words (via rotated XORs) into a single 64-bit summary value, then combines it with the stream ID (multiplied by the golden-ratio constant) via the SplitMix64 mixing function, and seeds a fresh generator from the result. This approach ensures:

The same parent state + stream ID pair always yields the same child generator.
Forked generators are statistically independent of the parent and of each other when using different stream IDs.
The parent generator continues from its current state unaffected.

Typical use: allocate one root generator per seed and fork one stream per entity, subsystem, or procedural layer to keep all sub-systems deterministic and independent.

FromSeed(int)

Creates a Xoshiro256** RNG from the specified 32-bit signed seed value.

Declaration

public static Xoshiro256StarStar FromSeed(int seed)

Parameters

Type	Name	Description
int	seed	The 32-bit signed seed. It is reinterpreted as a 32-bit unsigned integer, then widened to 64 bits before being expanded via SplitMix64.

Returns

Type	Description
Xoshiro256StarStar	A fully initialized Xoshiro256StarStar instance.

FromSeed(long)

Creates a Xoshiro256** RNG from the specified 64-bit signed seed value.

Declaration

public static Xoshiro256StarStar FromSeed(long seed)

Parameters

Type	Name	Description
long	seed	The 64-bit signed seed. It is reinterpreted bit-for-bit as a `ulong` before being expanded via SplitMix64.

Returns

Type	Description
Xoshiro256StarStar	A fully initialized Xoshiro256StarStar instance.

FromSeed(uint)

Creates a Xoshiro256** RNG from the specified 32-bit unsigned seed value.

Declaration

public static Xoshiro256StarStar FromSeed(uint seed)

Parameters

Type	Name	Description
uint	seed	The 32-bit unsigned seed. It is widened to 64 bits before being expanded via SplitMix64.

Returns

Type	Description
Xoshiro256StarStar	A fully initialized Xoshiro256StarStar instance.

FromSeed(ulong)

Creates a Xoshiro256** RNG using the specified 64-bit unsigned seed value. The seed is expanded via SplitMix64 into four 64-bit state words, and the resulting state is guaranteed non-zero.

Declaration

public static Xoshiro256StarStar FromSeed(ulong seed)

Parameters

Type	Name	Description
ulong	seed	The seed value used to initialize the RNG state. Four distinct SplitMix64 outputs are generated from the seed to populate the four state words. All seed values, including zero, produce valid non-degenerate states.

Returns

Type	Description
Xoshiro256StarStar	A fully initialized Xoshiro256StarStar instance.

FromString(string)

Creates a Xoshiro256** RNG from a stable hash of the given string. The string is hashed using FNV-1a to produce a reproducible 64-bit seed, making this useful for named procedural seeds (e.g., level names, world IDs).

Declaration

public static Xoshiro256StarStar FromString(string seed)

Parameters

Type	Name	Description
string	seed	The string used to generate a stable, cross-platform seed hash. The same string always produces the same RNG sequence on any platform.

Returns

Type	Description
Xoshiro256StarStar	A fully initialized Xoshiro256StarStar instance.

Exceptions

Type	Condition
ArgumentNullException	Thrown if `seed` is `null`.

GetState()

Retrieves the current internal state of the RNG for serialization or checkpointing.

Declaration

public Xoshiro256State GetState()

Returns

Type	Description
Xoshiro256State	An Xoshiro256State struct containing the current values of all four 64-bit state words. Restoring this snapshot via SetState(Xoshiro256State) will reproduce the exact same sequence of values from this point forward.

NextBytes(byte[], int, int)

Fills a specified portion of a byte array with random bytes generated by the xoshiro256** algorithm.

Declaration

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

Parameters

Type	Name	Description
byte[]	buffer	The byte array to populate. Must not be `null`.
int	offset	The zero-based index in `buffer` at which to begin writing. Must be in the range [0, `buffer.Length`]. Defaults to `0`.
int	count	The number of bytes to write starting at `offset`. Pass `-1` to fill from `offset` to the end of the buffer. Must satisfy `offset + count <= buffer.Length`.

Remarks

Each call to NextUInt64() produces 8 bytes written in little-endian order (least-significant byte first). Any unused bytes from the final 64-bit draw are discarded.

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 random value derived from the upper 32 bits of a full 64-bit xoshiro256** output.

Declaration

public uint NextUInt32()

Returns

Type	Description
uint	A uniformly distributed unsigned 32-bit integer in the range [`0`, `uint.MaxValue`].

Remarks

Calls NextUInt64() and discards the lower 32 bits. Because xoshiro256** produces uniformly high-quality bits at all positions, either half of the 64-bit result is equally valid. Discarding the low half is a convention that also allows packing two 32-bit values from one state step when needed. One full 64-bit state step is consumed per call regardless.

NextUInt64()

Returns an unsigned 64-bit random value using the xoshiro256** algorithm.

Declaration

public ulong NextUInt64()

Returns

Type	Description
ulong	A uniformly distributed unsigned 64-bit integer in the range [`0`, `ulong.MaxValue`] (all 64 bits are of uniformly high quality).

Remarks

The output is computed as rotl(s1 * 5, 7) * 9 before the state is advanced. The double-multiply scrambler (the "**" in the name) provides excellent bit diffusion across all 64 output bits with no known statistical weaknesses.

The state is then advanced via:

t = s1 << 17
s2 ^= s0
s3 ^= s1
s1 ^= s2
s0 ^= s3
s2 ^= t
s3 = rotl(s3, 45)

The rotation constants (17, 45) are the reference parameters from the xoshiro256** specification.

SetState(Xoshiro256State)

Restores the RNG to a previously saved state, enabling deterministic replay from a known checkpoint.

Declaration

public void SetState(Xoshiro256State state)

Parameters

Type	Name	Description
Xoshiro256State	state	The state snapshot to restore. If all four state words are zero (an invalid all-zero state), `S3` is automatically set to `1` to ensure the generator can produce valid output.

Remarks

The xoshiro256** algorithm must never have an all-zero state; advancing from all zeros produces only zeros. If a zero state is detected after restoration, the implementation corrects it automatically rather than throwing an exception, allowing graceful recovery from corrupt saves.