🎲 @trap-stevo/rng

The ultimate deterministic random number generator for reproducible creativity and controlled chaos.
Power procedural generation, AI systems, simulations, and games with elegance, speed, and infinite repeatability — all from a single seed.

🚀 Features

• 🎯 Seedable Randomness – Deterministic output from string, number, or auto-generated seeds
• ⚙️ Functional & OOP Modes – Use as a function or an engine with .next() and .reset()
• 🔁 Reproducible Control – Perfect for testing, generation, and simulations
• ✨ Compact & Fast – Zero-dependency, minimal footprint, blazing performance
• 🧠 Hash-Based Entropy – Converts any string into high-quality random sequences

🧠 Use Cases

• Procedural terrain or content generation
• Repeatable unit testing scenarios
• Reproducible AI behavior or randomized narratives
• Games, simulations, puzzles, and more

⚙️ System Requirements

| Requirement | Version | |----------------|--------------------| | Node.js | ≥ 19.x | | npm | ≥ 9.x (recommended)| | OS | Windows, macOS, Linux |

🔍 API Specifications

RNG(input)

Returns a pure function that yields deterministic floats (0 → 1) each call.

| Param | Type | Description | |-------|-------------------|--------------------------------------| | input | string, number| Seed input, either as string or number |

RNGEngine

A class version of the RNG with additional control.

Constructor

new RNGEngine(seedInput)

| Param | Type | Description | |-----------|-------------------|--------------------------------------| | seedInput | string, number| Seed input, either as string or number |

Methods

| Method | Description | |------------|--------------------------------------------------| | next() | Returns the next deterministic float (0 → 1) | | call() | Alias for .next() (functional-style compat) | | reset() | Resets internal state to original seed position |

🧬 Hash Function

Used internally to convert strings into numeric seeds.

import { HashText } from "@trap_stevo/rng";

const hash = HashText("hello world");
console.log(hash); // → 1794106052

📦 Installation

npm install @trap_stevo/rng

🛠️ Usage

🔧 Functional Mode

import { RNG } from "@trap_stevo/rng";

const random = RNG("planet-42");

console.log(random()); // → 0.32918 (always the same)
console.log(random()); // → 0.84920

⚙️ Class-Based Mode

import { RNGEngine } from "@trap_stevo/rng";

const engine = new RNGEngine("galaxy-seed");

console.log(engine.next()); // → deterministic float
console.log(engine.next()); // → next deterministic float

engine.reset(); // Resets back to initial state

📜 License

See License in LICENSE.md

🎲 Predictable Randomness, Infinite Possibility.
Bring order to chaos. From simulations to starscapes, rng powers your imagination with precision.