EZ RNG

EZ RNG simplifies your RNG needs by offering the following global functions via a sole, auto-loaded singleton script:

gen_int() - Generates integers in an array inclusively-between minimum and maximum values

gen_float() - Generates floats in an array inclusively-between minimum and maximum values

gen_gaussian() - Simulates a statistical normal distribution and generates numbers thereof

gen_weighted() - Uses float-based weights for generation with favorability

Badges

Installation

Install from the Godot editor's AssetLib

  1.) Click on "AssetLib" at the top-middle of the editor
  2.) Search for "EZ RNG" without double-quotes
  3.) Click on "EZ RNG"
  4.) Click "Download"
  5.) Click "Change Install Folder"
  6.) Create a "res://addons/ez_rng" folder
  7.) Click "Select Current Folder" while inside "res://addons/ez_rng"
  8.) Click "Install"
  9.) Navigate to Project -> Project Settings -> Plugins and check the "On" box 
  10.) Call the EZ RNG functions anywhere in the rest of your project's GDScript scripts via:
    10.1.) EZRNG.gen_int()
    10.2.) EZRNG.gen_float()
    10.3.) EZRNG.gen_gaussian()
    10.4.) EZRNG.gen_weighted()

Usage

EZRNG.gen_int()

  EZRNG.gen_int(count: int, min: int, max: int) -> Array[int]

  ## e.g. Generate 10 integers between 1 and 10:

  var my_int_array: Array[int] = EZRNG.gen_int(10, 1, 10)

EZRNG.gen_float()

  EZRNG.gen_float(count: int, min: float, max: float, dof: float) -> Array[float]

  ## e.g. Generate 5 floats between 1.0 and 20.0, rounded to the hundredths-place:

  var my_float_array: Array[float] = EZRNG.gen_float(5, 1.0, 20.0, 0.01)

EZRNG.gen_gaussian()

  EZRNG.gen_gaussian(count: int, avg: float, dev: float, dof: float) -> Array[float]

  ## e.g. Simulate a normal distribution with a mean of 20 and standard deviation of 2.5.
  ## Return 40 sampled values thereof, rounded to the tenths-place:

  var my_gaussian_array: Array[float] = EZRNG.gen_gaussian(40, 20.0, 2.5, 0.1)

EZRNG.gen_weighted()

  EZRNG.gen_weighted(count: int, weights: PackedFloat32Array) -> Array[int]

  ## e.g. Consider the weights [-1.0, 0.0, 0.5, 1, 2, 4]
  ## Neither -1.0 nor 0.0 will ever be chosen since they are <=0.0.
  ## 4 is the most-likely to be chosen, 0.5 is the least-likely.
  ## Return 20 index position integers based on these weights:

  var my_weights: PackedFloat32Array = [-1.0, 0.0, 0.5, 1, 2, 4]
  var my_weighted_array: Array[int] = EZRNG.gen_weighted(20, my_weights)

Usage/Examples

If working on a Pen n' Paper RPG type of application, you could roll dice:

## Roll 1d20
var d20_result: int = EZRNG.gen_int(1, 1, 20)[0]

## Roll 2d20
var d20_result: Array[int] = EZRNG.gen_int(2, 1, 20)

## Roll 1d100
var d100_result: int = EZRNG.gen_int(1, 1, 100)[0]

## Roll 2d100
var d100_result: Array[int] = EZRNG.gen_int(2, 1, 100)

## Sample advantage 1d20 roll
var adv: int = EZRNG.gen_int(2, 1, 20).max()

## Sample disadvantage 1d20 roll:
var dis: int = EZRNG.gen_int(2, 1, 20).min()

If you want to add weighting to your number generation to grant favorability:

## Specify an array of things you want to be picked with favorability
var favorite_snacks: Array[String] = ["apple", "cookie", "ice cream"]

## Specify the weights, or, favorability of these things in the same order
## e.g. I like cookies twice as much as apples, and ice cream twice as much as cookies
var snack_weights: PackedFloat32Array = [0.5, 1.0, 2.0]

## Let's say I want to buy snacks for the next two weeks, eating one per day
## This means we want 14 random values to be generated to then align with the snack indices
var weight_results: Array[int] = EZRNG.gen_weighted(14, snack_weights)

## The weight_results array will favor ice cream but still pick apples and cookies
## Now we combine the weight_results and favorite_snacks to see what to buy
var snack_purchase: Array[String] = []
for result in weight_results:
    snack_purchase.append(favorite_snacks[result])

If you need to generate numbers with decimal values you can do so specifying degrees of freedom:

## Generate a random enemy's wallet with a loot table of $3.50 to $100.00
var loot_wallet: float = EZRNG.gen_float(1, 3.5, 100.0, 0.01)[0]

## For even more precise decimal places, modify the Degrees of Freedom "dof"
var hundred_thousandth_rng: float = EZRNG.gen_float(1, 0.0, 50.0, 0.00001)[0]

## To loot the enemy's wallet above to the nearest dollar, specify 1 for "dof"
var rounded_loot_wallet: int = EZRNG.gen_float(1, 3.5, 100.0, 1)[0]

## Likewise for the nearest ten-dollars, specify 10 for "dof"
var rounded_loot_wallet: int = EZRNG.gen_float(1, 3.5, 100.0, 10)[0]

## And likewise for the nearest ten-cents, specify 0.1 for "dof"
var rounded_loot_wallet: float = EZRNG.gen_float(1, 3.5, 100.0, 0.1)[0]

If you want to generate values based on a statistical model, supply the mean and standard deviation for Box-Muller generation:

## Let's say a JRPG wants to add some dynamicism to enemy stats
## The typical same-level enemy has an average health of 1200, discrete integer values only
## The developer wants there to be a common variance (1 standard deviation, 68%) of ~200
## When generating 10 enemies in the game, lets give them some dynamic health values
var enemy_health: Array[int] = EZRNG.gen_gaussian(10, 1200.0, 200.0, 1)

## From here when constructing the enemies the developer can loop through health assignment
for enemy in enemies:
    enemy.set_health(enemy_health[enemy])

FAQ

Is this plugin truly necessary for RNG?

No, but with most RNG needs boiling down to needing X-number of generated values between minimum-Y and maximum-Z, this plugin grants quick global-level RNG availability. I've built similar standalone RNG nodes to accomplish similar, but a plugin available at the global-level, eliminating the hussle of node management thereof, makes it even quicker especially when encountering circumstances where you need to re-instantiate RandomNumberGenerator objects time-to-time at runtime. The actual line-of-code count of this plugin is 24 ignoring documentation, but if you want to modify it or make your own custom RNG functionality, I recommend reading the GDScript doc on the subject.

What if I only want to supply integers for gen_float() or gen_gaussian()?

You can supply integers without incident.

What if I only want integer results for gen_float() or gen_gaussian()?

Set your Degrees of Freedom "dof" parameter to 1.

Documentation

• RandomNumberGenerator
• Randomize()
• RandI_Range()
• RandF_Range()
• Snapped()
• RandFn()
• Rand_Weighted()

Acknowledgements

• Awesome README
• Godot Foundation
• Shields.io Badges
• Opensource.org License Templates

Authors

Tundra Peaks Studios

@aaron-tundrapeaksstudios

License

MIT