Random

Minetest provides four different random sources, each with its own merits. Modders must choose wisely unless they can let the engine do the random for them (e.g. randomly picking a sound or a texture for particles).

Lua builtins

Not restricted by mod security, these functions are available to both SSMs and CSMs:

math.randomseed

Seed the random. Minetest already does this for you using the system time.

IMPORTANT: Do not seed the random to turn it into a deterministic random source as other mods may expect it to be "non-deterministic".

Conversely, do not rely on the random to have any particular seed either; other mods & the engine may have seeded it (using the system time) to be "non-deterministic".

The problem with math.randomseed is that there is only one global, hidden seed. There is no way to get the current seed out; mods can't restore their random sequence. Mods seeding the random thus necessarily conflict - unless they all expect it to be "non-deterministic" and only seed it accordingly (ideally not at all, since the engine-side seeding should suffice).

If you need math.random for its performance but want it to be deterministic, you may reseed the random after you're done with it to ensure that it is "non-deterministic" again.

-- Use the random to generate a seed for the random; preferable over using system time,
-- as the latter may be deterministic
local seed = ... -- some fixed seed
local reseed = math.random(2^31-1)
math.randomseed(seed) -- temporarily make the random "deterministic"
-- ... do something using `math.random` ...
math.randomseed(reseed)

math.random

Get a random number. Very versatile; allows getting floats between 0 and 1 or integers in a range.

NOTE: The random numbers between 0 and 1 do not provide a full 52-bit mantissa full of entropy; they usually have around 32 bits of entropy.

WARNING: When using this to obtain integers, make sure that both the upper & lower bound as well as their difference are within the C int range - otherwise you may get overflows & errors.

TIP: Use math.random as your go-to versatile "non-deterministic" random source.

Random Number Generators

PcgRandom

A seedable 32-bit signed integer pseudo-random number generator.

PcgRandom(seed)

Constructs a PcgRandom instance with the given seed, which should be an integer within 32-bit bounds.

:next([min, max])

If min and max are both omitted, they default to -2^31 (-2147483648) and 2^31 - 1 (2147483647) respectively.

:rand_normal_dist(min, max, [num_trials])

WARNING: No successful use of this function is documented. Consider implementing your own normal distribution instead.

min and max are required; they need to be integers.

Rough approximation of a normal distribution with a mean of (max - min) / 2 and a variance of (((max - min + 1) ^ 2) - 1) / (12 * num_trials).

num_trials defaults to 6. The more trials, the better the approximation.

The return value is a float.

PseudoRandom

A seedable 16-bit unsigned integer pseudo-random number generator.

"Uses a well-known LCG algorithm introduced by K&R."

Perhaps the lowest-quality random generator of all.

PseudoRandom(seed)

Constructor: Takes a seed and returns a PseudoRandom object.

:next([min, max])

If min and max are both omitted, they default to 0 and 2^16-1 (32767) respectively.

WARNING: Requires ((max - min) == 32767) or ((max-min) <= 6553)) for a proper distribution.

SecureRandom

System-provided cryptographically secure random: An attacker should not be able to predict the generated sequence of random numbers. Use this when generating cryptographic keys or tokens.

On Windows, the Win32 Crypto API is used to retrieve cryptographically secure random values which is available on every supported version of Windows. On any other platform it is retrieved from /dev/urandom which should be available on all Unix-like platforms such as Linux and Android. However it is theoretically still possible that a secure random source is not available, and you should use an assertion to make sure that a SecureRandom object is actually returned (see below).

SecureRandom()

Constructor: Returns a SecureRandom object or nil if no secure random source is available.

TIP: Use assert(SecureRandom(), "no secure random available") to error if no secure random source is available.

:next_bytes([count])

Only argument is count, an optional integer defaulting to 1 and limited to 2048 specifying how many bytes are to be returned. Returned as a Lua bytestring of length count

Benchmarking

collectgarbage"stop" -- we don't want GC heuristics to interfere

local n = 1e8 -- number of runs
local function bench(name, constructor, invokation)
    local func = assert(loadstring(([[
local r = %s
for _ = 1, %d do %s end
]]):format(constructor, n, invokation)))
    local t = minetest.get_us_time()
    func()
    print(name, (minetest.get_us_time() - t) / n, "µs/call")
end

bench("Lua", "nil", "math.random()")
bench("PCG", "PcgRandom(42)", "r:next()")
bench("K&R", "PseudoRandom(42)", "r:next()")
bench("Secure", "assert(SecureRandom())", "r:next_bytes()")

Example output:

Lua 0.00385002  µs/call
PCG 0.05579729  µs/call
K&R 0.05859349  µs/call
Secure  0.11211887  µs/call

Comparison

Random Source	Performance	Bytes of entropy	Seedability	Versatility	Distribution	Security	Portability
math.random	very good (1x)	up to 4	global seed; seeded by default	very good	no guarantees, but usually decent enough	not cryptographically secure	varies by platform
PcgRandom	okay (~14x)	up to 4	per-instance seed	very good	good, decent guarantees	not cryptographically secure	always the same
PseudoRandom	okay (~15x)	1 to 2	per-instance seed	outright sucks	okay-ish	not cryptographically secure	always the same
SecureRandom	still okay (30x)	1 to 2048	not seedable			cryptographically secure	varies by platform; may be missing

Note: The performance comparison is a bit of an apples-to-oranges comparison for multiple reasons:

1. The different generators make different guarantees regarding the randomness;
2. The different generators generate different numbers of bytes per invocation - the default was arbitrarily chosen; Secure random in particular is able to generate plenty of bytes (up to 2048) with one call.

The benchmark still suffices to draw basic conclusions though, especially for the common case where a random source is simply used once (e.g. math.random() < 0.5).

Conclusion

1. Never use PseudoRandom. It is strictly inferior to PcgRandom.
2. Use math.random if you want a fast "non-deterministic" random.
3. Use PcgRandom if you need per-instance seedability and can take the performance hit.
4. Use SecureRandom if and only if you need a cryptographically secure random.