{"id":"elentium/random","name":"random","scope":"elentium","platform":"roblox","description":"A high-performance, feature-complete randomization utility for Luau. This module is a heavily optimized rework of the original Random library, designed specifically for Roblox developers who require precision, speed, and advanced filtering like blacklisting and weighted distribution.","version":"2.1.0","latest":"2.1.0","versions":["2.0.5","2.0.6","2.0.51","2.0.52","2.0.53","2.0.61","2.0.62","2.1.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"8af2b6e32e0e40c5e5f3c098f343a4ffc679d1a695a45af65892c7ee9af6159a","likes":0,"downloads":0,"install":"forest install elentium/random","url":"https://forest.dev/p/roblox/elentium/random","files":"https://api.forest.dev/ai/package/roblox/elentium/random/files","readme":"# Random V2.1.0\n\nA high-performance, feature-complete randomization utility for **Roblox Luau**. This module is a heavily optimized rework of the original Random library, designed for Roblox developers who need speed, precision, and advanced filtering such as blacklisting and weighted distribution.\n\n---\n\n## Key Features\n\n* **Smart blacklisting:** Exclude specific values from random results without manual retry loops.\n* **Weighted choice:** Order-independent linear-scan algorithm for drop tables, rarities, and loot systems.\n* **Spatial randomization:** Dedicated methods for `Vector3`, `Vector2`, `CFrame`, and `UnitVector`.\n* **UI & visuals:** Easy generation for `Color3`, `UDim2` (offset), and `UDim2Scaled`.\n* **Fully typed:** Strict Luau types with generics, exported from a dedicated `Types` module.\n\n---\n\n## Installation\n\n### Wally\n\nAdd the following to your `wally.toml`:\n\n```toml\nRandom = \"elentium/random@2.1.0\"\n```\n\n### GitHub\n\nClone or download from [github.com/Elentium/Random](https://github.com/Elentium/Random).\n\n### Roblox Studio\n\nA pre-built insert model is available at `roblox-studio-insert/Random.rbxm`.\n\n---\n\n## Quick Start\n\n```luau\nlocal Random = require(path.to.Random)\n\nlocal rng = Random.new(12345)\n\nlocal roll = rng:Integer(1, 6)\nlocal chance = rng:Float(0, 1, 2)\nlocal item, key = rng:Choice({ sword = 10, shield = 5, potion = 1 })\nlocal position = rng:Vector3({ min = -10, max = 10 }, { min = 0, max = 5 }, { min = -10, max = 10 })\n```\n\nAlways call methods with `:` syntax (`rng:Integer(...)`, not `rng.Integer(...)`).\n\n---\n\n## API\n\n### `Random.new(seed: number?) -> RandomObject`\n\nCreates a random object. If `seed` is omitted, Roblox generates one internally.\n\n### Primitives\n\n| Method | Description |\n|--------|-------------|\n| `:Integer(min, max, blacklist?)` | Random integer in `[min, max]`, optionally excluding blacklisted values |\n| `:Float(min, max, precision?)` | Random float in `[min, max]`, optionally rounded to `precision` decimal places |\n\n### Choice\n\n| Method | Description |\n|--------|-------------|\n| `:Choice(container, blacklist?)` | Picks a random key from a map or array; returns `(value, key)` |\n| `:BlazeChoice(container)` | Fast array-only choice; returns `(value, index)` |\n| `:ChooseMultiple(container, amount, blacklist?, allowDuplicates?)` | Picks multiple entries; returns a map of chosen key-value pairs |\n| `:WeightedChoice(container, totalWeight)` | Weighted pick from `{ { weight, item }, ... }`; returns `(item, weight)` |\n\n### Roblox Types\n\n| Method | Description |\n|--------|-------------|\n| `:Vector3(x, y, z, precision?)` | Random `Vector3` from axis ranges |\n| `:Vector2(x, y, precision?)` | Random `Vector2` from axis ranges |\n| `:UnitVector()` | Random unit direction as `Vector3` |\n| `:Color3()` | Random `Color3` with RGB in `[0, 1]` |\n| `:UDim2(x, y)` | Random offset `UDim2` from integer ranges |\n| `:UDim2Scaled(x, y, precision?)` | Random scale `UDim2` from float ranges |\n| `:CFrame(position, allowedAxes?, precision?)` | Random position and optional rotation |\n\n`Range` is `{ min: number, max: number }`. For `:CFrame`, `position` is `{ x: Range, y: Range, z: Range }`.\n\n### Object lifecycle\n\n| Method | Description |\n|--------|-------------|\n| `:Clone()` | Clones the object and its internal `Random` instance |\n| `:Destroy()` | Clears the object and removes its metatable |\n\n---\n\n## Warnings\n\n* Avoid heavy blacklists on `:Integer` when more than ~90% of the range is excluded — performance degrades significantly. `:Choice` and `:ChooseMultiple` are not affected the same way.\n* Always use `:` method syntax on `RandomObject` instances.\n* `min` must not be greater than `max`.\n\n---\n\n## Benchmarks\n\nA benchmark harness lives in `bench/` and is mapped in `default.project.json` as `Benchmark`. Run it from Studio to compare method performance on your target environment.\n\n---\n\n## Changelog\n\n### 2.1.0\n\n* Improved code organization with a separate `Types` module\n* Improved Luau types (generics, `{ [K]: V }` table syntax)\n* Performance improvements (including reservoir sampling for `:Choice`)\n* `Vector3` and `UnitVector` now return `Vector3` via `Vector3.new`\n\n### 2.0.6\n\n* Fixed typos and small inconsistencies\n\n### 2.0.5\n\n* Added `RandomObject:WeightedChoice`\n* Published Wally package\n\n### 2.0.0\n\n* Major performance improvements\n* Cleaner API and documentation\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","readmeTruncated":false}