SeedForge Documentation

Advanced seedable pseudo-random number generator library for JavaScript with multiple algorithms, statistical distributions, and noise generators.

#Installation

npm

npm install seedforge-prng

CDN

<script src="https://unpkg.com/seedforge-prng/dist/seedforge.js"></script>

ES Modules

import { PRNG, Noise, Algorithms } from 'seedforge-prng';

CommonJS

const { PRNG, Noise, Algorithms } = require('seedforge-prng');

#Quick Start

const { PRNG } = require('seedforge-prng');

// Create a seeded generator
const rng = new PRNG('my-seed');

// Basic random values
rng.random();          // 0.0 to 1.0
rng.int(1, 100);       // Integer 1-100
rng.float(0, 10);      // Float 0-10
rng.bool(0.5);         // 50% true

// Array operations
rng.pick(['a', 'b', 'c']);  // Random element
rng.shuffle([1, 2, 3, 4]);   // Shuffled copy

// Distributions
rng.normal(100, 15);   // Gaussian
rng.exponential(1.5);  // Exponential

// Same seed = same results, every time!

#Algorithms

SeedForge includes 6 PRNG algorithms. Choose based on your needs:

Selecting an Algorithm

// Default (xoshiro128**)
const rng1 = new PRNG('seed');

// Specify algorithm
const rng2 = new PRNG('seed', 'sfc32');
const rng3 = new PRNG('seed', 'pcg32');
const rng4 = new PRNG('seed', 'mulberry32');

#Constructor

// String seed (hashed internally)
const rng1 = new PRNG('my-world-seed');

// Numeric seed
const rng2 = new PRNG(12345);

// With specific algorithm
const rng3 = new PRNG('seed', 'sfc32');

#Basic Generation

const rng = new PRNG('example');

rng.random();       // 0.7234521
rng.int(1, 6);       // 4 (dice roll)
rng.int(0, 255);     // 182 (byte value)
rng.float(-1, 1);    // -0.3421
rng.bool();          // true (50% chance)
rng.bool(0.8);       // true (80% chance)
rng.sign();          // -1 or 1

#Statistical Distributions

SeedForge provides 17 statistical distributions for realistic data generation.

All Distributions

const rng = new PRNG('stats');

// IQ scores (mean 100, stddev 15)
rng.normal(100, 15);  // 94.28

// Loot gold (minimum 10, Pareto distributed)
rng.pareto(1.5, 10);  // Usually low, occasionally high

// Enemy spawn count
rng.poisson(3);       // Average of 3

// v1.1.0: Word frequency ranking (Zipf distribution)
rng.zipf(100, 1.0);   // Returns 1-100 with power-law frequency

// v1.1.0: Wind direction (Von Mises circular distribution)
rng.vonMises(0, 2);   // Concentrated around 0 radians (East)

// v1.1.0: Card draw probability (Hypergeometric)
rng.hypergeometric(52, 13, 5);  // Hearts in 5-card hand

#Array Utilities

const rng = new PRNG('arrays');

// Pick random element
rng.pick(['sword', 'shield', 'potion']);  // 'shield'

// Draw 3 cards without replacement
rng.sample(['A', 'K', 'Q', 'J', '10'], 3);  // ['K', '10', 'A']

// Shuffle a deck
const deck = [1, 2, 3, 4, 5];
rng.shuffle(deck);  // [3, 1, 5, 2, 4]

// Weighted selection
rng.weightedPick(
    ['common', 'rare', 'legendary'],
    [70, 25, 5]
);  // Most likely 'common'

// Object-based weights (loot table)
rng.weightedPickObject({
    common: 60,
    uncommon: 25,
    rare: 10,
    legendary: 5
});  // 'common'

#Geometric Utilities

Generate random points in various shapes for spawn systems and spatial distribution.

const rng = new PRNG('geometry');

// Spawn enemy within 50 units of player
const spawn = rng.pointInCircle(50);
// { x: 23.4, y: -31.2 }

// Place items around a ring
const item = rng.pointOnCircle(100);
// { x: 87.3, y: 48.7 }

// 3D particle spawn
const particle = rng.pointInSphere(10);
// { x: 3.2, y: -5.1, z: 7.8 }

// Random position in room
const pos = rng.pointInRect(800, 600);
// { x: 423.5, y: 187.2 }

#Special Generators

const rng = new PRNG('special');

rng.uuid();      // 'f47ac10b-58cc-4372-a567-0e02b2c3d479'
rng.color();     // '#7a3f9c'
rng.colorRGB();  // { r: 122, g: 63, b: 156 }
rng.colorHSL();  // { h: 274, s: 42, l: 43 }
rng.angle();     // 4.234 (radians)
rng.angleDeg();  // 242.5 (degrees)

#State Management

Save, restore, clone, and fork generators for game saves, replays, and parallel streams.

const rng = new PRNG('game');

// Generate some values
rng.random();
rng.random();

// Save state
const savedState = rng.getState();
const json = JSON.stringify(savedState);

// ... later, restore state
rng.setState(JSON.parse(json));

// Clone for parallel use
const rng2 = rng.clone();
rng.random() === rng2.random();  // true

// Fork for independent streams
const weatherRng = rng.fork('weather');
const combatRng = rng.fork('combat');

#Simplex Noise

Simplex noise is ideal for procedural terrain, textures, and organic patterns.

const { Noise } = require('seedforge-prng');

const noise = new Noise.SimplexNoise('terrain');

// 2D noise
noise.noise2D(0, 0);       // -1 to 1
noise.noise2D(0.5, 0.5);   // Smooth variation

// 3D noise
noise.noise3D(0, 0, 0);    // For volumetric data

// Fractal Brownian Motion (fBm)
noise.fbm(x, y, z, octaves, lacunarity, persistence);

#Value Noise

const noise = new Noise.ValueNoise('seed');

noise.noise2D(0, 0);
noise.noise3D(0, 0, 0);
noise.fbm(x, y, z, octaves, lacunarity, persistence);

#Perlin Noise NEW in v1.1.0

Classic Perlin gradient noise - the original algorithm that started it all.

const perlin = new Noise.PerlinNoise('seed');

// 2D noise (returns -1 to 1)
perlin.noise2D(1.5, 2.3);     // 0.312

// 3D noise
perlin.noise3D(1.5, 2.3, 0.8); // -0.089

// With fBm for terrain
perlin.fbm(x * 0.01, y * 0.01, null, 6, 2.0, 0.5);

#Worley Noise NEW in v1.1.0

Cellular/Voronoi noise - perfect for stone, cells, stained glass, and organic patterns.

const worley = new Noise.WorleyNoise('seed');

// Basic usage - distance to nearest point
worley.noise2D(1.5, 2.3);

// Distance types: 'euclidean', 'manhattan', 'chebyshev'
// Feature indices: 0 = F1 (nearest), 1 = F2 (second), 2 = F2-F1 (edges)

// Round cells (euclidean F1)
worley.noise2D(x, y, 'euclidean', 0);

// Diamond cells (manhattan)
worley.noise2D(x, y, 'manhattan', 0);

// Cell edges / cracks (F2-F1)
worley.noise2D(x, y, 'euclidean', 2);

#Ridged Noise NEW in v1.1.0

Sharp ridges and peaks - ideal for mountains, veins, lightning bolts.

const ridged = new Noise.RidgedNoise('mountains');

// Sharp mountain ridges
ridged.noise2D(x * 0.01, y * 0.01);

// With fBm for detailed peaks
ridged.fbm(x * 0.01, y * 0.01, null, 6, 2.0, 0.5);

#Billowed Noise NEW in v1.1.0

Soft, puffy shapes - perfect for clouds, smoke, foam.

const billowed = new Noise.BillowedNoise('clouds');

// Fluffy cloud shapes
billowed.noise2D(x * 0.01, y * 0.01);

// With fBm for detailed clouds
billowed.fbm(x * 0.01, y * 0.01, null, 4, 2.0, 0.5);

#fBm & Turbulence

fBm layers multiple octaves of noise for more natural-looking results. Turbulence uses absolute values for chaotic patterns.

const noise = new Noise.SimplexNoise('fire');

// Standard fBm for terrain
noise.fbm(x * 0.01, y * 0.01, null, 6, 2.0, 0.5);

// NEW: Turbulence for fire/smoke
noise.turbulence(x * 0.03, y * 0.03, null, 6, 2.2, 0.5);

#Domain Warping NEW in v1.1.0

Distort coordinates using noise for organic, flowing, otherworldly patterns.

const noise = new Noise.SimplexNoise('marble');

// Single warp - subtle organic distortion
noise.warp(x * 0.02, y * 0.02, 1.5, 4);

// Double warp - extreme alien terrain
noise.warp2(x * 0.02, y * 0.02, 2.0, 4);

#TypeScript

SeedForge includes full TypeScript definitions.

import { PRNG, Noise, PRNGState, Point2D, RGB } from 'seedforge-prng';

const rng: PRNG = new PRNG('seed');

const value: number = rng.random();
const point: Point2D = rng.pointInCircle(10);
const color: RGB = rng.colorRGB();
const state: PRNGState = rng.getState();

const noise: Noise.SimplexNoise = new Noise.SimplexNoise('terrain');

#Browser Usage

Script Tag

<script src="https://unpkg.com/seedforge-prng/dist/seedforge.js"></script>
<script>
    const rng = new PRNG.PRNG('seed');
    const noise = new PRNG.Noise.SimplexNoise('terrain');
</script>

ES Modules

<script type="module">
    import { PRNG, Noise } from 'https://unpkg.com/seedforge-prng/dist/seedforge.mjs';
    
    const rng = new PRNG('seed');
</script>

#Performance

Benchmark results (operations per second, higher is better):