{"id":25344387,"url":"https://github.com/nuskey8/NRandom","last_synced_at":"2026-04-18T14:30:20.708Z","repository":{"id":253764897,"uuid":"844206812","full_name":"yn01-dev/RandomExtensions","owner":"yn01-dev","description":"Provides better random number utilities and weighted collections for .NET and Unity.","archived":false,"fork":false,"pushed_at":"2024-08-20T04:59:42.000Z","size":366,"stargazers_count":113,"open_issues_count":0,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-21T13:12:38.352Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yn01-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-18T17:43:26.000Z","updated_at":"2025-02-18T02:39:55.000Z","dependencies_parsed_at":"2025-01-03T05:13:51.910Z","dependency_job_id":"ac735585-a236-4e30-a11c-782c6c38b73d","html_url":"https://github.com/yn01-dev/RandomExtensions","commit_stats":{"total_commits":42,"total_committers":1,"mean_commits":42.0,"dds":0.0,"last_synced_commit":"b635a9ce468043ef055d76dffcc01494dba2bf24"},"previous_names":["annulusgames/randomextensions","yn01dev/randomextensions","yn01-dev/randomextensions"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yn01-dev%2FRandomExtensions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yn01-dev%2FRandomExtensions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yn01-dev%2FRandomExtensions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yn01-dev%2FRandomExtensions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yn01-dev","download_url":"https://codeload.github.com/yn01-dev/RandomExtensions/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240018705,"owners_count":19734873,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-14T11:17:42.563Z","updated_at":"2026-04-18T14:30:20.629Z","avatar_url":"https://github.com/yn01-dev.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Random Extensions\n\n[![NuGet](https://img.shields.io/nuget/v/RandomEx.svg)](https://www.nuget.org/packages/RandomEx)\n[![Releases](https://img.shields.io/github/release/AnnulusGames/RandomExtensions.svg)](https://github.com/AnnulusGames/RandomExtensions/releases)\n[![GitHub license](https://img.shields.io/github/license/AnnulusGames/RandomExtensions.svg)](./LICENSE)\n\nEnglish | [日本語](README_JA.md)\n\n## Overview\n\nRandom Extensions is a library that provides functionality for pseudorandom number generation for .NET and Unity.\n\n.NET has a built-in `Random` class, but it is not sufficient in terms of functionality and contains complex implementations and unnecessary abstractions due to compatibility issues.\n\nUnity's `UnityEngine.Random` is a static class, making it impossible to instantiate. Additionally, it manages internal states, making it difficult to reproduce random numbers.\n\nRandom Extensions introduces `IRandom` as a new abstraction layer for random number generation, providing high performance implementations based on various algorithms (xoshift, xoshiro, splitmix, PCG). It also offers many useful features for handling random numbers, such as extension methods that support `System.Numerics` and Unity types, `IWeightedCollection\u003cT\u003e` for handling weighted random numbers, and LINQ extensions for random numbers (`RandomEnumerable`).\n\n\u003e [!WARNING]\n\u003e Do not use this library for security purposes. If you need cryptographically secure random numbers, use `System.Security.Cryptography.RandomNumberGenerator`.\n\n## Installation\n\n### NuGet packages\n\nRandom Extensions requires .NET Standard 2.1 or higher. The package is available on NuGet.\n\n### .NET CLI\n\n```ps1\ndotnet add package RandomEx\n```\n\n### Package Manager\n\n```ps1\nInstall-Package RandomEx\n```\n\n### Unity\n\nYou can use Random Extensions in Unity by using NugetForUnity. For more details, refer to the [Unity](#unity-1) section.\n\n## Basic Usage\n\nYou can generate random numbers using `RandomEx.Shared`.\n\n```cs\nusing RandomExtensions;\n\n// Get a random value between 0-9\nvar n = RandomEx.Shared.NextInt(0, 10);\n\n// Get a random boolean value\nvar flag = RandomEx.Shared.NextBool();\n```\n\nYou can also create an instance of `IRandom` initialized with a random seed using `RandomEx.Create()`.\n\n```cs\n// Create an instance\nvar rand = RandomEx.Create();\n\n// Get a random value in the range [0.0, 1.0)\nvar d = rand.NextDouble();\n```\n\n\u003e [!WARNING]\n\u003e Please note that `RandomEx.Shared` is thread-safe, but instances created with `RandomEx.Create()` or other classes implementing `IRandom` are not thread-safe.\n\n## Supported Types\n\nRandom Extensions supports more types than the standard `System.Random`.\n\n```cs\nvar rand = RandomEx.Create();\n\n// int\nrand.NextInt();                 // [int.MinValue, int.MaxValue]\nrand.NextInt(10);               // [0, 10)\nrand.NextInt(10, 20);           // [10, 20)\n\n// uint\nrand.NextUInt();                // [0, uint.MaxValue]\nrand.NextUInt(10);              // [0, 10)\nrand.NextUInt(10, 20);          // [10, 20)\n\n// long\nrand.NextLong();                // [long.MinValue, long.MaxValue]\nrand.NextLong(10);              // [0, 10)\nrand.NextLong(10, 20);          // [10, 20)\n\n// ulong\nrand.NextULong();               // [0, ulong.MaxValue]\nrand.NextULong(10);             // [0, 10)\nrand.NextULong(10, 20);         // [10, 20)\n\n// float\nrand.NextFloat();               // [0f, 1f)\nrand.NextFloat(10f);            // [0f, 10f)\nrand.NextFloat(10f, 20f);       // [10f, 20f)\n\n// double\nrand.NextDouble();              // [0.0, 1.0)\nrand.NextDouble(10.0);          // [0.0, 10.0)\nrand.NextDouble(10.0, 20.0);    // [10.0, 20.0)\nrand.NextDoubleGaussian();      // Get a random value following a Gaussian distribution with a mean of 0.0 and a standard deviation of 1.0\n\n// byte[], Span\u003cbyte\u003e\nrand.NextBytes(buffer);          // Fill the buffer with random bytes\n```\n\nAdditionally, by introducing the extension package, you can use methods that support types in `System.Numerics` and Unity. For details, see the sections on [System.Numerics](#systemnumerics) and [Unity](#unity-1).\n\n## Collection Operations\n\n### Element Retrieval\n\nYou can use the `GetItem()` method to retrieve a random element from an array. If you want to retrieve multiple elements at once, use `GetItems()`.\n\n```cs\nvar rand = RandomEx.Create();\n\n// Create an array of values\nvar values = new int[] { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };\n\n// Get a random element\nvar item = rand.GetItem(values);\n\n// Get 5 random elements (with duplicates)\nvar items = rand.GetItems(values, 5);\n```\n\nYou can also specify weights for each element. The array of weights you pass as an argument must match the number of elements in the original array.\n\n```cs\nvar values = new int[] { 0, 1, 2 };\nvar weights = new double[] { 1.0, 5.0, 1.0 };\n\n// Retrieve weighted random elements\nvar item = rand.GetItem(values, weights);\nvar items = rand.GetItem(values, weights, 5);\n```\n\n### Shuffling\n\nYou can shuffle the elements of an array using the `Shuffle()` method.\n\n```cs\nvar array = new int[] { 0, 1, 2, 3, 4, 5 };\n\n// Shuffle the array elements\nrand.Shuffle(array);\n```\n\nThis method modifies the array itself. If you need a side-effect-free shuffle, use the following LINQ extension.\n\n### LINQ Extensions\n\nUnder the `RandomExtensions.Linq` namespace, there are LINQ extensions that utilize random numbers.\n\n```cs\nusing System;\nusing System.Linq;\nusing RandomExtensions.Linq;\n\nvar sequence = Enumerable.Range(0, 100);\n\n// Get a random element\nvar r = sequence.RandomElement();\n\n// Shuffle the order\nforeach (var item in sequence.Shuffle())\n{\n    Console.WriteLine(item);\n}\n\n// Create an IEnumerable\u003cT\u003e that yields random values in the range [0, 9] 10 times\nforeach (var item in RandomEnumerable.Repeat(0, 10, 10))\n{\n    Console.WriteLine(item);\n}\n```\n\nThese methods can take an `IRandom` instance for random number generation. If not specified, `RandomEx.Shared` will be used.\n\n```cs\nvar rand = RandomEx.Create();\n\n// Get elements using the passed rand instance\nvar r = sequence.RandomElement(rand);\n```\n\n## Weighted Collections\n\nUnder the `RandomExtensions.Collections` namespace, there are collections that hold weighted elements.\n\n```cs\n// Interface for a weighted collection\npublic interface IWeightedCollection\u003cT\u003e : IReadOnlyCollection\u003cWeightedValue\u003cT\u003e\u003e\n{\n    T GetItem\u003cTRandom\u003e(TRandom random) where TRandom : IRandom;\n    void GetItems\u003cTRandom\u003e(TRandom random, Span\u003cT\u003e destination) where TRandom : IRandom;\n}\n\n// Struct representing a weighted element\npublic readonly record struct WeightedValue\u003cT\u003e(T Value, double Weight);\n```\n\nBelow is a sample of using `WeightedList\u003cT\u003e` for weighted selection.\n\n```cs\n// Create a weighted list\nvar weightedList = new WeightedList\u003cstring\u003e();\n\n// Add elements with specified weights\nweightedList.Add(\"Legendary\", 0.5f);\nweightedList.Add(\"Epic\", 2.5f);\nweightedList.Add(\"Rare\", 12f);\nweightedList.Add(\"Uncommon\", 25f);\nweightedList.Add(\"Common\", 60f);\n\n// Retrieve a weighted random element\nvar rarity = weightedList.GetItem();\n```\n\n## IRandom\n\nRandom Extensions provides `IRandom` as an interface for random number generators. By implementing this interface, you can create custom random number generator.\n\n```cs\npublic interface IRandom\n{\n    void InitState(uint seed);\n    uint NextUInt();\n    ulong NextULong();\n}\n```\n\n### IRandom Implementations\n\nRandom Extensions provides several `IRandom` implementations by default. Below is a list of class names and the pseudorandom number algorithms they use internally.\n\n| Class Name | Algorithm |\n| - | - |\n| `Pcg32Random` | PCG32 (PCG-XSH-RR) |\n| `SplitMix32Random` | splitmix32 |\n| `SplitMix64Random` | splitmix64 |\n| `Xorshift32Random` | xorshift32 |\n| `Xorshift64Random` | xorshift64 |\n| `Xorshift128Random` | xorshift128 |\n| `Xoshiro128StarStarRandom` | xoshiro128** |\n| `Xoshiro256StarStarRandom` | xoshiro256** |\n\n## RandomExtensions.Algorithms\n\nUnder the `RandomExtensions.Algorithms` namespace, there are implementations of algorithms for generating pseudorandom numbers.\n\nThese are structs with minimal state and methods, useful in scenarios where performance is critical or state serialization is required.\n\nBelow is a sample using the `XorShift32` struct to generate pseudorandom numbers.\n\n```cs\nusing RandomExtensions.Algorithms;\n\nvar seed = 123456;\nvar xorshift = new Xorshift32(seed);\n\nvar r = xorshift.Next();\n```\n\n## System.Numerics\n\n`RandomEx.Numerics` package, available on NuGet, provides extensions that support types in `System.Numerics`.\n\n#### .NET CLI\n\n```ps1\ndotnet add package RandomEx.Numerics\n```\n\n#### Package Manager\n\n```ps1\nInstall-Package RandomEx.Numerics\n```\n\n### Basic Usage\n\nAfter installation, you can use the methods below.\n\n```cs\nusing System.Numerics;\nusing RandomExtensions;\nusing RandomExtensions.Numerics;\n\nvar rand = RandomEx.Create();\n\n// Vector2\nrand.NextVector2();\nrand.NextVector2(new Vector2(10f, 10f));\nrand.NextVector2(new Vector2(10f, 10f), new Vector2(20f, 20f));\nrand.NextVector2Direction();    // Get a random direction vector of length 1\nrand.NextVector2InsideCircle(); // Get random point inside a unit circle\n\n// Vector3\nrand.NextVector3();\nrand.NextVector3(new Vector3(10f, 10f, 10f));\nrand.NextVector3(new Vector3(10f, 10f, 10f), new Vector2(20f, 20f, 20f));\nrand.NextVector3Direction();    // Get a random direction vector of length 1\nrand.NextVector3InsideSphere(); // Get random point inside a unit sphere\n\n// Vector4\nrand.NextVector4();\nrand.NextVector4(new Vector4(10f, 10f, 10f, 10f));\nrand.NextVector4(new Vector4(10f, 10f, 10f, 10f), new Vector2(20f, 20f, 20f, 20f));\n\n// Quaternion\nrand.NextQuaternionRotation();  // Get a quaternion representing a random rotation\n```\n\n## Unity\n\nRandom Extensions is available for use in Unity and provides an extension package.\n\n### Requirements\n\n* Unity 2021.3 or higher\n\n### Installation\n\n1. Install [NugetForUnity](https://github.com/GlitchEnzo/NuGetForUnity).\n\n2. Open the NuGet window by selecting `NuGet \u003e Manage NuGet Packages`, search for the `RandomEx` package, and install it.\n    ![img](docs/img-nugetforunity.png)\n\n3. Open the Package Manager window by selecting `Window \u003e Package Manager`, then click on `[+] \u003e Add package from git URL` and enter the following URL:\n\n    ```\n    https://github.com/AnnulusGames/RandomExtensions.git?path=src/RandomExtensions.Unity/Assets/RandomExtensions.Unity\n    ```\n\n### Extension Methods\n\nUnder the `RandomExtensions.Unity` namespace, the following extension methods are available for Unity:\n\n```cs\nusing UnityEngine;\nusing RandomExtensions;\nusing RandomExtensions.Unity;\n\nvar rand = RandomEx.Create();\n\n// Vector2\nrand.NextVector2();\nrand.NextVector2(new Vector2(10f, 10f));\nrand.NextVector2(new Vector2(10f, 10f), new Vector2(20f, 20f));\nrand.NextVector2Direction();    // Get a random direction vector of length 1\nrand.NextVector2InsideCircle(); // Get random point inside a unit circle\n\n// Vector3\nrand.NextVector3();\nrand.NextVector3(new Vector3(10f, 10f, 10f));\nrand.NextVector3(new Vector3(10f, 10f, 10f), new Vector2(20f, 20f, 20f));\nrand.NextVector3Direction();    // Get a random direction vector of length 1\nrand.NextVector3InsideSphere(); // Get random point inside a unit sphere\n\n// Vector4\nrand.NextVector4();\nrand.NextVector4(new Vector4(10f, 10f, 10f, 10f));\nrand.NextVector4(new Vector4(10f, 10f, 10f, 10f), new Vector2(20f, 20f, 20f, 20f));\n\n// Quaternion\nrand.NextQuaternionRotation();  // Get a quaternion representing a random rotation\n\n// Color\nrand.NextColor();\nrand.NextColor(new Color(1f, 1f, 1f));\nrand.NextColor(new Color(0f, 0f, 0f), new Color(1f, 1f, 1f));\nrand.NextColorHSV(0f, 1f, 0f, 1f, 0f, 1f);          // Specify HSV range\nrand.NextColorHSV(0f, 1f, 0f, 1f, 0f, 1f, 0f, 1f);  // Specify HSV and alpha range\n```\n\n## License\n\nThis library is released under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnuskey8%2FNRandom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnuskey8%2FNRandom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnuskey8%2FNRandom/lists"}