BenMakesGames.RandomHelpers 3.1.1

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
There is a newer version of this package available.
See the version list below for details.
dotnet add package BenMakesGames.RandomHelpers --version 3.1.1
NuGet\Install-Package BenMakesGames.RandomHelpers -Version 3.1.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="BenMakesGames.RandomHelpers" Version="3.1.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add BenMakesGames.RandomHelpers --version 3.1.1
#r "nuget: BenMakesGames.RandomHelpers, 3.1.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install BenMakesGames.RandomHelpers as a Cake Addin
#addin nuget:?package=BenMakesGames.RandomHelpers&version=3.1.1

// Install BenMakesGames.RandomHelpers as a Cake Tool
#tool nuget:?package=BenMakesGames.RandomHelpers&version=3.1.1

Extensions for System.Random and IList to help you generate random content, including dice rolls, enum values, items from lists, sets, dictionaries, and more.

Hey! Listen! this library was designed for use in games; no effort has been made to make these methods cryptographically secure.

Pro tip: don't new up instances of System.Random if you don't need to control the seed. Just use System.Random.Shared!

Buy Me a Coffee at ko-fi.com

int Random.Roll(int rolls, int sides)

Simulates rolling dice to generate a random integer.

  • rolls: Number of times to roll the die.
  • sides: Number of sides of the die.

Example usage:

int damage = Random.Shared.Roll(2, 6) + 2; // 2d6+2 damage

T Random.Next(IReadOnlyList<T> list)

Picks a single, random element from the given array, list, or read-only list.

Example usage:

var names = new List<string>() { "Abby", "Ben", "Carly" };
var name = Random.Shared.Next(names);

T Random.Next(IReadOnlySet<T> set)

As above, but for sets, including HashSet, SortedSet, etc - anything that implements IReadOnlySet<T>.

TKey Random.Next(IReadOnlyDictionary<TKey, TValue> dictionary)

Picks a single, random key from the given dictionary, or read-only dictionary.

Example usage:

var myFavoriteNumbers = new Dictionary<double, string>() {
    { -1 / 12.0, "negative one-twelfth" },
    { 7, "seven" },
    { 42, "forty-two" },
};

var number = Random.Shared.NextKey(myFavoriteNumbers);

string Random.NextString(string allowedCharacters, int length)

Generates a random string.

  • allowedCharacters: A string containing the characters which can appear in the generated string.
  • length: The length of the string to generate.

Example usage:

// assuming some instance of Random named "rng":
string id = Random.Shared.NextString("abcdefghijklmnopqrstuvwxyz0123456789", 16);

string Random.NextString(IReadOnlyList<char> allowedCharacters, int length)

Generates a random string.

  • allowedCharacters: A list or array containing the characters which can appear in the generated string.
  • length: The length of the string to generate.

bool Random.NextBool()

Returns either true, or false.

(double X, double Y) Random.NextDoublePointInACircle(double radius = 1)

Generates a random point inside a circle of the given radius and centered at (0, 0).

Example usage:

var (x, y) = Random.Shared.NextDoublePointInACircle();

(float X, float Y) Random.NextSinglePointInACircle(double radius = 1)

Generates a random point inside a circle of the given radius and centered at (0, 0).

Example usage:

var (x, y) = Random.Shared.NextDoublePointInACircle();

The alias NextFloatPointInACircle also exists, in case you like calling floats "Float" instead of "Single".

T Random.NextEnumValue<T>()

Picks a single, random value from the given Enum type.

Example usage:

public enum Race
{
    Elf,
    Dwarf,
    Human
}

...

// assuming some instance of Random named "rng":
var race = Random.Shared.NextEnumValue<Race>();

void IList<T>.Shuffle(Random rng)

Fisher-Yates Shuffle. Modifies the array or list in-place.

Unlike the other methods in this library, Shuffle operates on a list, and must be passed an instance of Random (instead of operating on an RNG, and passing a list).

Example usage:

var favoriteFruit = new string[] { "Mango", "Watermelon", "Raspberry", "Cantaloupe" };
favoriteFruit.Shuffle(Random.Shared);

int Random.NextPercentBonus(int baseAmount, float percentModifier)

Suppose you want to increase damage by 10%. Someone deals 18 damage. Do they get +1 damage, or +2?

When you deal with small base numbers, percent bonuses can be hard to work with, since a hard decision to round up or down will cause your percent modifiers to have a much larger or smaller impact than intended.

There are a few ways to deal with this:

  • Use larger base numbers.
  • Use Math.Round (doesn't help much if numbers don't vary by much; especially if they're small to begin with).
  • Don't use % bonuses; use fixed bonuses.
  • Round down, but then take the remainder as a % chance to add one more.

Random.NextPercentBonus helps you do the last option (with additional logic to correctly handle % penalties).

I'd like to emphasize that just because this function helps you do the last option doesn't mean that it's the best option for YOUR game! Choose the system that works best for your game; if that system happens to be one where numbers are small, but % bonuses are wanted, then this function may help you solve a problem experienced by that system.

Example usage:

int damage = Random.Shared.Roll(2, 6) + 2; // 2d6+2
float damageBonus = 0.15f; // +15%

int finalDamage = Random.Shared.NextPercentBonus(damage, damageBonus);

Additional alias methods

  • NextFloat()
    • An alias for the system-provided NextSingle() (in case, like me, you always get tripped up by the whole float/single nomenclature)
  • NextLong(), NextLong(long exclusiveMax), and NextLong(long inclusiveMin, long exclusiveMax)
    • Aliases for the system-provided NextInt64 family
Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net6.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
5.1.0 230 11/25/2023
5.0.0 104 11/25/2023
4.0.0 122 11/4/2023
3.1.1 165 5/4/2023
3.1.0 123 5/4/2023
3.0.0 137 5/4/2023
2.2.1 173 4/16/2023
2.2.0 165 4/16/2023
2.1.4 609 7/25/2020
2.1.3 514 7/25/2020
2.1.2 518 11/1/2019
2.1.1 636 2/2/2019
2.1.0 943 4/1/2018
2.0.0 928 3/25/2018
1.0.0 889 3/25/2018