BorrowedTorch.Randomness
1.4.0
Prefix Reserved
dotnet add package BorrowedTorch.Randomness --version 1.4.0
NuGet\Install-Package BorrowedTorch.Randomness -Version 1.4.0
<PackageReference Include="BorrowedTorch.Randomness" Version="1.4.0" />
<PackageVersion Include="BorrowedTorch.Randomness" Version="1.4.0" />
<PackageReference Include="BorrowedTorch.Randomness" />
paket add BorrowedTorch.Randomness --version 1.4.0
#r "nuget: BorrowedTorch.Randomness, 1.4.0"
#:package BorrowedTorch.Randomness@1.4.0
#addin nuget:?package=BorrowedTorch.Randomness&version=1.4.0
#tool nuget:?package=BorrowedTorch.Randomness&version=1.4.0
BorrowedTorch.Randomness
Seeded random streams and noise for procedural generation. The same seed gives the same numbers on every platform, every .NET version and every version of this package, so a world seed always rebuilds the same world.
using BorrowedTorch.Randomness;
var world = new Rng(worldSeed);
var mazeRng = world.Fork("maze", floor); // one stream per system (and per floor)
var lootRng = world.Fork("loot"); // draws here never shift the maze
int roll = lootRng.NextInt(1, 7); // unbiased (Lemire's method)
bool trap = mazeRng.NextBool(0.1);
var chunk = StableHash.Of("chunk"); // in hot loops, hash the key once:
var chunkRng = world.Fork(chunk, index); // same stream as world.Fork("chunk", index)
// Noise: pure functions of (seed, x, y), no period, so an infinite world can be sampled in any order.
var caves = new FractalNoise(world.Fork("caves").Seed, FractalSettings.Default with { Octaves = 5 });
bool open = caves.Sample(cellX, cellY) > 0.05;
What is in it
| Type | Purpose |
|---|---|
Rng |
PCG32 generator: NextUInt, NextInt, NextDouble, NextBool, Pick, Shuffle, Fork |
StableHash |
FNV-1a 64 + SplitMix64: stable seeds from strings, Combine, Mix |
GradientNoise |
2D Perlin-style gradient noise in [-1, 1] on a hashed lattice: stateless, no period |
FractalNoise |
fBm: octaves of GradientNoise with their own seeds and offsets, normalized to [-1, 1] |
FractalSettings |
Frequency, octaves, lacunarity, gain as a plain record (Default with { ... }) |
R2Sequence |
The R2 low-discrepancy sequence: points of the unit square that fill it evenly, open-ended |
BlueNoise |
A seeded square of blue noise (void and cluster) that tiles without a seam, for dithering |
Shaders
The same kind of thing for HLSL, as source: Random.fxh, Noise.fxh and Sequences.fxh arrive in your output at
Content/Effects/Randomness/, for your shaders - and other BorrowedTorch packages' - to #include and compile with
them, from the content pipeline or at runtime. A shader in Content/Effects/YourGame/ reaches them as
#include "../Randomness/Noise.fxh".
| File | What is in it |
|---|---|
Random.fxh |
Integer hashes pcg, pcg2d, pcg3d, WangHash; Hash12, a sine-free hash of two floats; |
Random01, rnd (a stream), SeedHash, ToUnit in [0, 1); per-pixel noise for dithering and |
|
spreading samples - InterleavedGradientNoise and its turned gradient, TriangularNoise |
|
Noise.fxh |
2D gradient noise GNoise, Noise01, Fbm01; 3D value noise ValueNoise3, Fbm3 - seeded; |
and 3D noise tiling every period cells, for volumes baked once: gradient PerlinNoise3, |
|
PerlinFbm3; cellular WorleyNoise3, WorleyFbm3; and the two together, PerlinWorley3 |
|
Sequences.fxh |
Low-discrepancy points: RadicalInverse, Hammersley, R2 (as R2Sequence, for small indices) |
32-bit, as shader model 5 is: not the numbers Rng and the C# noise give for the same seed, which are 64-bit. The
same input gives the same output on every GPU, as integer arithmetic does; the noise's floating point can differ in
its last bits between GPUs.
Guarantees
- Output is frozen. No release will change what an existing method returns for a given seed,
including how
Forkderives seeds. A new algorithm ships as a new type. The golden-value tests (KnownValues_*) enforce this for every method, on .NET 8 and 10. - Noise is bit-identical everywhere. It uses only IEEE add, subtract, multiply and floor (no
Math.Sin,Math.Powor permutation tables), and its golden values are tested on .NET 8 and 10 likeRng's. - Forks depend only on the parent's seed and the key, not on how many numbers the parent has drawn, so systems stay independent of each other's call order.
- Fork keys are part of your save format. Renaming
"maze"changes every maze for every saved seed.
Not for security
Rng is predictable by design. Never use it for anything adversarial (anti-cheat, multiplayer
authority, tokens, keys); use System.Security.Cryptography.RandomNumberGenerator instead.
Build
dotnet test
dotnet pack src/BorrowedTorch.Randomness -c Release -o artifacts
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. 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. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net8.0
- No dependencies.
NuGet packages (4)
Showing the top 4 NuGet packages that depend on BorrowedTorch.Randomness:
| Package | Downloads |
|---|---|
|
BorrowedTorch.Nature
Nature for MonoGame (compute fork), generated and drawn on the GPU: grass, a procedural sky seen through air worked out from wherever the viewer is, from the ground to orbit, with volumetric clouds, and the wind for anything to move in. |
|
|
BorrowedTorch.FabricSimulator
GPU cloth solver for MonoGame: a compute shader integrates the particles, relaxes the constraints and computes the normals, and the positions never leave the GPU. Verlet integration with Jacobi relaxation, plastic bending so creases stay, long-range attachments, colliders with friction, self-collision through a spatial hash, cuts, rips and tearing under strain, and drag against wind you set every frame. Solver only - you fetch the particles in your own vertex shader and draw the sheet yourself. Requires Windows and the compute-capable MonoGame fork. The solver ships as HLSL and is compiled by your content pipeline. |
|
|
BorrowedTorch.Architecture
Procedural level architecture for grid- and tile-based games: cell-space footprint masks, grid layouts whose edges are walls, openings or doors, a seeded perfect-maze generator (recursive backtracker) with distance and dead-end queries, and tilers that turn a layout into a thick-wall or thin-wall tile map. |
|
|
BorrowedTorch.Engine
Kindling, Borrowed Torch's game engine: what a game's own code builds against - its features registering components, systems, keys and UI handlers - for the Kindling editor and player to run |
GitHub repositories
This package is not used by any popular GitHub repositories.