# Random Selector Documentation

- Link: https://saguiitay.com/documentations/random-selector-documentation/
- Published: 2025-10-12T17:18:34+03:00
- Author: Itay

Random Selector is a utility package, that provides an efficient, weight-based, 
random selector. The selector can be used to randomly spawn enemies, generate loot,
etc. while being extremely efficient and fast.

The package includes advanced builder pattern APIs and preset configurations to 
make creating complex probability distributions easier and more intuitive.

## Features

Random Selector includes the following features:

 * **Weighted randomness** based on .Net’s Random class, Unity’s Random class, a
   thread-safe .Net Random variant, or any user-provided random number generator(
   such as a web-based generator)
 * **Builder Pattern API** for fluent, chainable configuration of complex probability
   distributions
 * **Extension Methods** for seamless integration between selectors and builders,
   enabling easy transformation and combination of existing selectors
 * **Preset Configurations** for common distribution patterns (uniform, exponential,
   linear decay, normal, tiered rarity, Pareto, etc.)
 * **Statistics and Analytics** system for tracking selection patterns, analyzing
   distributions, and debugging probability issues
 * **Unity Editor Tools** including Distribution Tester and Performance Profiler
   for comprehensive testing and optimization
 * Supports multiple usage scenarios, including:
    - Editor-only
    - Code-only
    - Multi-level selections
    - Builder pattern with method chaining
    - Real-time statistics tracking
 * Fully documented code base in C#
 * Advanced probability manipulation methods (scaling, normalization, conditional
   adding)
 * Performance profiling and memory usage analysis capabilities

# Code base

The main class of the package is “RandomSelectorScript”. It provides a simple mechanism
to select random items from a provided list of items. The class can optionally be
provided an “IRandom” implementation, for greater control. Internally, the class
implements the Alias Method algorithm – this results in an O(N²) one-time preparation,
and then on O(1) complexity for random items selection.

The package includes several additional core classes:

 * **WeightedSelectorBuilder** – A fluent API builder for constructing complex probability
   distributions with method chaining
 * **WeightedSelectorPresets** – Static factory methods for creating common weighted
   selection patterns
 * **RandomSelectorExtensions** – Extension methods for seamless integration between
   selectors and builders
 * **SelectionStatistics** – Data structure for tracking selection patterns and 
   frequencies
 * **SelectionAnalytics** – Real-time analytics system for monitoring selection 
   behavior
 * **SelectionAnalyticsUtility** – Utility class for easy integration of analytics
   tracking

The package provides 3 implementations for the IRandom interface:

 * **SystemRandom** – IRandom implementation for the System.Random class
 * **ThreadSafeRandom** – IRandom implementation for a thread-safe, thread-random,
   System.Random class
 * **UnityEngineRandom** – IRandom implementation for the UnityEngine.Random class

# Using the RandomSelectorScript

The RandomSelectorScript can be used in multiple ways.

## Unity Editor Only

As can be seen in the sample **SpawnItemScript** script and the sample **EditorSample**
scene, the package can be used in an Editor-Only mode. In this mode, a MonoBehaviour
implementation that contains an instance of **RandomSelectorScript** is used. The
list of items, and their probabilities is filled from the Unity Editor.

A **Spawn** method can be used to select a random item, and a Unity Event can be
used to respond to the item selection, as seen in the **SetSelectedItemTextScript**
script.

## Code Only

As an alternative, a code-only mode can be used to have more control, as seen in
the sample **SpawnItemByCodeScript** script and the sample **CodeSample** scene.
In this mode, an instance of **RandomSelectorScript** is created and populated with
items via code. A **Spawn** method can again be used to select a random item, and
respond to the selection.

## Multi-Level selection

For a multi-level random selection can be achieved by nesting multiple **RandomSelectorScript**
levels. As seen in the sample **GetLootScript** script and the sample **LootSample**
scene, a **RandomSelectorScript** instance is used to select sub-**RandomSelectorScript**
instances. In the sample, we used the main **RandomSelectorScript** instance for
the rarity of the loot cards (common, rare or legendary) with different probabilities.
Once the rarity is selected, a sub-**RandomSelectorScript** instance is used to 
select specific cards with different probabilities (e.g. Swordman, Spearman, etc.).

# Editor Tools

Random Selector includes powerful Unity Editor tools to help you test, debug, and
profile your weighted selection systems during development.

## Distribution Tester

The **Distribution Tester** is accessed via `Tools > Random Selector > Distribution
Tester` and provides comprehensive testing of your probability distributions.

### Key Features

 * **Visual Distribution Testing**: Create test configurations with weighted items
   and run thousands of selections to verify your probability distributions
 * **Real-Time Results Visualization**: See selection results in both chart and 
   table formats with color-coded items
 * **Deviation Analysis**: Compare actual selection frequencies against expected
   probabilities with deviation indicators
 * **Multiple Random Providers**: Test with UnityEngine.Random, System.Random (with
   seeds), or any custom IRandom implementation
 * **Export Capabilities**: Export test results to CSV files or Unity’s debug log
   for further analysis

### Using the Distribution Tester

 1. **Configure Test Items**: Add items with their respective weights and assign colors
    for visualization
 2. **Set Test Parameters**: Choose number of test selections (100 to 100,000) and 
    random provider
 3. **Run Tests**: Execute distribution tests and analyze results in real-time
 4. **Analyze Deviations**: Review actual vs expected percentages with color-coded 
    deviation indicators
 5. **Export Results**: Save detailed results for documentation or further analysis

### Example Workflow

    ```notranslate
    // The Distribution Tester helps verify configurations like:
    var lootSelector = new WeightedSelectorBuilder<string>()
        .AddItem("Common Loot", 50)    // Should be ~50% of selections
        .AddItem("Uncommon Loot", 30)  // Should be ~30% of selections
        .AddItem("Rare Loot", 15)      // Should be ~15% of selections
        .AddItem("Epic Loot", 4)       // Should be ~4% of selections
        .AddItem("Legendary Loot", 1)  // Should be ~1% of selections
        .Build();

    // Use Distribution Tester to verify these percentages match reality
    // across thousands of test selections
    ```

## Performance Profiler

The **Performance Profiler** is accessed via `Tools > Random Selector > Performance
Profiler` and provides detailed performance analysis of your Random Selector implementations.

### Profiling Capabilities

 * **Selection Performance**: Measure selections per second across different random
   providers
 * **Initialization Benchmarking**: Compare setup times for different selector configurations
 * **Memory Usage Analysis**: Track memory consumption patterns across various selector
   sizes
 * **Provider Comparison**: Side-by-side performance comparison of UnityEngine.Random,
   System.Random, and ThreadSafeRandom
 * **Scalability Testing**: Test performance with different numbers of items (10
   to 1,000+)
 * **Custom Test Sizes**: Configure small (1K), medium (10K), and large (100K) selection
   tests

### Key Performance Metrics

 * **Selections Per Second**: Raw selection throughput for each random provider
 * **Initialization Time**: Time required to build alias tables and prepare selectors
 * **Memory Footprint**: Memory usage for different selector configurations
 * **Scaling Characteristics**: How performance changes with selector size

### Using the Performance Profiler

 1. **Configure Test Parameters**: Set test sizes, item counts, and choose which random
    providers to benchmark
 2. **Run Performance Tests**: Execute comprehensive benchmarks across all configurations
 3. **Analyze Results**: Review detailed performance metrics in sortable tables
 4. **Identify Bottlenecks**: Find performance issues before they impact your game
 5. **Compare Providers**: Choose the best random provider for your specific use case

### Performance Optimization Tips

 * **UnityEngine.Random** typically offers the best performance for most Unity applications
 * **System.Random** with seeds provides deterministic results for testing and debugging
 * **ThreadSafeRandom** is essential for multi-threaded scenarios but has slight
   overhead
 * Initialization cost is amortized over many selections – the Alias Method’s O(
   1) selection performance shines with frequent use

## Additional Editor Utilities

### Cache Management

Use `Tools > Random Selector > Clear All Caches` to clear internal caches when experiencing
editor issues.

### Integration with Unity Profiler

The Performance Profiler integrates with Unity’s built-in Profiler, providing detailed
markers for:

 * `RandomSelector.GetItem` – Individual selection operations
 * `RandomSelector.Initialize` – Alias table construction
 * `RandomSelector.AddItems` – Item addition operations

These editor tools ensure your Random Selector configurations perform optimally 
and behave as expected, providing confidence in your weighted selection systems 
before deployment.

# Builder Pattern API

The Random Selector package now includes a powerful builder pattern API that makes
creating and configuring weighted selectors much more intuitive and flexible.

## WeightedSelectorBuilder

The `WeightedSelectorBuilder<T>` class provides a fluent API for constructing complex
probability distributions with method chaining. This approach offers several advantages:

 * **Readability**: Chainable methods make the code self-documenting
 * **Flexibility**: Easy to modify and experiment with different configurations
 * **Validation**: Built-in validation ensures your configuration is correct
 * **Reusability**: Builders can be cloned and modified for variations

### Basic Usage

    ```notranslate
    using RandomSelector;

    // Create a simple weighted selector
    var selector = new WeightedSelectorBuilder<string>()
        .AddItem("Common Item", 70)
        .AddItem("Rare Item", 20)
        .AddItem("Legendary Item", 10)
        .Build();

    // Use the selector
    var selectedItem = selector.GetItem();
    ```

### Core Building Methods

The builder provides several methods for adding items:

 * **AddItem(T item, int weight)** – Add a single item with specified weight
 * **AddItems(IEnumerable items, int weight)** – Add multiple items with equal weights
 * **AddItems(IEnumerable> items)** – Add from existing probability items
 * **AddItemWithPercentage(T item, float percentage)** – Add item with percentage(
   0-100%)
 * **AddIf(T item, int weight, bool condition)** – Conditionally add items

    ```notranslate
    // Adding multiple items with equal weights
    var selector = new WeightedSelectorBuilder<GameObject>()
        .AddItems(commonEnemies, 50)
        .AddItems(rareEnemies, 15)
        .AddItem(bossEnemy, 5)
        .AddIf(seasonalEnemy, 30, isHolidaySeason)
        .Build();
    ```

### Probability Adjustment Methods

Fine-tune your probability distributions:

 * **ScaleProbabilities(float multiplier)** – Scale all weights proportionally
 * **NormalizeProbabilities(int targetSum)** – Normalize weights to sum to target
 * **SetEqualProbabilities(int weight)** – Set all items to equal weights
 * **AdjustItemProbability(T item, int newWeight)** – Change weight of specific 
   item

    ```notranslate
    var selector = new WeightedSelectorBuilder<string>()
        .AddItem("Item A", 10)
        .AddItem("Item B", 20)
        .AddItem("Item C", 30)
        .ScaleProbabilities(2.0f)  // Double all weights
        .NormalizeProbabilities(100)  // Normalize to sum to 100
        .Build();
    ```

### Configuration Methods

Configure advanced behavior:

 * **WithRandom(IRandom random)** – Use custom random number generator
 * **WithSeed(int seed)** – Set seed for deterministic results
 * **OnItemSelected(UnityAction callback)** – Add selection event handler

    ```notranslate
    var selector = new WeightedSelectorBuilder<string>()
        .AddItem("Test Item", 1)
        .WithSeed(12345)  // Deterministic for testing
        .OnItemSelected(item => Debug.Log($"Selected: {item}"))
        .Build();
    ```

## WeightedSelectorPresets

The `WeightedSelectorPresets` static class provides factory methods for creating
common distribution patterns quickly and easily.

### Common Distribution Patterns

#### Uniform Distribution

All items have equal probability:

    ```notranslate
    var selector = WeightedSelectorPresets
        .CreateUniform(new[] { "A", "B", "C", "D" })
        .Build();
    ```

#### Exponential Decay

Items decrease in probability exponentially:

    ```notranslate
    var selector = WeightedSelectorPresets
        .CreateExponential(orderedItems, baseWeight: 100, decayFactor: 0.5f)
        .Build();
    // Results in weights like: 100, 50, 25, 12, 6, 3, 1...
    ```

#### Linear Decay

Items decrease in probability linearly:

    ```notranslate
    var selector = WeightedSelectorPresets
        .CreateLinearDecay(orderedItems, baseWeight: 100, decrement: 10)
        .Build();
    // Results in weights like: 100, 90, 80, 70, 60...
    ```

#### Normal Distribution (Bell Curve)

Items in the middle have higher probability:

    ```notranslate
    var selector = WeightedSelectorPresets
        .CreateNormal(items, peakWeight: 100, sigma: 0.3f)
        .Build();
    ```

#### Tiered Rarity System

Perfect for loot systems with rarity tiers:

    ```notranslate
    var selector = WeightedSelectorPresets
        .CreateTiered(
            commonItems: commonLoot,
            uncommonItems: uncommonLoot, 
            rareItems: rareLoot,
            legendaryItems: legendaryLoot,
            tierRatios: new int[] { 70, 20, 8, 2 })
        .Build();
    ```

#### Pareto Distribution (80/20 Rule)

20% of items get 80% of the probability weight:

    ```notranslate
    var selector = WeightedSelectorPresets
        .CreatePareto(items, highWeight: 80, lowWeight: 20)
        .Build();
    ```

#### Percentage-Based

Define exact percentage chances:

    ```notranslate
    var percentages = new Dictionary<string, float>
    {
        { "Very Common", 50f },
        { "Common", 30f },
        { "Uncommon", 15f },
        { "Rare", 4f },
        { "Legendary", 1f }
    };

    var selector = WeightedSelectorPresets
        .CreatePercentage(percentages, normalizeToHundred: true)
        .Build();
    ```

#### Custom Mathematical Function

Use any mathematical function for weight distribution:

    ```notranslate
    // Quadratic function example
    var selector = WeightedSelectorPresets
        .CreateCustom(items, 
            position => 100f * (1f - position * position), 
            minimumWeight: 1)
        .Build();
    ```

## Advanced Usage Examples

### Dynamic Loot System with Seasonal Adjustments

    ```notranslate
    // Base loot configuration
    var lootBuilder = WeightedSelectorPresets
        .CreateTiered(
            commonItems: baseCommonLoot,
            rareItems: baseRareLoot,
            legendaryItems: baseLegendaryLoot)
        .AddIf(holidayItem, 25, IsHolidaySeason())
        .AddIf(eventItem, 15, IsSpecialEvent());

    // Adjust for player level
    if (playerLevel > 50)
    {
        lootBuilder.ScaleProbabilities(1.5f)  // Better loot for high level
                   .AddItems(endgameLoot, 10);
    }

    var lootSelector = lootBuilder
        .OnItemSelected(item => LogLootDrop(item))
        .Build();
    ```

### A/B Testing System

    ```notranslate
    // Create multiple variants for testing
    var variantA = new WeightedSelectorBuilder<Reward>()
        .AddItems(rewards, 1)
        .WithSeed(GetPlayerSeed())
        .Build();

    var variantB = WeightedSelectorPresets
        .CreateExponential(rewards, 100, 0.7f)
        .WithSeed(GetPlayerSeed())
        .Build();

    var selector = isTestGroupA ? variantA : variantB;
    ```

### Adaptive Enemy Spawning

    ```notranslate
    var spawnBuilder = new WeightedSelectorBuilder<EnemyType>()
        .AddItems(basicEnemies, GetDifficultyWeight())
        .AddItems(eliteEnemies, GetEliteSpawnRate());

    // Adapt based on player performance
    if (playerWinRate > 0.8f)
    {
        spawnBuilder.ScaleProbabilities(1.3f)  // Increase difficulty
                   .AddItems(challengeEnemies, 20);
    }
    else if (playerWinRate < 0.3f)
    {
        spawnBuilder.AddItems(supportEnemies, 30);  // Add easier enemies
    }

    var enemySelector = spawnBuilder.Build();
    ```

The builder pattern and presets make Random Selector much more powerful and easier
to use, whether you need simple uniform distributions or complex multi-tiered systems
with dynamic adjustments.

# Extension Methods

Random Selector now includes powerful extension methods that enable seamless integration
between existing selectors and the builder pattern, providing convenient ways to
transform, combine, and analyze selectors.

## Core Extension Methods

The `RandomSelectorExtensions` class provides several methods to work with existing
selectors:

### Converting to Builder Pattern

    ```notranslate
    // Convert an existing selector to builder for modification
    var existingSelector = new RandomSelectorScript<string>();
    existingSelector.AddItem(10, "Item 1");
    existingSelector.AddItem(20, "Item 2");

    // Convert to builder and modify
    var modifiedSelector = existingSelector
        .ToBuilder()
        .AddItem("New Item", 15)
        .ScaleProbabilities(2.0f)
        .Build();
    ```

### Rebuilding with Modifications

    ```notranslate
    // Rebuild an existing selector with new configuration
    var updatedSelector = existingSelector.RebuildWith(builder =>
    {
        builder.AddItem("Bonus Item", 25)
               .NormalizeProbabilities(100)
               .WithSeed(12345);
    });
    ```

### Merging Multiple Selectors

    ```notranslate
    var selectors = new[] { commonLootSelector, rareLootSelector, epicLootSelector };
    var mergedSelector = selectors.Merge(builder =>
    {
        builder.AddItem("Special Merged Item", 5)
               .ScaleProbabilities(1.2f);
    });
    ```

## Convenient Transformation Methods

The extension methods provide shortcuts for common transformations:

    ```notranslate
    // Scale all weights by a multiplier
    var scaledSelector = mySelector.WithScaledWeights(1.5f);

    // Normalize weights to sum to a target (default 100)
    var normalizedSelector = mySelector.WithNormalizedWeights(1000);

    // Add new items to an existing selector
    var extendedSelector = mySelector.WithAdditionalItems(newItems, 25);

    // Remove specific items
    var filteredSelector = mySelector.WithoutItems(itemsToRemove);

    // Remove items matching a condition
    var cleanedSelector = mySelector.WithoutItemsWhere(item => item.StartsWith("Temp_"));

    // Set all items to equal weights
    var uniformSelector = mySelector.WithEqualWeights(10);

    // Change random strategy
    var seedSelector = mySelector.WithSeed(54321);
    var customRandomSelector = mySelector.WithRandomStrategy(new ThreadSafeRandom());
    ```

## Weight Distribution Analysis

Extension methods also provide statistical analysis of your selectors:

    ```notranslate
    // Get detailed statistics about weight distribution
    var stats = mySelector.GetWeightStats();
    Debug.Log($"Total Items: {stats.ItemCount}");
    Debug.Log($"Weight Range: {stats.MinWeight}-{stats.MaxWeight}");
    Debug.Log($"Is Uniform Distribution: {stats.IsUniform}");
    Debug.Log($"Full Stats: {stats.ToString()}");
    ```

# Selection Statistics and Analytics

Random Selector now includes comprehensive statistics tracking and analytics to 
help you understand selection patterns, verify distributions, and debug probability
issues.

## Statistics Tracking

The `SelectionStatistics` and `SelectionAnalytics` classes provide detailed tracking
of selection patterns:

### Basic Statistics Collection

    ```notranslate
    // Enable statistics tracking on a selector
    var selector = new RandomSelectorScript<string>();
    selector.AddItem(70, "Common");
    selector.AddItem(20, "Uncommon");
    selector.AddItem(10, "Rare");

    // Create analytics tracker
    var analytics = new SelectionAnalytics<string>();

    // Track selections
    for (int i = 0; i < 1000; i++)
    {
        var item = selector.GetItem();
        analytics.RecordSelection(item);
    }

    // Get detailed statistics
    var stats = analytics.GetStatistics();
    Console.WriteLine(stats.ToString());
    ```

### Real-Time Monitoring

    ```notranslate
    // Monitor selection patterns in real-time
    var utility = new SelectionAnalyticsUtility<GameObject>();
    utility.StartTracking(lootSelector);

    // After some gameplay...
    var currentStats = utility.GetCurrentStatistics();
    if (currentStats.MostSelected.Frequency > 0.8f)
    {
        Debug.LogWarning("One item is being selected too frequently!");
    }
    ```

## Statistical Analysis Features

### Selection Frequency Analysis

 * Track how often each item is selected
 * Calculate actual vs expected frequencies
 * Identify distribution anomalies
 * Monitor selection patterns over time

### Performance Metrics

 * Total selections made
 * Number of unique items selected
 * Most/least frequently selected items
 * Average selections per item
 * Distribution deviation analysis

### Usage Example with Debugging

    ```notranslate
    public class LootSystem : MonoBehaviour
    {
        [SerializeField] private RandomSelectorScript<LootItem> lootSelector;
        private SelectionAnalytics<LootItem> analytics;

        void Start()
        {
            analytics = new SelectionAnalytics<LootItem>();

            // Subscribe to selection events for automatic tracking
            lootSelector.OnItemSelected.AddListener(item => 
            {
                analytics.RecordSelection(item);

                // Debug unusual patterns
                var stats = analytics.GetStatistics();
                if (stats.TotalSelections % 100 == 0) // Every 100 selections
                {
                    ValidateDistribution(stats);
                }
            });
        }

        private void ValidateDistribution(SelectionStatistics stats)
        {
            if (stats.MostSelected.Frequency > 0.5f)
            {
                Debug.LogWarning($"Item '{stats.MostSelected.Item}' selected {stats.MostSelected.Frequency:P} of the time!");
            }
        }
    }
    ```
