Random

Inherits: RandomNumberGenerator < Reference < Object

Inherited By: Random2D

An instance of RandomNumberGenerator available at @GlobalScope.

Description

This is a singleton which allows to use RandomNumberGenerator methods without instantiating a dedicated object. This means that Random can be used via script with methods such as @GDScript.randi:

Random.randomize() # Time-based.
Random.seed = hash("Goost") # Manual.
var i = Random.randi() % 100
var f = Random.randf_range(-1.0, 1.0)

The class provides other useful convenience methods and properties other than what RandomNumberGenerator already provides out of the box.

Local instances must be created with new_instance method. It’s not possible to instantiate a new Random instance with Random.new() in GDScript. Alternatively, a new instance can be created with ClassDB.instance("Random"), see ClassDB.instance.

You have to call RandomNumberGenerator.randomize for local instances manually if you want to have non-reproducible results, else done automatically for the global instance by default.

For 2D, use Random2D class, which inherits all the functionality behind Random as well.

Properties

Color color Color( 0, 0, 1, 1 )
bool condition true
int number 37
float value 0.5

Methods

Array choices ( Variant sequence, int count=1, PoolIntArray weights=null, bool cumulative=false )
Color color_hsv ( float hue_min=0.0, float hue_max=1.0, float saturation_min=0.0, float saturation_max=1.0, float value_min=0.0, float value_max=1.0, float alpha_min=1.0, float alpha_max=1.0 )
Color color_rgb ( float red_min=0.0, float red_max=1.0, float green_min=0.0, float green_max=1.0, float blue_min=0.0, float blue_max=1.0, float alpha_min=1.0, float alpha_max=1.0 )
bool decision ( float probability )
Reference new_instance ( ) const
Variant pick ( Variant sequence )
Variant pop ( Variant sequence )
Variant range ( Variant from, Variant to )
void shuffle ( Array array )

Property Descriptions

Default Color( 0, 0, 1, 1 )
Getter get_color()

The next random color in HSV color space. Saturated, bright colors are preferred. Equivalent to the following code:

var color = Color.from_hsv(randf(), rand_range(0.5, 1.0), rand_range(0.5, 1.0))

For more options, use color_hsv or color_rgb.

Default true
Getter get_condition()

Generates a random boolean value. Useful for randomizing true and false states, conditions, decisions etc. The outcome is equal for both values.

if Random.condition:
    pass

Equivalent to the following code:

if randf() >= 0.5:
    pass
Default 37
Getter get_number()

Generates a random unsigned 32-bit integer. Equivalent to RandomNumberGenerator.randi.

Default 0.5
Getter get_value()

Generates a random real number in the range of 0.0..1.0. Equivalent to RandomNumberGenerator.randf.

Method Descriptions

Returns an Array of randomly picked elements from a sequence, with the number of elements equal to count. The elements are picked according to integer weights or an array of values from the sequence if it’s a Dictionary and if weights is empty.

All elements of weights must be non-negative integers, and must contain at least one non-zero element if weights is not empty. Additionally, the order of integers should be non-decreasing if cumulative is true.

If weights is not empty and if sequence is not a Dictionary, then the size of weights must be equal to the size of sequence.

Generates a random Color specified in HSV color model. See also Color.from_hsv. By default, equivalent to the following code:

var color = Color.from_hsv(randf(), randf(), randf())

If you want to generate colors which are not too pale and not too dark, use color.

Generates a random Color specified in RGB color model. By default, equivalent to the following code:

var color = Color(randf(), randf(), randf())

If you want to generate colors which are not too pale and not too dark, use color.

Returns a boolean based on a given probability value in the range of 0.0..1.0. The higher the probability value the higher the chance of this returning true.

Instantiates a new local Random instance based on RandomNumberGenerator. Does not override the Random instance accessible at @GlobalScope.

Returns a random element from a container or indexable sequence, such as Array, Dictionary, String. If container is empty, prints an error and returns null.

Returns a random element from an Array or Dictionary, and then removes the value from it. If container is empty, prints an error and returns null.

For performance reasons, this will modify the original order in the Array: the last value is swapped with the popped element, and then Array.pop_back is called. See Array.remove for explanations.

Unlike pick, the String and Pool*Array types are not supported, since they are passed by value when calling this function.

Generates a singular value in a specified range depending on the type of Variant. The types of from and to must be the same.

For integer and float values, generates a random number in the range equivalently to RandomNumberGenerator.randi_range and RandomNumberGenerator.randf_range respectively.

For any other type, the value is linearly interpolated with a random weight of 0.0..1.0.

  • void shuffle ( Array array )

Shuffles the array such that the items will have a random order. By default, this method uses the global random number generator in Random singletons, but unlike in Array.shuffle, local instances of Random can be created with new_instance to achieve reproducible results given the same seed.