This module adds a few functions for generating random numbers, and possibly other things randomly in the future.

Functions

• phi.rng:uuid, generates a random number in the range -2147483648..2147483647 (-2^31..2^31-1). This is generated by summoning a new entity and getting the UUID. This is the most random RNG, but may not be the fastest, and cannot be seeded. The output is stored in $phi.rng.value phitemp

• phi.rng:global_lcg, generates a random number in the range -134217728..134217727. This is less random than UUID, but uses only the scoreboard. This is generated using a Linear Congruential Generator (LCG). This is a well known, but simplistic algorithm, which is known to not be the most random, but gives good enough results in most cases and is very fast/easy to calculate. This specific function uses a shared seed. The output is stored in $phi.rng.value phitemp

• phi.rng:reset_seed, recalculates the shared seed used by phi.rng:global_lcg. This is rarely needed, but is available in the public API in case it is needed

• phi.rng:lcg, uses the same algorithm as phi.rng:global_lcg, except uses the seed that is passed in to the function.

  The seed is input in $phi.rng.lcg.seed phitemp which is modified into the new seed, and the output is stored in $phi.rng.value phitemp

  The modified seed should be copied to another score for safe keeping, and restored next time a random number is needed. The seed will be modified on every call

• phi.rng:lcg_raw, same as phi.rng:lcg, but has a range of -2147483648..2147483647 (-2^31..2^31-1). However, this is not recommended when converting this to a small range, because the low bits of this number has low entropy. For large ranges this isn't a problem

• phi.rng:lcg_range_fast, this generates a random number from $phi.rng.range.min phitemp inclusive to $phi.rng.range.max phitemp exclusive. This uses the LCG algorithm, but may not be perfectly uniform

• phi.rng:lcg_range_uniform, this is the same as phi.rng:lcg_range_fast, except is slightly more sophisticated to ensure the output is uniform, at a slight cost to performance

• phi.rng:global_lcg_range_fast, same as phi.rng:lcg_range_fast but using the global seed

• phi.rng:global_lcg_range_uniform, same as phi.rng:lcg_range_uniform but using the global seed

• phi.rng:uuid_range_fast, this generates a random number from $phi.rng.range.min phitemp inclusive to $phi.rng.range.max phitemp exclusive. This uses the UUID algorithm, but may not be perfectly uniform

• phi.rng:uuid_range_uniform, this is the same as phi.rng:uuid_range_fast, except is slightly more sophisticated to ensure the output is uniform, at a slight cost to performance, and a slight cost to entropy (but for the vast majority of ranges this entropy difference is negligible)

• phi.rng:bool, generates a random true (1)/false(0) value. This cannot be seeded, because LCG is not very well suited to separating into individual bits, as such this always uses the UUID technique.