PCG Random Extension for Defold

This extension wraps PCG, A Family of Better Random Number Generators. C++ implementation v0.98.

Official website https://www.pcg-random.org

Official documentation https://www.pcg-random.org/using-pcg-cpp.html

The PCG Family

The PCG family combines properties not previously seen together in the same generation scheme:

• It's really easy to use, and yet its very flexible and offers powerful features.
• It's very fast, and can occupy very little space.
• It's performance in statistical tests is excellent (see the PCG paper for full details).
• It's much less predictable and thus more secure than most generators.

The PCG family offers various generators with different properties. There are 32-bit and 64-bit generators, some with huge periods, some with streams support, some take their own memory address as an addition to the seed, some can be initialized with extended data.

Setup

Paste this URL as a dependency in your game.project file.

https://github.com/Lerg/extension-pcgrandom/archive/master.zip

API reference

pcgrandom.new_rng(pcg_type: number, seed: number, [stream]: number) -> rng: lightuserdata

Creates a new specified random number generator with a given seed and an optional stream for generators that support it.

• pcg_type: number Generator type id.
• seed: number Seed number.
• stream: number Stream number.
• return: rng: lightuserdata RNG instance.

---

pcgrandom.new_rng_array(pcg_type: number, array: table, seed: number, [stream]: number) -> rng: lightuserdata

Creates a new specified extended random number generator with a given array for the extended data, seed and an optional stream.

Supported generators: pcgrandom.PCG32_K2, pcgrandom.PCG32_K64, pcgrandom.PCG32_C64, pcgrandom.PCG32_K1024, pcgrandom.PCG32_C1024, pcgrandom.PCG32_K16384.

• pcg_type: number Generator type id.
• array: table Array with UINT32 numbers for the extended data, the size of the array must match the generator type.
• seed: number Seed number.
• stream: number Stream number.
• return: rng: lightuserdata RNG instance.

---

pcgrandom.next(rng: lightuserdata) -> value: number

Generates a pseudorandom integer number.

• rng: lightuserdata RNG instance.
• return: value: number Random value.

---

pcgrandom.bound(rng: lightuserdata, upper_bound: number) -> value: number

Generates a pseudorandom integer number on [0,upper_bound) interval.

• rng: lightuserdata RNG instance.
• upper_bound: number Upper bound.
• return: value: number Random value.

---

pcgrandom.range(rng: lightuserdata, lower_bound: number, upper_bound: number) -> value: number

Generates a pseudorandom integer number on [lower_bound,upper_bound) interval.

• rng: lightuserdata RNG instance.
• lower_bound: number Lower bound.
• upper_bound: number Upper bound.
• return: value: number Random value.

---

pcgrandom.advance(rng: lightuserdata, delta: number)

Advances the generator forward delta steps, but does so in logarithmic time. (Not available for non-equidistributed extended generators.)

• rng: lightuserdata RNG instance.
• delta: number Delta.

---

pcgrandom.backstep(rng: lightuserdata, delta: number)

Moves the generator backwards delta steps, but does so in logarithmic time. (Not available for non-equidistributed extended generators.)

• rng: lightuserdata RNG instance.
• delta: number Delta.

---

pcgrandom.max(rng: lightuserdata) -> max: number

Returns the greatest possible random value from the generator.

• rng: lightuserdata RNG instance.
• return: max: number Max.

---

pcgrandom.period_pow2(rng: lightuserdata) -> period: number

Returns the period of the generator as a power of two. For PCG32, it returns 64, indicating a period of 2^64.

• rng: lightuserdata RNG instance.
• return: period: number Period.

---

pcgrandom.streams_pow2(rng: lightuserdata) -> streams: number

Returns the number of streams as a power of two. For PCG32, it returns 63, indicating 2^63 streams.

• rng: lightuserdata RNG instance.
• return: streams: number Streams.

---

pcgrandom.wrapped(rng: lightuserdata) -> wrapped: boolean

Tells you when the generator wraps around to the beginning (which we define as the zero state).

• rng: lightuserdata RNG instance.
• return: wrapped: boolean Wrapped.

---

pcgrandom.next_uint64(rng: lightuserdata) -> value: string

Generates a UINT64 pseudorandom number when used with a 64-bit generator.

• rng: lightuserdata RNG instance.
• return: value: string UINT64 random value represented as an 8 character long string - memory representation of a UINT64 number.

---

pcgrandom.next_real1(rng: lightuserdata) -> value: number

Generates a random number on [0,1]-real-interval.

• rng: lightuserdata RNG instance.
• return: value: number Random value.

---

pcgrandom.next_real2(rng: lightuserdata) -> value: number

Generates a random number on [0,1)-real-interval.

• rng: lightuserdata RNG instance.
• return: value: number Random value.

---

pcgrandom.genrand_res53(rng: lightuserdata) -> value: number

Generates a random number on [0,1)-real-interval with 53-bit resolution using a 64-bit integer when used with a 64-bit generator.

• rng: lightuserdata RNG instance.
• return: value: number Random value.

---

pcgrandom.genrand_res53_mix(rng: lightuserdata) -> value: number

Generates a random number on [0,1)-real-interval with 53-bit resolution using two 32bit integers.

• rng: lightuserdata RNG instance.
• return: value: number Random value.

---

pcgrandom.d4(rng: lightuserdata) -> value: number

Generates a random integer on [1,4] interval like from a dice.

• rng: lightuserdata RNG instance.
• return: value: number Random value.

---

pcgrandom.d6(rng: lightuserdata) -> value: number

Generates a random integer on [1,6] interval like from a dice.

• rng: lightuserdata RNG instance.
• return: value: number Random value.

---

pcgrandom.d8(rng: lightuserdata) -> value: number

Generates a random integer on [1,8] interval like from a dice.

• rng: lightuserdata RNG instance.
• return: value: number Random value.

---

pcgrandom.d10(rng: lightuserdata) -> value: number

Generates a random integer on [1,10] interval like from a dice.

• rng: lightuserdata RNG instance.
• return: value: number Random value.

---

pcgrandom.d12(rng: lightuserdata) -> value: number

Generates a random integer on [1,12] interval like from a dice.

• rng: lightuserdata RNG instance.
• return: value: number Random value.

---

pcgrandom.d20(rng: lightuserdata) -> value: number

Generates a random integer on [1,20] interval like from a dice.

• rng: lightuserdata RNG instance.
• return: value: number Random value.

---

pcgrandom.toss(rng: lightuserdata) -> value: number

Generates a random integer on [0,1] interval like from a toss of a coin.

• rng: lightuserdata RNG instance.
• return: value: number Random value.

---

pcgrandom.card(rng: lightuserdata) -> value: number

Generates a random integer on [1,52] interval like picking a random card from a standard deck.

• rng: lightuserdata RNG instance.
• return: value: number Random value.

---

pcgrandom.card2(rng: lightuserdata) -> suit: number, card: number

Generates two random integers on [1,4] and [1,13] intervals like picking a random card suit and a random card from a suit.

• rng: lightuserdata RNG instance.
• return: suit: number Random suit [1,4], card: number Random card [1,13].

---

pcgrandom.shuffle(rng: lightuserdata, array: table)

Shuffles the provided array in place.

• rng: lightuserdata RNG instance.
• array: table The array of values.

---

pcgrandom.delete(rng: lightuserdata)

Deletes the random generator and frees the alocated memory for it.

• rng: lightuserdata RNG instance.

---

Available generators

The number after PCG specifies the bit size of the generator (8, 16, 32, 64). It is possible to use 64-bit generators but Lua in Defold doesn't fully support such numbers.

The K variants are k-dimensionally equidistributed. The C variants offer better crypographic security, uniform but not equidistributed, harder to predict. The number after K or C specifies the extended data length, the higher the number the higher is the period of the generator.

ONESEQ variants offer a single stream.

UNIQUE variants have an extra seed based on memory address.

FAST variants are faster but slightly less statistically good output function (nevertheless still very good).

ONCE_INSECURE variants only output each number exactly once during their period. They are compact, and are statistically excellent, but should not be used except in specialized scenarios.

• pcgrandom.PCG32
• pcgrandom.PCG32_ONESEQ
• pcgrandom.PCG32_UNIQUE
• pcgrandom.PCG32_FAST
• pcgrandom.PCG64
• pcgrandom.PCG64_ONESEQ
• pcgrandom.PCG64_UNIQUE
• pcgrandom.PCG64_FAST
• pcgrandom.PCG8_ONCE_INSECURE
• pcgrandom.PCG16_ONCE_INSECURE
• pcgrandom.PCG32_ONCE_INSECURE
• pcgrandom.PCG64_ONCE_INSECURE
• pcgrandom.PCG8_ONESEQ_ONCE_INSECURE
• pcgrandom.PCG16_ONESEQ_ONCE_INSECURE
• pcgrandom.PCG32_ONESEQ_ONCE_INSECURE
• pcgrandom.PCG64_ONESEQ_ONCE_INSECURE
• pcgrandom.PCG32_K2
• pcgrandom.PCG32_K2_FAST
• pcgrandom.PCG32_K64
• pcgrandom.PCG32_K64_ONESEQ
• pcgrandom.PCG32_K64_FAST
• pcgrandom.PCG32_C64
• pcgrandom.PCG32_C64_ONESEQ
• pcgrandom.PCG32_C64_FAST
• pcgrandom.PCG32_K1024
• pcgrandom.PCG32_K1024_FAST
• pcgrandom.PCG32_C1024
• pcgrandom.PCG32_C1024_FAST
• pcgrandom.PCG32_K16384
• pcgrandom.PCG32_K16384_FAST
• pcgrandom.PCG64_K32
• pcgrandom.PCG64_K32_ONESEQ
• pcgrandom.PCG64_K32_FAST
• pcgrandom.PCG64_C32
• pcgrandom.PCG64_C32_ONESEQ
• pcgrandom.PCG64_C32_FAST
• pcgrandom.PCG64_K1024
• pcgrandom.PCG64_K1024_FAST
• pcgrandom.PCG64_C1024
• pcgrandom.PCG64_C1024_FAST

Example

local rng = pcgrandom.new_rng(pcgrandom.PCG32, socket.gettime())

print('uint32', pcgrandom.next(rng))
print('real2', pcgrandom.next_real2(rng))
print('d6', pcgrandom.d6(rng))

pcgrandom.delete(rng)
rng = nil