@opensourceframework/seeded-rng

@opensourceframework/seeded-rng

Seeded random number generator for reproducible randomness in games, simulations, and testing.

⚠️ SECURITY WARNING: The default SeededRNG class is NOT cryptographically secure!

Use SecureSeededRNG for security-sensitive operations (see below).

Two RNG Implementations

This library provides two RNG classes:

Class	Algorithm	Secure?	Use Case
SeededRNG	LCG	❌ No	Games, testing, simulations
SecureSeededRNG	ISAAC	✅ Yes	Passwords, tokens, keys

When to use which?

// ❌ NOT secure - Use for games, testing, simulations
import { SeededRNG } from '@opensourceframework/seeded-rng';
const gameRng = new SeededRNG(42);

// ✅ Secure - Use for security-sensitive operations
import { SecureSeededRNG } from '@opensourceframework/seeded-rng';
const secureRng = new SecureSeededRNG(42);

Features

• 🎲 Deterministic Randomness - Same seed always produces the same sequence
• 🔄 Reproducible Results - Perfect for testing, debugging, and replays
• 🎮 Game Development - Procedural generation, AI behavior, loot tables
• 🧪 Testing - Deterministic test data generation
• 📊 Simulations - Reproducible simulation results
• 🔐 Secure Option - Cryptographically secure version available
• 🪶 Zero Dependencies - Lightweight and self-contained

Installation

npm install @opensourceframework/seeded-rng
# or
yarn add @opensourceframework/seeded-rng
# or
pnpm add @opensourceframework/seeded-rng

Quick Start

Basic Usage (Not Secure)

import { SeededRNG } from '@opensourceframework/seeded-rng';

// Create with a specific seed for reproducibility
const rng = new SeededRNG(42);

// Basic random values
console.log(rng.next());           // Float [0, 1)
console.log(rng.nextInt(1, 100));  // Integer [1, 100]
console.log(rng.nextFloat(0, 10)); // Float [0, 10)

// Game mechanics
const diceRoll = rng.nextInt(1, 6);
const isCritical = rng.chance(0.05); // 5% chance
const coinFlip = rng.nextBool();

// Array operations
const colors = ['red', 'green', 'blue'];
const randomColor = rng.pick(colors);
const shuffled = rng.shuffle([1, 2, 3, 4, 5]);

// Weighted selection (loot tables)
const loot = rng.weightedPick([
  { item: 'common', weight: 70 },
  { item: 'rare', weight: 20 },
  { item: 'legendary', weight: 1 },
]);

// Reset to replay the same sequence
rng.reset();
console.log(rng.nextInt(1, 100)); // Same as first call

Secure Usage (Cryptographically Secure)

import { SecureSeededRNG } from '@opensourceframework/seeded-rng';

// Create with a specific seed (reproducible AND secure)
const rng = new SecureSeededRNG(42);

// Generate secure random values
console.log(rng.nextInt(1, 100));  // Secure integer
console.log(rng.nextHex(32));      // Secure hex string (64 chars)

// Generate truly random (non-seeded) secure values
const randomRng = new SecureSeededRNG();
const sessionToken = randomRng.nextHex(32); // Each run = different
const apiKey = randomRng.nextBase64(32);    // Base64 encoded

// Generate proper UUID v4
const uuid = rng.nextUUID(); // Cryptographically secure UUID

// Fork for independent but deterministic streams
const fork1 = rng.fork();
const fork2 = rng.fork();

API Reference

SeededRNG Class (Fast, NOT Secure)

Constructor

new SeededRNG(seed?: number)

Creates a new RNG instance. If no seed is provided, a random seed is generated.

Methods

Method	Description
next()	Returns random float [0, 1)
nextInt(min, max)	Returns random integer [min, max]
nextFloat(min, max)	Returns random float [min, max)
nextBool(probability?)	Returns random boolean (default 50%)
nextSign()	Returns -1 or 1
chance(probability)	Returns true with given probability
pick(array)	Returns random element from array
shuffle(array)	Returns shuffled copy of array
weightedPick(items)	Weighted random selection
nextHex(length)	Returns random hex string
nextUUID()	Returns UUID-like string
fork()	Creates new independent RNG
reset()	Resets to initial state
getInitialSeed()	Gets the initial seed
getCurrentSeed()	Gets current state
setSeed(seed)	Sets current state
getStats()	Gets RNG statistics

SecureSeededRNG Class (Cryptographically Secure)

Constructor

new SecureSeededRNG(seed?: number)

Creates a cryptographically secure RNG. If no seed is provided, uses crypto.getRandomValues().

Security Methods

Method	Description
nextHex(length)	Secure random hex string
nextBytes(length)	Secure random byte array
nextBase64(length)	Secure Base64 encoded string
nextUUID()	Secure UUID v4

Standard Methods (Same as SeededRNG)

Method	Description
next()	Returns random float [0, 1)
nextInt(min, max)	Returns random integer [min, max]
nextFloat(min, max)	Returns random float [min, max)
nextBool(probability?)	Returns random boolean
chance(probability)	Returns true with given probability
pick(array)	Returns random element from array
shuffle(array)	Returns shuffled copy of array
weightedPick(items)	Weighted random selection
fork()	Creates new independent RNG
reset()	Resets to initial state

Convenience Functions

import { 
  createRNG, 
  createSecureRNG,
  seededInt, 
  seededFloat, 
  seededShuffle, 
  seededPick,
  seededSecureInt,
  seededSecureHex
} from '@opensourceframework/seeded-rng';

// Fast RNG (not secure)
const rng = createRNG(42);
const value = seededInt(42, 1, 100);

// Secure RNG
const secureRng = createSecureRNG(42);
const secureHex = seededSecureHex(42, 32);

Usage Examples

Secure Token Generation

import { SecureSeededRNG } from '@opensourceframework/seeded-rng';

// Generate session tokens (secure!)
function generateSessionToken(): string {
  const rng = new SecureSeededRNG();
  return rng.nextHex(32); // 64-character hex string
}

// Generate API keys
function generateApiKey(): string {
  const rng = new SecureSeededRNG();
  return `sk_${rng.nextHex(24)}`;
}

// Generate password reset tokens
function generateResetToken(): string {
  const rng = new SecureSeededRNG();
  return rng.nextBase64(32);
}

// Generate secure UUIDs
function generateSecureId(): string {
  const rng = new SecureSeededRNG();
  return rng.nextUUID(); // Real UUID v4
}

Procedural Generation

import { SeededRNG } from '@opensourceframework/seeded-rng';

function generateTerrain(seed: number, width: number, height: number) {
  const rng = new SeededRNG(seed);
  const terrain = [];
  
  for (let y = 0; y < height; y++) {
    const row = [];
    for (let x = 0; x < width; x++) {
      row.push({
        elevation: rng.nextFloat(0, 1),
        moisture: rng.nextFloat(0, 1),
        hasTree: rng.chance(0.1),
      });
    }
    terrain.push(row);
  }
  
  return terrain;
}

// Same seed always produces same terrain
const world1 = generateTerrain(12345, 100, 100);
const world2 = generateTerrain(12345, 100, 100);
// world1 === world2 (same data)

Game Loot System

import { SeededRNG } from '@opensourceframework/seeded-rng';

class LootSystem {
  private rng: SeededRNG;

  constructor(seed: number) {
    this.rng = new SeededRNG(seed);
  }

  dropLoot() {
    const rarity = this.rng.weightedPick([
      { item: 'common', weight: 60 },
      { item: 'uncommon', weight: 25 },
      { item: 'rare', weight: 12 },
      { item: 'epic', weight: 2.5 },
      { item: 'legendary', weight: 0.5 },
    ]);

    const itemCount = this.rng.nextInt(1, 3);
    const items = [];

    for (let i = 0; i < itemCount; i++) {
      items.push(this.generateItem(rarity));
    }

    return { rarity, items };
  }

  private generateItem(rarity: string) {
    return {
      id: this.rng.nextUUID(),
      name: `${rarity} item`,
      stats: {
        power: this.rng.nextInt(10, 100),
        defense: this.rng.nextInt(5, 50),
      },
    };
  }
}

Testing with Deterministic Data

import { SeededRNG } from '@opensourceframework/seeded-rng';

describe('User Processing', () => {
  let rng: SeededRNG;

  beforeEach(() => {
    rng = new SeededRNG(42); // Consistent seed for all tests
  });

  function generateTestUser() {
    return {
      id: rng.nextUUID(),
      name: `User_${rng.nextInt(1000, 9999)}`,
      email: `test${rng.nextInt(1, 100)}@example.com`,
      age: rng.nextInt(18, 80),
      active: rng.nextBool(),
    };
  }

  it('should process user correctly', () => {
    const user = generateTestUser();
    // Same user data every test run
    expect(user.age).toBe(58); // Deterministic!
  });
});

Algorithm

SeededRNG (Fast, Not Secure)

Uses the Linear Congruential Generator (LCG) algorithm:

seed = (seed * a + c) % m

With parameters from Numerical Recipes:

• a = 9301
• c = 49297
• m = 233280

SecureSeededRNG (Cryptographically Secure)

Uses the ISAAC (Indirection, Shift, Accumulate, Add, and Count) cipher algorithm:

• Designed by Bob Jenkins (1996)
• Passes statistical tests for randomness
• Suitable for cryptographic applications
• Deterministic like SeededRNG (same seed = same sequence)

For random bytes without a seed, uses:

• Browser: crypto.getRandomValues()
• Node.js: crypto.webcrypto.getRandomValues()

Contributing

See Contributing Guide for details.

License

MIT © OpenSource Framework Contributors