XRNG
XRNG is a seedable 32-bit RNG library with multiple instance support. It's an SRB2 Lua implementation of xoshiro128++ PRNG. Created instances should be seeded with a number or a string, otherwise the generated number sequences will always be the same after initialization.To add the library to your mod, make sure to insert the lua file in the WAD/PK3 before all scripts that will use it. If you want to insert it to a mod in WAD format, you'll need to change the file name. (LUA_XRNG is recommended)
Make sure to read both of the spoilers below, they explain things you'll need to know if you want to use XRNG.
Important:
For netgame compatibility, you'll need to synchronize the RNG state (
The recommended way to do it is by using a NetVars hook:
s) for every XRNG instance you create.The recommended way to do it is by using a NetVars hook:
Example:
local rng = newXRNG();
addHook("NetVars",function(net)
rng.s = net($)
end)Functions:
You need to use the newXRNG function at least once to be able to use this library, as all other functions are called from an XRNG instance.
newXRNG(seed)
rng will be used as the name of an XRNG instance in the function descriptions below, but you can name it any way you want. Just make sure to replace rng with your instance name when calling these functions.
rng:setSeed(seed)
rng:randomNumber()
rng:randomUnsigned()
rng:randomFixed()
rng:randomByte()
rng:randomKey(a)
rng:randomRange(a,b)
rng:randomChance(p)
newXRNG(seed)
Description
This function creates a new XRNG instance.
Parameters
seed - seed given to the created XRNG instance (string or number, defaults to 0 if not specified)
Return values
rng - new XRNG instance
finalseed - seed actually used by the instance, always a number
This function creates a new XRNG instance.
Parameters
seed - seed given to the created XRNG instance (string or number, defaults to 0 if not specified)
Return values
rng - new XRNG instance
finalseed - seed actually used by the instance, always a number
Usage examples:
--Create an RNG with seed 0
local rng = newXRNG()
--Create an RNG with seed 42
local rng2 = newXRNG(42)
--Create an RNG seeded with a string, which is hashed to an integer
local rng3 = newXRNG("example")
--The same as above, but also put the hashed seed value in finalseed variable
local rng4, finalseed = newXRNG("example")rng will be used as the name of an XRNG instance in the function descriptions below, but you can name it any way you want. Just make sure to replace rng with your instance name when calling these functions.
rng:setSeed(seed)
Description
This function changes the RNG seed to a given value (strings are hashed to numbers).
Parameters
seed - seed given to the XRNG instance (string or number, defaults to 0 if not specified)
Return values
finalseed - seed actually used by the instance, always a number
This function changes the RNG seed to a given value (strings are hashed to numbers).
Parameters
seed - seed given to the XRNG instance (string or number, defaults to 0 if not specified)
Return values
finalseed - seed actually used by the instance, always a number
Usage examples:
--Set the seed to 42
rng:seed(42)
--Seed RNG with a string, which is hashed to an integer
rng:seed("example")
--The same as above, but also put the hashed seed value in finalseed variable
finalseed = rng:seed("example")Description
This function returns a random integer.
Return values
result - generated random value
This function returns a random integer.
Return values
result - generated random value
Description
This function returns a random non-negative integer.
Return values
result - generated random value
This function returns a random non-negative integer.
Return values
result - generated random value
Description
This function returns a random integer from 0 to FRACUNIT-1.
Return values
result - generated random value
This function returns a random integer from 0 to FRACUNIT-1.
Return values
result - generated random value
Description
This function returns a random integer from 0 to 255.
Return values
result - generated random value
This function returns a random integer from 0 to 255.
Return values
result - generated random value
Description
This function returns a random integer from 1 to a. Useful for getting a random key/index for Lua arrays.
Parameters
a - highest possible result
Return values
result - generated random value
This function returns a random integer from 1 to a. Useful for getting a random key/index for Lua arrays.
Parameters
a - highest possible result
Return values
result - generated random value
Description
This function returns a random integer from a to b.
The difference between those values should not be bigger than 2147483647. (32768*FRACUNIT-1)
Parameters
a, b - lowest and highest possible result
Return values
result - generated random value
This function returns a random integer from a to b.
The difference between those values should not be bigger than 2147483647. (32768*FRACUNIT-1)
Parameters
a, b - lowest and highest possible result
Return values
result - generated random value
Description
This function returns true p% of the time, where p is a number between 0 and FRACUNIT.
For example: 0 is 0%, FRACUNIT/2 is 50%, FRACUNIT is 100%.
Parameters
p - chance to return true
Return values
result - boolean (true or false)
This function returns true p% of the time, where p is a number between 0 and FRACUNIT.
For example: 0 is 0%, FRACUNIT/2 is 50%, FRACUNIT is 100%.
Parameters
p - chance to return true
Return values
result - boolean (true or false)
No screenshots are included as it's just a Lua library.
