PCG Random Number Generator native extension for the Defold Game Engine.
This extension generates random numbers with the minimal C implementation of PCG. Every random operation uses an explicit RNG context id, so deterministic systems can stay isolated from each other.
Add this project as a Defold library dependency:
https://github.com/selimanac/defold-random/archive/master.zip
If you find my Defold Extensions useful for your projects, please consider supporting it. I'd love to hear about your projects! Please share your released projects that use my native extensions. It would be very motivating for me.
Create an RNG context first. All random functions require the context id as the first argument.
local rng = rnd.new()
print(rnd.number(rng))
rnd.delete(rng)The extension can keep up to 255 active RNG contexts at the same time. Delete contexts you no longer use with rnd.delete(id), or clear all active contexts with rnd.clear_contexts().
For deterministic map generation, create the context from a user-visible seed:
local map_seed = 12345
local map_rng = rnd.new(map_seed)
local tile = rnd.range(map_rng, 1, 30)
local noise = rnd.double(map_rng)
rnd.delete(map_rng)rnd.new(init_state) uses init_seq = 1. Use rnd.new(init_state, init_seq) when you want to choose both unsigned 32-bit PCG seed inputs.
Creates an entropy-seeded RNG context and returns its id.
When no seed is provided, the extension uses the platform OS entropy source when available: SecRandomCopyBytes on Apple platforms, BCryptGenRandom on Windows, Web Crypto on HTML5, and /dev/urandom on Linux/Android. Unsupported platforms fall back to the bundled PCG time-based fallback entropy helper. The selected source is logged with dmLogInfo.
Creates a deterministic RNG context using an unsigned 32-bit init_state and init_seq = 1.
Creates a deterministic RNG context using exact unsigned 32-bit seed values.
Reseeds an existing context from entropy.
Reseeds an existing context using an unsigned 32-bit init_state and init_seq = 1.
Reseeds an existing context using exact unsigned 32-bit seed values.
Deletes one RNG context. The id becomes invalid.
Deletes all RNG contexts. Existing ids become invalid.
Lua numbers cannot exactly represent every 64-bit integer, so exact 64-bit seed APIs use decimal strings.
local rng = rnd.new64("12345678901234567890", "42")
rnd.delete(rng)Creates a context using exact unsigned 64-bit decimal string seed inputs.
Reseeds a context using exact unsigned 64-bit decimal string seed inputs.
Raw state APIs use decimal strings so the full PCG state can be saved and restored exactly.
local state, increment = rnd.state(rng)
rnd.set_state(rng, state, increment)Returns raw PCG state and increment as unsigned 64-bit decimal strings. increment controls the PCG stream.
Restores raw PCG state and increment from unsigned 64-bit decimal strings.
Returns a 32-bit unsigned integer as a Lua number. Values can be in [0, 4294967295].
Returns a table of 32-bit unsigned integers. count must be a non-negative integer. rnd.numbers(id, 0) returns an empty table.
Returns a 32-bit unsigned integer in [0, upper_bound). upper_bound must be greater than 0.
Returns a 32-bit unsigned integer in [min, max]. Only unsigned 32-bit integer bounds are supported.
Returns a table of 32-bit unsigned integers in [min, max].
Returns a floating point number in [0, 1).
Returns a table of floating point numbers in [0, 1). count must be a non-negative integer. rnd.doubles(id, 0) returns an empty table.
Returns a floating point number in [min, max). Not as fast as rnd.double(id).
Returns true or false with equal probability.
Returns true according to the given probability. Values less than or equal to 0 always return false; values greater than or equal to 1 always return true.
DnD style dice roller.
PARAMETERS
id(number) - RNG context id.roll(number) - Roll amount.type(number) - Dice type.
Dice constants:
rnd.d4- D4: four-sided die.rnd.d6- D6: six-sided die.rnd.d8- D8: eight-sided die.rnd.d10- D10: ten-sided die, returns 0-9.rnd.d12- D12: twelve-sided die.rnd.d20- D20: twenty-sided die.rnd.d100- D%: percentile die, returns 0-90 in tens.
RETURN
result(table) - Dice results.total(number) - Total amount of dice results.
local rng = rnd.new(123)
local result, total = rnd.dice(rng, 2, rnd.d10)Tosses a coin. Returns 0 or 1.
Rolls a six-sided die. Returns a number in [1, 6].
Picks a standard deck card index. Returns a number in [1, 52].
Picks a standard deck suit and rank as two return values. Suit is in [1, 4]; card is in [1, 13].
Shuffles the array part of a table in place using Fisher-Yates and returns the same table.
local rng = rnd.new(123)
local items = { "a", "b", "c", "d" }
rnd.shuffle(rng, items)Debug/sample method that prints PCG sample output and consumes the context RNG state.
- Breaking change: removed global RNG calls. Every random operation now requires an RNG context id.
- Added context lifecycle APIs:
rnd.new,rnd.new64,rnd.reset,rnd.reset64,rnd.delete, andrnd.clear_contexts. - Added exact raw state APIs:
rnd.state(id)andrnd.set_state(id, state, increment). - Added exact unsigned 64-bit decimal string support for context seeds and raw state save/restore.
- Added utility APIs:
rnd.bound(id, upper_bound),rnd.card(id), andrnd.card2(id).
- Added
rnd.seed32(init_state, init_seq)for exact deterministic unsigned 32-bit seeding from Lua. - Added batch generators:
rnd.numbers(count)rnd.ranges(count, min, max)rnd.doubles(count)
- Added probability helpers:
rnd.boolean()rnd.chance(probability)
- Added
rnd.shuffle(array)for in-place Fisher-Yates table shuffling. - Added
pcgrandom/annotations.lua - Added missing
rnd.dice()documentation topcgrandom.script_api. - Added entropy reseed logging showing whether OS entropy or fallback entropy was used.
rnd.seed()now reseeds from entropy only when called with no arguments.rnd.seed(0, seq)is now valid deterministic seeding behavior.rnd.double_range(min, max)now generates values in[min, max), matchingrnd.double()semantics.