Random Generators

Random generators for Unity is a collection of random generators, different random engines, distributions, modificators and filters.

The library has a useful infrastructure that makes it easy to expand it and add new distributions, modificators, filters and random generators.

The library is very fast and heap allocation free.

Installation

This repo is a regular Unity package. You can install it as your project dependency. More here: https://docs.unity3d.com/Manual/upm-dependencies.html.

Usage

1. Create a provider from Assets/Create/Random Generator Providers/ or choose one of pre-made providers among DefaultBoolUniformGeneratorProvider, DefaultIntUniformGeneratorProvider, DefaultFloatUniformGeneratorProvider, DefaultNormalGeneratorProvider and DefaultBatesGeneratorProvider.
2. Add ContinuousGeneratorProviderReference for continuous distributions or DiscreteGeneratorProviderReference for discrete distributions as a serialize field into your component.
3. Link a selected provider into a right provider reference. Toggle on/off Shared. If Shared is on, a generator is created once and reused by all requesters. If Shared is off, a new generator is created for every requester.
4. In your script, call ContinuousGeneratorProviderReference.generator or DiscreteGeneratorProviderReference.GetGenerator() and cache the result. They return a IContinuousGenerator or IDiscreteGenerator that generate a random value.
5. Call Generate() in a gotten generator to get a random value that corresponds to a selected distribution.

Also, you can create your own infrastructure. Every part of this library is public and available separately from other parts.

Parts

Random Engines

Random engines are algorithms in structs that generate pseudo-random values.

List of random engines

• LCG32 - Wikipedia;
• LCG64 - Wikipedia;
• Xoroshiro128+ - Wikipedia;
• XorShift32 - Wikipedia;
• XorShift64 - Wikipedia;
• XorShift128 - Wikipedia.

Random Generators

Random generators use random engines (custom or pre-built in Unity) to generate pseudo-random values corresponding to a distribution. They may simply wrap random engines as well. They consist of distributions, generators and generator providers.

Distributions

Distributions are just algorithms in static classes that return a random value(s). They usually require an independent and identically distributed random generator. By default, Unity generator is used as such a generator. Also, the distributions support Func<float> and IContinuousGenerator as an iid random generator.

Generators

Generators are standard c# classes that implement IContinuousGenerator or IDiscreteGenerator and wrap one of the methods of the distributions.

Generator Providers

Generator providers are scriptable objects and can be linked to a serialize field in Unity components. They wrap generators and provide unique and shared instances of them.

List of continuous generator algorithms

• Bates - Wikipedia;
• Exponential - Wikipedia;
• Extreme Value - Wikipedia;
• Func<float> Random Generator Wrapper;
• Gamma - Wikipedia;
• Irwin-Hall - Wikipedia;
• LCG32 Random Generator Wrapper;
• LCG64 Random Generator Wrapper;
• Normal - Wikipedia;
• Rejection - Wikipedia;
• C# Random Generator Wrapper - Microsoft Docs;
• Unity Random Generator Wrapper - Unity Docs;
• Weibull - Wikipedia;
• Xoroshiro128+ Random Generator Wrapper;
• XorShift32 Random Generator Wrapper;
• XorShift64 Random Generator Wrapper;
• XorShift128 Random Generator Wrapper.

List of discrete generator algorithms

• Bernoulli - Wikipedia;
• Binomial - Wikipedia;
• Geometric - Wikipedia;
• LCG32 Random Generator Wrapper;
• LCG64 Random Generator Wrapper;
• Negative Binomial - Wikipedia;
• Poisson - Wikipedia;
• C# Random Generator Wrapper - Microsoft Docs;
• Unity Random Generator Wrapper - Unity Docs;
• Weighted - distribution where every value has a weight and its probability is a ratio of its weight to a sum of all weights;
• Xoroshiro128+ Random Generator Wrapper;
• XorShift32 Random Generator Wrapper;
• XorShift64 Random Generator Wrapper;
• XorShift128 Random Generator Wrapper.

Random modificators

There are different modificators in this library. They modify results of generators and mimic them. Modificators has providers as random generators.

Modificators

Modificators are standard c# classes that implement IContinuousGenerator or IDiscreteGenerator but they are not actually generators, they take a generated value from a depended generator, modify it somehow and return a result.

Modificator Providers

Modificator providers are scriptable objects and can be linked to a serialize field in Unity components. They wrap modificators and provide unique and shared instances of them.

List of continuous modificators

• Add - sums a generated value and a multiplier and returns the result;
• Clamp - clamps a generated value between specified minimum and maximum values;
• Multiply - multiplies a generated value and an item and returns the result;
• Round - rounds a generated value to a nearest integer.

List of discrete modificators

• Add - sums a generated value and a multiplier and returns the result;
• Clamp - clamps a generated value between specified minimum and maximum values;
• Round to Int - rounds a generated value to a nearest integer.

Random filters

For usual people random values may look like non-random. Because of that we need to filter results of random generators and regenerate them if a filter forbids a new value.

Filters

Filters are algorithms in static classes that check if a new generated value corresponds to their rules. They usually forbid certain sequences of random generated values.

Filter Wrappers

Filter wrappers are standard c# classes that implement IContinuousFilter or IDiscreteFilter and wrap one of the methods of filters.

Filter Providers

Filter providers are scriptable objects and can be linked to a serialize field in Unity components. They wrap filter wrappers and provide unique and shared instances of them.

Filtered Generators

Filtered generators are standard c# classes that implement IContinuousFilter or IDiscreteFilter. They take a generated value from a depended generator and check that value with filters. If at least one filter doesn't approve a new value, it's regenerated and checked again.

Filtered Generator Providers

Filtered generator providers are scriptable objects and can be linked to a serialize field in Unity components. They wrap filtered generators and provide unique and shared instances of them.

List of continuous filters

• Ascendant Sequence - checks if a value continues an ascendant sequence and it needs to be regenerated;
• Close - checks if a value continues a sequence where every value is close enough to a reference value and needs to be regenerated;
• Descendant Sequence - checks if a value continues a descendant sequence and it needs to be regenerated;
• Greater - checks if a value continues a sequence where every value is greater than a reference value and needs to be regenerated;
• In Range - checks if a value continues a sequence where every value is in range between the minimum and maximum and needs to be regenerated;
• Less - checks if a value continues a sequence where every value is less than a reference value and needs to be regenerated;
• Little Difference - checks if a value continues a sequence where consecutive elements differ by less than a required difference and needs to be regenerated;
• Not In Range - checks if a value continues a sequence where every value is in range between the minimum and maximum and needs to be regenerated.

List of discrete filters

• Ascendant Sequence - checks if a value continues an ascendant sequence and it needs to be regenerated;
• Close - checks if a value continues a sequence where every value is close enough to a reference value and needs to be regenerated;
• Descendant Sequence - checks if a value continues a descendant sequence and it needs to be regenerated;
• Frequent Value - checks if a value is contained in a sequence more than allowed times and needs to be regenerated;
• Opposite Pattern - checks if a value forms a pattern opposite to a previous pattern and needs to be regenerated;
• Pair - Checks if a value is contained in a sequence some elements before and needs to be regenerated;
• Repeating Pattern - checks if a new value forms a pattern the same to a pattern some elements before and needs to be regenerated;
• Same Pattern - checks if a value forms the same pattern in a sequence as a pattern before and needs to be regenerated;
• Same Sequence - checks if a value continues a sequence where every value is the same and needs to be regenerated.

References

References are serializable structs that wrap an access to unique and shared generators or filters from their providers. All the references require a link to a provider. Also, they have a toggle Shared. If it's on, a reference returns a shared generator or filter. If it's off, a reference returns a unique generator or filter.

List of references

• Continuous Generator Provider Reference;
• Discrete Generator Provider Reference;
• Continuous Filter Provider Reference;
• Discrete Filter Provider Reference.

Property drawers

• Require Discrete Generator - doesn't allow to set a generator with a wrong type into Discrete Generator Provider Reference;
• Require Discrete Filter - doesn't allow to set a filter with a wrong type into Discrete Filter Provider Reference.

Distribution Tests

In Window/Random Generators/ there are different distribution tests where you can test any distribution asset and see probabilities of its values.