godot-seeded-random-sequence

Seeded RNG Sequence

This module/class acts as RNG sequence that manages it's own state outside of the Godot Random Number Generator (RNG). This allows you to have unique RNG sequences that are not affected by one another, and can even reset/remember previous values.

This is useful for procedural generation, as the RNG can easily be interrupted by other nodes in your project. You can provide a seed directly, or allow the RNG to give a seed.

Installation and usage

Installing this module is very simple - just add it to your project and reference it in your scripts.

For Example:

/godot/project
   ├── lib
   |   └── SeededRandomSequence.gd
   └── objects
       └── MyObjectController.gd

You can save the state of the SRS by calling .save_state(), which will return the JSON string that represents the RNG. You can restore this state by calling .load_state(json) with the JSON string. This will use the initial seed to simulate the RNG until it returns to the state described in the JSON. This is useful for recovering the RNG across sessions, for example a save game or a replay system. Be warned, if you feed it bad data, it could lock up 'indefinitely' as it tries to find the matching state value. Since the state is stored internally as a 64bit integer, it could search for a long time before it hits the desired state.

After loading the state, you can then proceed to use it like normal, getting the next number with .next()

MyObjectController.gd

...
#Import the class module
const SeededRandomSequence = preload("res://lib/SeededRandomSequence.gd")

#Variables for the seed and RNG
export(String) var seed = 0
var _rng

func _ready():
  #Create the RNG
  _rng = SeededRandomSequence.new(seed)
  
  #Get the next number in the sequence
  var my_new_int = _rng.next()
  print("Got Number: ", my_new_int)

As a Singleton

There is a simple Singleton script included in this package, called SeededRandomSingleton. This Singleton simply creates and initializes a SeededRandomSequence object. You can add this Singleton to your project via:

Project
 └── Project Settings
     └── AutoLoad

and selecting the SeededRandomSingleton.gd script. Assuming you named the Autoload SeededRandomSingleton then you can simply access it in your scripts like:

SeededRandomSingleton.sequence.reset(new_seed) #Optional, if you want to control the seed
var value = SeededRandomSingleton.sequence.next() #Grab the next value
print(value) #Print out the value

It's a very easy way to take advantage of the sequence without needing to pass around an object.

Example Project

There is a provided Example Project in the repo. You can load it in Godot to see a simple GUI that allows you to set the seed, get the values, watch the state, and even save/load the JSON to show that it works! The example is shown in the /lib/example/ folder.