@trap_stevo/rng/README.md

Unleash beautifully deterministic randomness with a seedable generator crafted for developers, artists, game designers, and procedural creators. Whether forging alien worlds, generating dynamic narratives, or craving control over chaos, this tool delivers

# 🎲 @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

```js
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.

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

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

---


## 📦 Installation

```bash
npm install @trap_stevo/rng
```

---


## 🛠️ Usage

### 🔧 Functional Mode

```js
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

```js
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](./LICENSE.md)

---


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