Random

The Random data type generates pseudorandom numbers and directions.

Constructors

Name	Type / Returns	Description
Random.new		Returns a new pseudorandom generator using an optional seed.

Random.new

Returns a new Random object. If you don't provide the seed parameter, Random uses a seed from an internal entropy source.

If you provide a seed, it should be within the range [-9007199254740991, 9007199254740991], and Random will round it down to the nearest integer. So seeds of 0, 0.99, and math.random() all produce identical generators. If you need to generate a seed and store it for later retrieval, use math.random(max).

Parameters

Name	Type	Default	Description
seed	number		An optional number that initializes the pseudorandom number generator's internal state, truncated toward zero to a whole number. Should be within the range [-9007199254740991, 9007199254740991]; values outside this range are clamped to 0.

Code samples: View on Creator Hub (generating-random-seed).

Methods

Name	Type / Returns	Description
Random:NextInteger	number	Returns a pseudorandom integer uniformly distributed over `[min, max]`.
Random:NextNumber	number	Returns a pseudorandom number uniformly distributed over `[0, 1]`.
Random:NextNumber	number	Returns a pseudorandom number uniformly distributed over `[min, max]`.
Random:Shuffle	()	Uniformly shuffles a table in-place.
Random:NextUnitVector	Vector3	Returns a unit vector with a pseudorandom direction.
Random:Clone	Random	Returns a new Random object with the same state as the original.

Random:NextInteger

Returns a pseudorandom integer uniformly distributed over [min, max], inclusive of both endpoints. If min is greater than max, the two values are swapped so the call still succeeds. Both arguments are truncated toward zero to whole numbers before sampling.

Parameters

Name	Type	Default	Description
min	number		The minimum integer value of the range (inclusive). Truncated toward zero to a whole number.
max	number		The maximum integer value of the range (inclusive). Truncated toward zero to a whole number.

Returns

Type	Description
number

Random:NextNumber

Returns a uniform pseudorandom real number in the range of 0 to 1, inclusive.

Returns

Type	Description
number	A pseudorandom number uniformly distributed over [0, 1].

Random:NextNumber

Returns a uniform pseudorandom real number in the range of min to max, inclusive.

Parameters

Name	Type	Default	Description
min	number		The minimum value of the range (inclusive).
max	number		The maximum value of the range (inclusive).

Returns

Type	Description
number	A pseudorandom number uniformly distributed over [min, max].

Random:Shuffle

Uniformly shuffles the array part of tb in-place using NextInteger to pick indices. If there are any nil "holes" in the array part of the table, Shuffle throws an error, since shuffling could change the length.

The hash part of tb is ignored. No metamethods of tb are invoked.

The shuffle is defined to be a Fisher-Yates shuffle so the number of NextInteger calls is guaranteed to be consistent between engine versions for a given size of table.

Parameters

Name	Type	Default	Description
tb	table		The table whose array part is shuffled in-place.

Returns

Type	Description
()

Random:NextUnitVector

Returns a unit vector with a pseudorandom direction. Vectors returned from this function are uniformly distributed over the unit sphere.

Returns

Type	Description
Vector3	A unit vector with a pseudorandom direction.

Random:Clone

Returns a new Random object whose internal state is copied from the original. After cloning, both the original and the clone produce the same sequence of pseudorandom values going forward, but they advance independently — consuming a value from one does not affect the other.

Returns

Type	Description
Random	A new Random object with the same internal state as the original.