From 47899e67c53ce3f74767aa5ad9d01a5a261486c6 Mon Sep 17 00:00:00 2001 From: "Andrii Doroshenko (Xrayez)" Date: Fri, 8 Jan 2021 15:02:02 +0200 Subject: [PATCH] Add ability to restore `RandomNumberGenerator` state 3.2 version of b5107715f19ec122b7ee1a61831291dc0f1d5df0. `get_seed()` still returns the previous state and not the initial seed, because users may rely on this behavior for resetting the state in 3.2. Documented this is going to be fixed in 4.0. Co-authored-by: MidZik --- core/math/random_number_generator.cpp | 7 ++++++- core/math/random_number_generator.h | 4 ++++ core/math/random_pcg.h | 5 ++++- doc/classes/RandomNumberGenerator.xml | 23 +++++++++++++++++++++-- 4 files changed, 35 insertions(+), 4 deletions(-) diff --git a/core/math/random_number_generator.cpp b/core/math/random_number_generator.cpp index c6d8acf7daf..a208e3a676f 100644 --- a/core/math/random_number_generator.cpp +++ b/core/math/random_number_generator.cpp @@ -36,6 +36,9 @@ void RandomNumberGenerator::_bind_methods() { ClassDB::bind_method(D_METHOD("set_seed", "seed"), &RandomNumberGenerator::set_seed); ClassDB::bind_method(D_METHOD("get_seed"), &RandomNumberGenerator::get_seed); + ClassDB::bind_method(D_METHOD("set_state", "state"), &RandomNumberGenerator::set_state); + ClassDB::bind_method(D_METHOD("get_state"), &RandomNumberGenerator::get_state); + ClassDB::bind_method(D_METHOD("randi"), &RandomNumberGenerator::randi); ClassDB::bind_method(D_METHOD("randf"), &RandomNumberGenerator::randf); ClassDB::bind_method(D_METHOD("randfn", "mean", "deviation"), &RandomNumberGenerator::randfn, DEFVAL(0.0), DEFVAL(1.0)); @@ -44,6 +47,8 @@ void RandomNumberGenerator::_bind_methods() { ClassDB::bind_method(D_METHOD("randomize"), &RandomNumberGenerator::randomize); ADD_PROPERTY(PropertyInfo(Variant::INT, "seed"), "set_seed", "get_seed"); - // Default value is non-deterministic, override it for doc generation purposes. + ADD_PROPERTY(PropertyInfo(Variant::INT, "state"), "set_state", "get_state"); + // Default values are non-deterministic, override for doc generation purposes. ADD_PROPERTY_DEFAULT("seed", 0); + ADD_PROPERTY_DEFAULT("state", 0); } diff --git a/core/math/random_number_generator.h b/core/math/random_number_generator.h index 4a12f553b89..b15e4d6134b 100644 --- a/core/math/random_number_generator.h +++ b/core/math/random_number_generator.h @@ -47,6 +47,10 @@ public: _FORCE_INLINE_ uint64_t get_seed() { return randbase.get_seed(); } + _FORCE_INLINE_ void set_state(uint64_t p_state) { randbase.set_state(p_state); } + + _FORCE_INLINE_ uint64_t get_state() const { return randbase.get_state(); } + _FORCE_INLINE_ void randomize() { randbase.randomize(); } _FORCE_INLINE_ uint32_t randi() { return randbase.rand(); } diff --git a/core/math/random_pcg.h b/core/math/random_pcg.h index 6402ebd5546..5640c2ca19b 100644 --- a/core/math/random_pcg.h +++ b/core/math/random_pcg.h @@ -61,7 +61,7 @@ static int __bsr_clz32(uint32_t x) { class RandomPCG { pcg32_random_t pcg; - uint64_t current_seed; // seed with this to get the same state + uint64_t current_seed; // The seed the current generator state started from. uint64_t current_inc; public: @@ -76,6 +76,9 @@ public: } _FORCE_INLINE_ uint64_t get_seed() { return current_seed; } + _FORCE_INLINE_ void set_state(uint64_t p_state) { pcg.state = p_state; } + _FORCE_INLINE_ uint64_t get_state() const { return pcg.state; } + void randomize(); _FORCE_INLINE_ uint32_t rand() { current_seed = pcg.state; diff --git a/doc/classes/RandomNumberGenerator.xml b/doc/classes/RandomNumberGenerator.xml index 49104e0e543..315e7f85551 100644 --- a/doc/classes/RandomNumberGenerator.xml +++ b/doc/classes/RandomNumberGenerator.xml @@ -13,6 +13,7 @@ rng.randomize() var my_random_number = rng.randf_range(-10.0, 10.0) [/codeblock] + [b]Note:[/b] The default values of [member seed] and [member state] properties are pseudo-random, and changes when calling [method randomize]. The [code]0[/code] value documented here is a placeholder, and not the actual default seed. @@ -74,9 +75,27 @@ - The seed used by the random number generator. A given seed will give a reproducible sequence of pseudo-random numbers. + Initializes the random number generator state based on the given seed value. A given seed will give a reproducible sequence of pseudo-random numbers. [b]Note:[/b] 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. - [b]Note:[/b] The default value of this property is pseudo-random, and changes when calling [method randomize]. The [code]0[/code] value documented here is a placeholder, and not the actual default seed. + [b]Note:[/b] Setting this property produces a side effect of changing the internal [member state], so make sure to initialize the seed [i]before[/i] modifying the [member state]: + [codeblock] + var rng = RandomNumberGenerator.new() + rng.seed = hash("Godot") + rng.state = 100 # Restore to some previously saved state. + [/codeblock] + [b]Warning:[/b] the getter of this property returns the previous [member state], and not the initial seed value, which is going to be fixed in Godot 4.0. + + + The current state of the random number generator. Save and restore this property to restore the generator to a previous state: + [codeblock] + 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 in previous. + [/codeblock] + [b]Note:[/b] 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 [member seed] instead.