Index · Object → RefCounted → RandomNumberGenerator

RandomNumberGenerator

Provides methods for generating pseudo-random numbers.

Class Description

RandomNumberGenerator is a class for generating pseudo-random numbers. It currently uses PCG32.

Note: The underlying algorithm is an implementation detail and should not be depended upon.

To generate a random float number (within a given range) based on a time-dependent seed:

var rng = RandomNumberGenerator.new()
func _ready():
	var my_random_number = rng.randf_range(-10.0, 10.0)

Properties

var seed: int = 0

Initializes the random number generator state based on the given seed value. A given seed will give a reproducible sequence of pseudo-random numbers.

Note: The RNG does not have an avalanche effect, and can output similar random streams given similar seeds. Consider using a hash function to improve your seed quality if they're sourced externally.

Note: The default value of this property is pseudo-random, and changes when calling randomize(). The 0 value documented here is a placeholder, and not the actual default seed.

Note: Setting this property produces a side effect of changing the internal state, so make sure to initialize the seed before modifying the state:

var rng = RandomNumberGenerator.new()
rng.seed = hash("Godot")
rng.state = 100 # Restore to some previously saved state.
var state: int = 0

The current state of the random number generator. Save and restore this property to restore the generator to a previous state:

var rng = RandomNumberGenerator.new()
print(rng.randf())
var saved_state = rng.state # Store current state.
print(rng.randf()) # Advance internal state.
rng.state = saved_state # Restore the state.
print(rng.randf()) # Prints the same value as previously.

Note: Do not set state to arbitrary values, since the random number generator requires the state to have certain qualities to behave properly. It should only be set to values that came from the state property itself. To initialize the random number generator with arbitrary input, use seed instead.

Note: The default value of this property is pseudo-random, and changes when calling randomize(). The 0 value documented here is a placeholder, and not the actual default state.

Methods

func rand_weighted(weights: PackedFloat32Array) -> int

Returns a random integer between 0 and the size of the array that is passed as a parameter. Each value in the array should be a non-negative floating-point number that represents the relative likelihood that it will be returned as an index. A higher value means the value is more likely to be returned as an index, while a value of 0 means it will never be returned as an index.

For example, if [code skip-lint][0.5, 1, 1, 2][/code] is passed as a parameter, then the method is twice as likely to return 3 (the index of the value 2) and twice as unlikely to return 0 (the index of the value 0.5) compared to the indices 1 and 2.

Prints an error and returns -1 if the array is empty or contains any negative values.

var rng = RandomNumberGenerator.new()

var my_array = ["one", "two", "three", "four"]
var weights = PackedFloat32Array([0.5, 1, 1, 2])

# Prints one of the four elements in `my_array`.
# It is more likely to print "four", and less likely to print "one".
print(my_array[rng.rand_weighted(weights)])
func randf() -> float

Returns a pseudo-random float between 0.0 and 1.0 (inclusive).

func randf_range(from: float, to: float) -> float

Returns a pseudo-random float between from and to (inclusive).

func randfn(mean: float = 0.0, deviation: float = 1.0) -> float

Returns a normally-distributed, pseudo-random floating-point number from the specified mean and a standard deviation. This is also known as a Gaussian distribution.

Note: This method uses the Box-Muller transform algorithm.

func randi() -> int

Returns a pseudo-random 32-bit unsigned integer between 0 and 4294967295 (inclusive).

func randi_range(from: int, to: int) -> int

Returns a pseudo-random 32-bit signed integer between from and to (inclusive).

func randomize() -> void

Sets up a time-based seed for this RandomNumberGenerator instance. Unlike the @GlobalScope random number generation functions, different RandomNumberGenerator instances can use different seeds.

Inherited from RefCounted (4)
func init_ref() -> bool
func reference() -> bool
func unreference() -> bool
Inherited from Object (62)
func _get(property: StringName) -> Variant
func _get_property_list() -> Dictionary[]
func _init() -> void
func _iter_get(iter: Variant) -> Variant
func _iter_init(iter: Array) -> bool
func _iter_next(iter: Array) -> bool
func _notification(what: int) -> void
func _set(property: StringName, value: Variant) -> bool
func _to_string() -> String
func _validate_property(property: Dictionary) -> void
func add_user_signal(signal: String, arguments: Array = []) -> void
func call(method: StringName) -> Variant
func callv(method: StringName, arg_array: Array) -> Variant
func cancel_free() -> void
func connect(signal: StringName, callable: Callable, flags: int = 0) -> Error
func disconnect(signal: StringName, callable: Callable) -> void
func emit_signal(signal: StringName) -> Error
func free() -> void
func get(property: StringName) -> Variant
func get_class() -> String
func get_incoming_connections() -> Dictionary[]
func get_indexed(property_path: NodePath) -> Variant
func get_meta(name: StringName, default: Variant = null) -> Variant
func get_meta_list() -> StringName[]
func get_method_list() -> Dictionary[]
func get_property_list() -> Dictionary[]
func get_signal_connection_list(signal: StringName) -> Dictionary[]
func get_signal_list() -> Dictionary[]
func has_meta(name: StringName) -> bool
func has_method(method: StringName) -> bool
func has_signal(signal: StringName) -> bool
func is_class(class: StringName) -> bool
func is_connected(signal: StringName, callable: Callable) -> bool
func notification(what: int, reversed: bool = false) -> void
func remove_meta(name: StringName) -> void
func remove_user_signal(signal: StringName) -> void
func set(property: StringName, value: Variant) -> void
func set_block_signals(enable: bool) -> void
func set_deferred(property: StringName, value: Variant) -> void
func set_indexed(property_path: NodePath, value: Variant) -> void
func set_message_translation(enable: bool) -> void
func set_meta(name: StringName, value: Variant) -> void
func set_script(script: Variant) -> void
func set_translation_domain(domain: StringName) -> void
func to_string() -> String
func tr(message: StringName, context: StringName = &"") -> String
func tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") -> String

Signals

Inherited from Object (2)