selimanac/defold-random/random
PCG Random Number Generator Native Extension for the Defold Game Engine
- GitHub: selimanac/defold-random — pinned to
v1.3.0(released while Defold 1.13.0 was current)- Pick a release from selimanac/defold-random releases and add its Source code (zip) URL (or a packaged
.zipasset, if the library ships one) togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as rnd from "rnd"
- Pick a release from selimanac/defold-random releases and add its Source code (zip) URL (or a packaged
- Asset Portal: defold-random
Functions
rnd.new(init_state: number, init_seq: number): numberrnd.new64(init_state: string, init_seq: string): numberrnd.reset(id: number, init_state: number, init_seq: number)rnd.reset64(id: number, init_state: string, init_seq: string)rnd.delete(id: number)rnd.clear_contexts()rnd.state(id: number): LuaMultiReturn<[string, string]>rnd.set_state(id: number, state: string, increment: string)rnd.number(id: number): numberrnd.numbers(id: number, count: number): tablernd.bound(id: number, upper_bound: number): numberrnd.range(id: number, min: number, max: number): numberrnd.ranges(id: number, count: number, min: number, max: number): tablernd.double(id: number): numberrnd.doubles(id: number, count: number): tablernd.double_range(id: number, min: number, max: number): numberrnd.boolean(id: number): booleanrnd.chance(id: number, probability: number): booleanrnd.toss(id: number): numberrnd.roll(id: number): numberrnd.card(id: number): numberrnd.card2(id: number): LuaMultiReturn<[number, number]>rnd.dice(id: number, roll: number, type: number): LuaMultiReturn<[table, number]>rnd.shuffle(id: number, array: table): tablernd.check(id: number)
rnd.new(init_state: number, init_seq: number): number
Creates an isolated RNG context and returns its context id. Call without arguments to seed from entropy, with init_state to use init_seq = 1, or with init_state and init_seq for exact unsigned 32-bit deterministic seeding.
Parameters
init_state:number— Optional starting state for the RNG. Must be an unsigned 32-bit integer.init_seq:number— Optional output sequence for the RNG. Must be an unsigned 32-bit integer.
Returns
Id:number— RNG context id.
rnd.new64(init_state: string, init_seq: string): number
Creates an isolated RNG context using exact unsigned 64-bit decimal string seeds.
Parameters
init_state:string— Starting state for the RNG as an unsigned 64-bit decimal string.init_seq:string— Output sequence for the RNG as an unsigned 64-bit decimal string.
Returns
Id:number— RNG context id.
rnd.reset(id: number, init_state: number, init_seq: number)
Reseeds an existing RNG context. Call with only id to seed from entropy, with id and init_state to use init_seq = 1, or with id, init_state, and init_seq for exact unsigned 32-bit deterministic seeding.
Parameters
id:number— RNG context id.init_state:number— Optional starting state for the RNG. Must be an unsigned 32-bit integer.init_seq:number— Optional output sequence for the RNG. Must be an unsigned 32-bit integer.
rnd.reset64(id: number, init_state: string, init_seq: string)
Reseeds an existing RNG context using exact unsigned 64-bit decimal string seeds.
Parameters
id:number— RNG context id.init_state:string— Starting state for the RNG as an unsigned 64-bit decimal string.init_seq:string— Output sequence for the RNG as an unsigned 64-bit decimal string.
rnd.delete(id: number)
Deletes an RNG context. The context id becomes invalid.
Parameters
id:number— RNG context id.
rnd.clear_contexts()
Deletes all RNG contexts. Existing context ids become invalid.
rnd.state(id: number): LuaMultiReturn<[string, string]>
Returns raw PCG state and increment as unsigned 64-bit decimal strings.
Parameters
id:number— RNG context id.
Returns
State:string— Raw PCG state.Increment:string— Raw PCG increment. Controls the PCG stream.
rnd.set_state(id: number, state: string, increment: string)
Restores raw PCG state and increment from unsigned 64-bit decimal strings.
Parameters
id:number— RNG context id.state:string— Raw PCG state.increment:string— Raw PCG increment. Controls the PCG stream.
rnd.number(id: number): number
Returns a 32-bit unsigned integer.
Parameters
id:number— RNG context id.
Returns
Random Number:number— Returns a 32-bit unsigned integer.
rnd.numbers(id: number, count: number): table
Returns a table of 32-bit unsigned integers.
Parameters
id:number— RNG context id.count:number— Number of values to generate. Must be a non-negative integer.
Returns
Random Numbers:table— Table of 32-bit unsigned integers.
rnd.bound(id: number, upper_bound: number): number
Returns a 32-bit unsigned integer in [0, upper_bound).
Parameters
id:number— RNG context id.upper_bound:number— Exclusive upper bound. Must be an unsigned 32-bit integer greater than 0.
Returns
Random Number:number— Returns a 32-bit unsigned integer in [0, upper_bound).
rnd.range(id: number, min: number, max: number): number
Returns a 32-bit unsigned integer between min and max values, inclusive. Only unsigned integers are supported.
Parameters
id:number— RNG context id.min:number— Minimum unsigned integer.max:number— Maximum unsigned integer.
Returns
Random Number:number— Returns a 32-bit unsigned integer between min and max values.
rnd.ranges(id: number, count: number, min: number, max: number): table
Returns a table of 32-bit unsigned integers between min and max values, inclusive.
Parameters
id:number— RNG context id.count:number— Number of values to generate. Must be a non-negative integer.min:number— Minimum unsigned integer.max:number— Maximum unsigned integer.
Returns
Random Numbers:table— Table of 32-bit unsigned integers between min and max values.
rnd.double(id: number): number
Returns a floating point number in [0, 1).
Parameters
id:number— RNG context id.
Returns
Random Number:number— Returns a floating point number in [0, 1).
rnd.doubles(id: number, count: number): table
Returns a table of floating point numbers in [0, 1).
Parameters
id:number— RNG context id.count:number— Number of values to generate. Must be a non-negative integer.
Returns
Random Numbers:table— Table of floating point numbers in [0, 1).
rnd.double_range(id: number, min: number, max: number): number
Returns a floating point number in [min, max). Not fast as rnd.double(id)
Parameters
id:number— RNG context id.min:number— Minimum number.max:number— Maximum number.
Returns
Random Number:number— Returns a floating point number in [min, max).
rnd.boolean(id: number): boolean
Returns true or false with equal probability.
Parameters
id:number— RNG context id.
Returns
Random Boolean:boolean— Random boolean value.
rnd.chance(id: number, probability: number): boolean
Returns true according to the given probability.
Parameters
id:number— RNG context id.probability:number— Probability from 0.0 to 1.0. Values <= 0 are always false and values >= 1 are always true.
Returns
Success:boolean— True if the probability check succeeds.
rnd.toss(id: number): number
Toss a coin.
Parameters
id:number— RNG context id.
Returns
Random Number:number— Returns 0 or 1 (0 = 'H', 1 = 'T')
rnd.roll(id: number): number
Roll the dice.
Parameters
id:number— RNG context id.
Returns
Random Number:number— Returns between 1-6
rnd.card(id: number): number
Picks a standard deck card index.
Parameters
id:number— RNG context id.
Returns
Card:number— Card index in [1, 52]. ⚠️ 1-based; passed torandomunchanged.
rnd.card2(id: number): LuaMultiReturn<[number, number]>
Picks a standard deck suit and rank.
Parameters
id:number— RNG context id.
Returns
Suit:number— Suit in [1, 4].Card:number— Card rank in [1, 13].
rnd.dice(id: number, roll: number, type: number): LuaMultiReturn<[table, number]>
Rolls dice using one of the exported dice constants.
Parameters
id:number— RNG context id.roll:number— Roll count. Must be greater than 0.type:number— Dice type. Use rnd.d4, rnd.d6, rnd.d8, rnd.d10, rnd.d12, rnd.d20, or rnd.d100.
Returns
Results:table— Table of dice results.Total:number— Total amount of dice results.
rnd.shuffle(id: number, array: table): table
Shuffles the array part of a table in place using Fisher-Yates.
Parameters
id:number— RNG context id.array:table— Table to shuffle.
Returns
Array:table— The same table, shuffled in place.
rnd.check(id: number)
Debug/sample method that prints PCG sample output and consumes RNG state.
Parameters
id:number— RNG context id.