Skip to Content
defold-typescript libraries
selimanac

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)
    1. Pick a release from selimanac/defold-random releases and add its Source code (zip) URL (or a packaged .zip asset, if the library ships one) to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as rnd from "rnd"
  • Asset Portal: defold-random

Functions

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 to random unchanged.

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.

On this page