RNG Methods

Burst is very restrictive in terms of inheritance and extensions so every Random Number Generator implements all the methods below. These methods are generated and identical between the RNG implementation.

Because of this highly duplicate nature, they are presented in this form and not in a classical Doxygen or similar.

Creation Methods

new XXX(seed)

Basic constructor that initializes the RNG with the given seed. Internally the SplitMix function is used, to initialize the internal state in an efficient way

CreateFromIndex(index, offset)

Specialized method for IParallelFor Jobs or normal for loops. Use the index of the loop or from the job as first parameter and a custom offset to make it unique.

CreateForEcs(int chunkIndexInQuery, int entityIndexInChunk, double globalTime = 1.0f, ulong customSeed = 0)

Specialized method to initialize the RNG inside the ECS system. The chunkIndexInQuery and entityIndexInChuck can be acquired very performantly with [ChunkIndexInQuery] and [EntityIndexInChunk]. Custom parameters globalTime and customSeed can be set, so the seed doesn’t statically depend on the index inside the ECS system.

CreateFrom(double globalTime, ulong customSeed = 1)

CreateFrom Time allows to use Unity’s time to provide a seed. A custom offset customSeed can be supplied, which is combined with the time to provide a unique seed.

CreateAdvanced()

The CreateAdvanced(...) method allows to directly initialize the internal RNG state without the custom hash function or any other general initialization code. This is an advanced method.

Next Uniform Random Numbers

bool NextBool()

Also:

  • bool2 NextBool2()
  • bool3 NextBool3()
  • bool4 NextBool4()

NextBool() returns a random boolean value with a 50% chance of being true and a 50% chance of being false. This method is good for generating single booleans, but if a lot of booleans are needed it might be better to use NextUInt() or NextULong() (depending on the size of the RNG) and then use bit operations to extract the booleans.

int NextInt()

Also:

  • int2 NextInt2()
  • int3 NextInt3()
  • int4 NextInt4()

NextInt() returns a uniform random integer value between int.MinValue and int.MaxValue.

uint NextUInt()

Also:

  • uint2 NextUInt2()
  • uint3 NextUInt3()
  • uint4 NextUInt4()

NextUInt() returns a uniform random unsigned integer value between uint.MinValue and uint.MaxValue.

ulong NextULong()

NextULong() returns a uniform random unsigned long integer value between 0 and ulong.MaxValue.

float NextFloat()

Also:

  • float2 NextFloat2()
  • float3 NextFloat3()
  • float4 NextFloat4()

Generates a random float between 0 and 1 by filling the mantissa with 23 random bits. Alternative Generation methods can be found in Conversion.AsFloatXXX Variants.

double NextDouble()

Also:

  • double2 NextDouble2()
  • double3 NextDouble3()
  • double4 NextDouble4()

Generates a random double between 0 and 1 by filling the mantissa with 52 random bits.

Ranged Uniform Random Numbers

int NextInt(intX max)

Also:

  • int NextInt(int max)
  • int2 NextInt2(int max)
  • int3 NextInt3(int max)
  • int4 NextInt4(int max)
  • int2 NextInt2(int2 max)
  • int3 NextInt3(int3 max)
  • int4 NextInt4(int4 max)

Generates a random integer between 0 and the given max (excluding max).

int NextInt(intX min, intX max)

Also:

  • int NextInt(int min, int max)
  • int2 NextInt2(int min, int max)
  • int3 NextInt3(int min, int max)
  • int4 NextInt4(int min, int max)
  • int2 NextInt2(int2 min, int2 max)
  • int3 NextInt3(int3 min, int3 max)
  • int4 NextInt4(int4 min, int4 max)

Generates a random integer between min (including) and the given max (excluding max).

uint NextUInt(uintX max)

Also:

  • uint2 NextUInt2(uint max)
  • uint3 NextUInt3(uint max)
  • uint4 NextUInt4(uint max)
  • uint2 NextUInt2(uint2 max)
  • uint3 NextUInt3(uint3 max)
  • uint4 NextUInt4(uint4 max)

Generates a random integer between 0 and the given max (excluding max).

uint NextUInt(uintX min, uintX max)

Also:

  • uint2 NextUInt2(uint min, uint max)
  • uint3 NextUInt3(uint min, uint max)
  • uint4 NextUInt4(uint min, uint max)
  • uint2 NextUInt2(uint2 min, uint2 max)
  • uint3 NextUInt3(uint3 min, uint3 max)
  • uint4 NextUInt4(uint4 min, uint4 max)

Generates a random integer between min (including) and the given max (excluding max).

ulong NextULong(ulong max)

Also:

  • ulong NextULong(ulong max)
  • ulong NextULong(ulong min, ulong max)

Generates a random integer between min (including), or 0, and the given max (excluding max).

float NextFloat(floatX max)

Also:

  • float2 NextFloat2(float max)
  • float3 NextFloat3(float max)
  • float4 NextFloat4(float max)
  • float2 NextFloat2(float2 max)
  • float3 NextFloat3(float3 max)
  • float4 NextFloat4(float4 max)

Generates a random float between 0 (including) and the given max (excluding max). Note that the internal multiplication, that has to be done to produce a number in that range, can sometimes include the maximum due to floating point inaccuracies.

float NextFloat(floatX min, floatX max)

Also:

  • float2 NextFloat2(float min, float max)
  • float3 NextFloat3(float min, float max)
  • float4 NextFloat4(float min, float max)
  • float2 NextFloat2(float2 min, float2 max)
  • float3 NextFloat3(float3 min, float3 max)
  • float4 NextFloat4(float4 min, float4 max)

Generates a random float between min (including) and the given max (excluding max). Note that the internal multiplication, that has to be done to produce a number in that range, can sometimes include the maximum due to floating point inaccuracies.

Collections

Shuffle(ref X)

The Shuffle(ref X) methods do uniformly and randomly shuffle any given NativeArray, NativeSlice or Span. The array contents has to be a struct (burst limitation).

Fill(ref X t)

Also:

  • Fill(ref Span t)
  • Fill(ref NativeSlice t)
  • Fill(ref NativeArray t)

The Fill() methods can be used to generate a large amount of random numbers to fill a custom array.