Make It Random User's Manual

Introduction |

Welcome to the Make It Random User's Manual. This document will assist in integrating this collection of random number generation utilities into your Unity project.

This topic contains the following sections:

What does Make It Random offer?

Make It Random is a fast, flexible, extensible, and feature rich random number generation library for Unity. It provides classes and functions, accessible from scripts, for generating random data of various sorts, including:

- bits
- integers
- floating point numbers
- angles
- vectors and quaternions
- strings
- dice rolls
- colors (includes the full Make It Colorful library!)

In addition to simply generating random data, it also includes utilities for the following (with support for non-uniform weights, where applicable):

- evaluating probabilities
- sampling from distributions
- selecting elements from a list
- selecting values from an enumeration
- selecting values from the set {-1, 0, +1}
- shuffling a list

Note |
---|

A basic version of Make It Random is available if you only need the core generation features. Documentation can be found online here, and the library can be acquired on the Unity Asset Store. |

How is Make It Random organized?

The foundation of Make It Random is the concept of a Random Engine, an object providing the basic services of a pseudo-random number generator (PRGN), responsible for generating a deterministic sequence of seemingly random bits initialized by a seed value. Unlike UnityEngineRandom, Make It Random engines are standard non-static classes which can be passed around, copied, and serialized. Multiple instances can exist simultaneously and independently, making it easier to control deterministic behavior when it is needed. (A static global instance does exist for convenience, however.)

On top of random engines, a wide variety of extension methods are available for using the random bits they generate to produce all of the more structured and complex data typically required by games. Because they are extension methods which apply to the Experilous.MakeItRandomIRandom interface which all Make It Random engines implement, it is easy to add further extension methods that will immediately become usable by any random engine type. Similarly, if for some reason none of the random engines supplied by Make It Random are suitable and you need to create your own, just make sure it implements IRandom and your new engine will automatically support all of the already existing utilities. (See Making Your Own Random Engine for more information.)

Note |
---|

The Make It Random library is located within the Experilous.MakeItRandom namespace. Be sure to put the appropriate using directive at the top of your scripts, or explicitly qualify type names within your code. |

Using Make It Random

The first step in using Make It Random is to pull in the namespace Experilous.MakeItRandom near the top of any script file in which you plan to use it. Without doing so, none of the extension functions for IRandom will not be available, making usage syntax far more verbose.

Pulling in the Make It Random namespace.

`using Experilous.MakeItRandom;`

The next step is to create an instance of a random engine, probably within an Awake() or Start() function. The easiest way to do that is by using MIRandom.CreateStandard(). This selects a random engine type that is suitable for general use and constructs an instance of that type. If you pass no parameters, the engine will be set to a reasonably unpredictable state. You may instead pass a seed, such as an int or a string, to generate the same sequence each time the program is executed.

Creating a standard random engine instance.

// Create a random engine with an unpredictable state. var random = MIRandom.CreateStandard();

If you know which random engine type you wish to use (XorShift128Plus is a good choice for most circumstances), then you may use a Create() function on that type to do so, just as with MIRandom.CreateStandard().

Creating an explicitly typed random engine instance.

// Create a random engine, initializing its state with a string seed. var random = XorShift128Plus.Create("My random seed!!1!11!~!");

Using that created instance, you can now call any of the numerous extension methods, depending on your needs. Here are some examples:

Make It Random Usage Examples

// Generate an integer where 1 <= n <= 10 int num1to10 = random.RangeCC(1, 10); // Generate a number where 0 <= n < 1 float num0to1 = random.FloatCO(); // Flip a coin bool heads = random.Chance(); // Check a 3 in 10 probability bool criticalHit = random.Probability(3, 10); // Generate a random height for a male character in cm float height = random.NormalSample(176f, 8f); // Generate an angle in degrees where -90 < n < +90 float angleNeg90toPos90 = random.SignedHalfAngleDegOO(); // Generate +1, -1, or 0 where +1 is twice as likely as -1, and 0 is rare int numPNZ = random.SignOrZero(200, 100, 1); // Roll 43 20-sided dice int[] diceRolls = random.RollDice(43, 20); // Roll 5 4-sided dice and just keep the sum int diceRollSum = random.SumRollDice(5, 4); // Shuffle the array of earlier dice rolls random.Shuffle(diceRolls); // Select a random die roll from the array int dieRoll = random.Element(diceRolls); // Select index where higher die rolls are more likely to be picked int dieRollIndex = random.WeightedIndex(diceRolls); // Generate a random 3D unit vector Vector3 direction = random.UnitVector3(); // Generate a position within a cirle of radius = 5 Vector2 point = random.PointWithinCircle(5f); // Generate a 32-character string with only alpha-numeric characters. string str = random.AlphaNumericString(32); // Make a generator which will produce random font styles. var fontStyleGen = random.MakeEnumGenerator<UnityEngine.FontStyles>(); // Generate a font style var style = fontStyleGen.Next(); // Pick a random warm color var color = random.ColorWarm(); // Alter the color's hue randomly by no more than 1/10. color = random.HueShift((ColorHSV)color, 0.1f);

See Also