Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

RandomNumberGenerator

继承： RefCounted < Object

提供生成伪随机数的方法。

描述

RandomNumberGenerator 是一个用于生成伪随机数的类。它目前使用 PCG32。

注意：底层算法属于实现细节，不应该对此产生依赖。

要根据时间相关种子生成（给定范围内的）随机浮点数：

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

教程

属性

int

seed

0

int

state

0

方法

int

rand_weighted(weights: PackedFloat32Array)

float

randf()

float

randf_range(from: float, to: float)

float

randfn(mean: float = 0.0, deviation: float = 1.0)

int

randi()

int

randi_range(from: int, to: int)

void

randomize()

属性说明

int seed = 0 🔗

  • void set_seed(value: int)

  • int get_seed()

根据给定的种子值来初始化随机数生成器的状态。使用相同的种子，将会生成一组完全可复现的伪随机数序列。

注意： 该随机数生成器（RNG）不具备雪崩效应，这意味着如果使用相近的种子值，可能会输出相似的随机数序列。如果你的种子是从外部获取的，建议考虑使用哈希函数来提升种子的质量。

注意： 该属性的默认值其实是伪随机的，并且会在调用 randomize() 方法时发生改变。这里文档中标注的默认值 0 仅仅是一个占位符，并不是它实际的默认种子。

注意： 设置该属性会产生一个副作用，即改变内部的 state（状态）。因此，请务必在修改 state 之前 先初始化种子：

var rng = RandomNumberGenerator.new()
rng.seed = hash("Godot")
rng.state = 100 # 恢复到之前保存的某个状态。

int state = 0 🔗

  • void set_state(value: int)

  • int get_state()

随机数生成器的当前状态。保存并恢复此属性，以将生成器恢复到之前的状态：

var rng = RandomNumberGenerator.new()
print(rng.randf())
var saved_state = rng.state # 保存当前状态。
print(rng.randf()) # 让内部状态发生步进。
rng.state = saved_state # 恢复状态。
print(rng.randf()) # 输出和之前一样的值。

注意：不要将状态设置为任意值，因为随机数生成器要求状态具有某些特性才能正常运行。它应该只设置为来自状态属性本身的值。要使用任意输入初始化随机数生成器，请改用 seed。

注意：该属性的默认值是伪随机的，会在调用 randomize() 时改变。文档中记录的 0 是占位符，不是实际的默认状态。

方法说明

int rand_weighted(weights: PackedFloat32Array) 🔗

返回一个介于 0 和作为参数传入的数组大小之间的随机整数。数组中的每个值都应该是一个浮点数，代表其作为索引被返回的相对概率。值越高，该索引被返回的可能性就越大；而值为 0 则意味着该索引永远不会被返回。

例如，如果传入参数 [0.5, 1, 1, 2]，那么该方法返回 3（值 2 的索引）的概率是返回索引 1 和 2 的两倍，而返回 0（值 0.5 的索引）的概率则只有它们的一半。

如果数组为空，则打印错误信息并返回 -1。

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)])

float randf() 🔗

返回在 0.0 和 1.0 之间（含端点）的伪随机浮点数。

float randf_range(from: float, to: float) 🔗

返回在 from 和 to 之间（含端点）的伪随机浮点数。

float randfn(mean: float = 0.0, deviation: float = 1.0) 🔗

返回一个正态分布的伪随机数，该分布使用指定的 mean 和标准 deviation。这也被称为高斯分布。

注意：该方法使用 Box-Muller 变换算法。

int randi() 🔗

返回在 0 和 4294967295 之间（含端点）的伪随机 32 位无符号整数。

int randi_range(from: int, to: int) 🔗

返回在 from 和 to 之间（含端点）的伪随机 32 位无符号整数。

void randomize() 🔗

为这个 RandomNumberGenerator 实例设置基于时间的种子。与 @GlobalScope 随机数生成函数不同，不同的 RandomNumberGenerator 实例可以使用不同的种子。