Rnd

rnd( [limit or table] )

Generates a random number under the given limit, or returns a random element from a sequence.

limit or table

Either the limit, non-inclusive, or a table. Defaults to a limit of 1.0.

The rnd() function returns a random number in a range. The result ranges from 0.0 up the given limit, but will never be the limit value itself. For instance, rnd(10) can return from 0.0 up to 9.99999, but will never return 10.

The random number includes a fractional part. To get a random integer, use flr(rnd(...)).

If a sequence-style table is passed instead of a numerical limit, the rnd() function will return a random element from the sequence.

If no limit or table is supplied, it will default to a limit of 1.0. Values returned will range from 0.0 up to 0.99999 (0x0.ffff).

The random number generator is initialized with an unpredictable seed value when PICO-8 starts. The generator may be initialized with an explicit seed using srand(), which permits a program to execute multiple times and always receive the same sequence of random numbers.

Working with ranges that don't start at 0

To select a random number between a minimum and a maximum, call rnd() with the size of the range, then add the minimum:

scale    = rnd(20) - 10     -- a random number between -10 and 10
bomb.x   = 32 + rnd(64)     -- a random number between 32 and 96
die_roll = flr(rnd(6)) + 1  -- a random integer between 1 and 6

To select a random fraction with a fixed number of decimal digits, multiply the range by the number of values between whole numbers (e.g. 100 for two decimal digits), and then divide the result by the same amount:

earnings = flr(rnd(50 * 100)) / 100  -- between 0.00 and 50.00

Undocumented range

Undocumented feature

This article describes a feature that is not mentioned in the official Pico-8 documentation. The feature was known to work at the time the article was written, but it may be removed or changed in a future version.

When it is numerical, rnd() appears to treat the limit value as if it were unsigned. For instance, calling rnd(-1) causes the randomizer to act internally as if the call had been rnd(65535). The random number is generated in this unsigned range. Therefore, since values 32768..65535 in unsigned format represent -32768..-1 in signed format, it should be expected that some return values will be negative in this case.

This extra range is not normally useful, but a limit value of 0xffff.ffff will produce almost a full 32 bits of randomness in a single call to rnd(), distributed across both the integer and fractional bits. However, because rnd() never returns the actual limit value, it's only possible to get results from 0x0000.0000 to 0xffff.fffe.

If true 32-bit randomness is needed, it may be obtained by calling rnd() twice and combining the two results:

function rnd32()
  return rnd() << 16 | rnd()
end

Examples

print(rnd(20))       -- for example, 3.837

print(flr(rnd(20)))  -- for example, 17

-- note this is the same as rnd(0xffff)
print(rnd(-1))       -- for example, -1734.56 or 13744.63

print(rnd(split("hello",""))) -- h, e, o have 20% probability, l has 40% probability

print(rnd({5,6,7,8,21,10,31,256})) -- returns a random value from the table between table[1] and table[#table]

See also

• Math
• srand()