nupp.random

Deterministic pseudo-random generation with explicit, serializable state.

Each Random owns an independent xoshiro128** sequence. A seed is always interpreted as one 32-bit word, and omitting it chooses a fixed seed rather than consulting a clock, so every sequence is reproducible. Generators are mutable and intentionally not safe to share between concurrent workers.

local random = require("nupp.random")

local dice = random.newRandom(42)
local d20 = dice:integer(20)
local unit = dice:next()

state and setState copy the four signed 32-bit state words. They are the portable checkpoint format: preserving them preserves the next draw exactly.

Module contents

Constructors

ConstructorDescription
newRandomCreates a generator outside any host or scheduler.

Types

TypeKindDescription
RandomrecordAn independent deterministic xoshiro128 sequence.

Constructors#

newRandomconstructor#

function newRandom(seed: integer?): Random

Creates a generator outside any host or scheduler.

Arguments

NameTypeDescription
seedinteger?

Returns

TypeDescription
Random

Types#

Randomrecord#

record Random
    constructor(self, seed: integer?) end

    function next(self): number end

    function integer(self, m: integer, n: integer?): integer end

    function range(self, low: number, high: number): number end

    function shuffle<T>(self, values: {T}): {T} end

    function reseed(self, seed: integer): nil end

    function state(self): {integer} end

    function setState(self, words: {integer}): nil end
end

An independent deterministic xoshiro128** sequence.

Methods

constructor#
constructor: function constructor(self, seed: integer?)

Creates a generator. An omitted seed uses a fixed reproducible value.

Arguments
NameTypeDescription
selfany
seedinteger?
next#
next: function next(self): number

Returns the next multiple of 2^-32 in [0, 1).

Arguments
NameTypeDescription
selfany
Returns
TypeDescription
number
integer#
integer: function integer(self, m: integer, n: integer?): integer

Returns an integer in [1, m], or in [m, n] when both are given.

Arguments
NameTypeDescription
selfany
minteger
ninteger?
Returns
TypeDescription
integer
Raises

  • when the selected range is empty

range#
range: function range(self, low: number, high: number): number

Returns the next value in [low, high), or (high, low] when reversed.

Arguments
NameTypeDescription
selfany
lownumber
highnumber
Returns
TypeDescription
number
shuffle#
shuffle: function shuffle<T>(self, values: {T}): {T}

Shuffles a list in place with Fisher-Yates and returns the same list.

Arguments
NameTypeDescription
selfany
values{T}
Returns
TypeDescription
{T}
reseed#
reseed: function reseed(self, seed: integer): nil

Restarts this generator from a 32-bit seed without changing its identity.

Arguments
NameTypeDescription
selfany
seedinteger
Returns
TypeDescription
nil
state#
state: function state(self): {integer}

Copies the four signed 32-bit state words into a fresh array.

Arguments
NameTypeDescription
selfany
Returns
TypeDescription
{integer}
setState#
setState: function setState(self, words: {integer}): nil

Restores exactly four state words.

Arguments
NameTypeDescription
selfany
words{integer}
Returns
TypeDescription
nil
Raises

  • when there are not four words or all four are zero