@trioforge/random 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @trioforge/random
+
+## 0.1.1
+
+### Patch Changes
+
+- [#6](https://github.com/Trio-Forge-Studio/packages/pull/6) [`dac820b`](https://github.com/Trio-Forge-Studio/packages/commit/dac820b44abb72c663f694c6125de44e1a1a8fcd) Thanks [@Hezaerd](https://github.com/Hezaerd)! - The source moved to [Trio-Forge-Studio/packages](https://github.com/Trio-Forge-Studio/packages), so the package's repository and issue links point there. The package now ships its `CHANGELOG.md`. The code is the same as the previous version.
+
+## 0.1.0
+
+### Minor Changes
+
+- First release. `Rng` is a seeded xoshiro128\*\* generator in plain Luau, so every client and server draws the same sequence from the same seed. It draws integers, floats, chances and normal values, and it picks by weight, shuffles and samples. A state can be saved, restored, cloned and forked. ([Trio-Forge-Studio/random#1](https://github.com/Trio-Forge-Studio/random/pull/1))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trio Forge Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,91 @@
-# Temporary Holding Version
+# @trioforge/random
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Seeded random numbers for roblox-ts. Every client and every server draws the same sequence from the same seed, today and after any engine update.
+
+Roblox's `Random` doesn't promise that. Its algorithm and `Random:Shuffle` belong to the engine and can change between versions, which matters as soon as a server and its clients must agree on a draw. This package runs [xoshiro128\*\*](https://prng.di.unimi.it/) in plain Luau instead, and checks it against the algorithm's reference output.
+
+## Install
+
+```sh
+pnpm add @trioforge/random
+```
+
+roblox-ts only looks for packages in the scopes your project lists, so add the `@trioforge` scope in two places.
+
+1. In `tsconfig.json`, add it to `typeRoots`:
+
+	```json
+	"typeRoots": ["node_modules/@rbxts", "node_modules/@trioforge"]
+	```
+
+2. In your Rojo project, map it beside `@rbxts` under `rbxts_include/node_modules`:
+
+	```json
+	"node_modules": {
+		"$className": "Folder",
+		"@rbxts": { "$path": "node_modules/@rbxts" },
+		"@trioforge": { "$path": "node_modules/@trioforge" }
+	}
+	```
+
+## Example
+
+```ts
+import { Rng } from "@trioforge/random";
+
+const rng = new Rng("chalet", 12345);
+
+print(rng.int(1, 6));
+// → 5
+print(rng.pick(["lamp", "vase", "clock"]));
+// → vase
+print(rng.shuffle([1, 2, 3, 4, 5]).join(" "));
+// → 5 4 1 2 3
+```
+
+## Seeds
+
+`new Rng(...seed)` takes any mix of strings and integers and hashes them into a 128-bit state. The same parts in the same order always give the same stream. Different parts give unrelated streams, so a seed can name what it's for:
+
+```ts
+import { Rng } from "@trioforge/random";
+
+const houseSeed = 2024;
+const furniture = new Rng("furniture", houseSeed);
+const weather = new Rng("weather", houseSeed);
+```
+
+The two streams above don't move together, and drawing from one never changes the other. Seed numbers must be integers within ±2^53. `new Rng()` with no parts seeds itself from the clock and `math.random`, for draws nobody needs to repeat.
+
+`fork()` takes four draws from a stream and seeds a new one from them. Hand a fork to a system that draws an unknown number of times, and the parent's sequence after it stays the same whatever the fork does.
+
+`state()` returns the four 32-bit words of the stream's position. `Rng.fromState(state)` resumes from them, so a server can save a stream or send it to clients. `clone()` copies a stream at its current position.
+
+## Draws
+
+| Method | Returns |
+| --- | --- |
+| `uint32()` | An integer from 0 to 2^32 − 1, the generator's raw output |
+| `float()` | A number in [0, 1) with 53 random bits |
+| `float(min, max)` | A number in [min, max) |
+| `int(min, max)` | An integer in [min, max], both inclusive, without modulo bias |
+| `chance(probability)` | `true` with the given probability |
+| `normal(mean?, deviation?)` | A normally distributed number, by default with mean 0 and deviation 1 |
+| `pick(items)` | One item |
+| `weightedIndex(weights)` | An index, chosen in proportion to its weight |
+| `weighted(items, weight)` | An item, chosen in proportion to `weight(item, index)` |
+| `shuffle(items)` | A shuffled copy. The array you pass stays as it was |
+| `sample(items, count)` | `count` distinct items, in the order they were drawn |
+
+Indices are 0-based, as everywhere in roblox-ts. Weights must be finite and non-negative, with a positive total. A zero weight is never chosen.
+
+```ts
+import { Rng } from "@trioforge/random";
+
+const rng = new Rng("loot", 7);
+const rarities = ["common", "rare", "epic"];
+print(rarities[rng.weightedIndex([80, 18, 2])]);
+// → common
+```
+
+Each method's sequence for a given state is part of the package's contract. A change that would draw differently from the same seed is a breaking change.

package/out/index.d.ts

@@ -0,0 +1,24 @@
+export type SeedPart = string | number;
+export type RngState = readonly [number, number, number, number];
+export declare class Rng {
+    private a;
+    private b;
+    private c;
+    private d;
+    constructor(...seed: SeedPart[]);
+    static fromState(state: RngState): Rng;
+    state(): RngState;
+    clone(): Rng;
+    fork(): Rng;
+    uint32(): number;
+    float(): number;
+    float(min: number, max: number): number;
+    int(min: number, max: number): number;
+    chance(probability: number): boolean;
+    normal(mean?: number, deviation?: number): number;
+    pick<T extends defined>(items: readonly T[]): T;
+    weightedIndex(weights: readonly number[]): number;
+    weighted<T extends defined>(items: readonly T[], weight: (item: T, index: number) => number): T;
+    shuffle<T extends defined>(items: readonly T[]): T[];
+    sample<T extends defined>(items: readonly T[], count: number): T[];
+}

package/out/init.luau

@@ -0,0 +1,301 @@
+-- Compiled with roblox-ts v3.0.0
+local WORD = 2 ^ 32
+local DOUBLE = 2 ^ 53
+-- Luau has no 32-bit multiply, and a full product of two words overflows a double's 53 bits, so it splits one side.
+local function imul(a, b)
+	local low = a * (b % 65536)
+	local high = ((a * math.floor(b / 65536)) % WORD) * 65536
+	return (low + high) % WORD
+end
+local function fmix(h)
+	h = imul(bit32.bxor(h, bit32.rshift(h, 16)), 0x85ebca6b)
+	h = imul(bit32.bxor(h, bit32.rshift(h, 13)), 0xc2b2ae35)
+	return bit32.bxor(h, bit32.rshift(h, 16))
+end
+local STRING = 0x5354524e
+local NUMBER = 0x4e554d42
+local function words(parts)
+	local result = { #parts }
+	for _, part in parts do
+		if type(part) == "string" then
+			local _arg1 = #part
+			-- ▼ Array.push ▼
+			table.insert(result, STRING)
+			table.insert(result, _arg1)
+			-- ▲ Array.push ▲
+			for index = 1, #part, 4 do
+				local a, b, c, d = string.byte(part, index, index + 3)
+				local _condition = a
+				if _condition == nil then
+					_condition = 0
+				end
+				local _condition_1 = b
+				if _condition_1 == nil then
+					_condition_1 = 0
+				end
+				local _exp = _condition + _condition_1 * 0x100
+				local _condition_2 = c
+				if _condition_2 == nil then
+					_condition_2 = 0
+				end
+				local _exp_1 = _exp + _condition_2 * 0x10000
+				local _condition_3 = d
+				if _condition_3 == nil then
+					_condition_3 = 0
+				end
+				table.insert(result, _exp_1 + _condition_3 * 0x1000000)
+			end
+		else
+			if part ~= part or part % 1 ~= 0 or math.abs(part) > DOUBLE then
+				error(`a seed number must be an integer within ±2^53, got {part}`, 3)
+			end
+			local _arg1 = part % WORD
+			local _arg2 = math.floor(part / WORD) % WORD
+			-- ▼ Array.push ▼
+			table.insert(result, NUMBER)
+			table.insert(result, _arg1)
+			table.insert(result, _arg2)
+			-- ▲ Array.push ▲
+		end
+	end
+	return result
+end
+local LANES = { 0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a }
+local function hashState(input)
+	-- ▼ ReadonlyArray.map ▼
+	local _newValue = table.create(#LANES)
+	local _callback = function(lane)
+		local h = lane
+		for _, word in input do
+			h = fmix((imul(bit32.bxor(h, word), 0x9e3779b1) + lane) % WORD)
+		end
+		return fmix(h)
+	end
+	for _k, _v in LANES do
+		_newValue[_k] = _callback(_v, _k - 1, LANES)
+	end
+	-- ▲ ReadonlyArray.map ▲
+	local state = _newValue
+	-- ▼ ReadonlyArray.every ▼
+	local _result = true
+	local _callback_1 = function(word)
+		return word == 0
+	end
+	for _k, _v in state do
+		if not _callback_1(_v, _k - 1, state) then
+			_result = false
+			break
+		end
+	end
+	-- ▲ ReadonlyArray.every ▲
+	if _result then
+		state[1] = 1
+	end
+	return { state[1], state[2], state[3], state[4] }
+end
+local function entropy()
+	return { math.random(0, 0xffff), math.random(0, 0xffff), math.random(0, 0xffff), math.floor(os.clock() * 1e6) % WORD }
+end
+local Rng
+do
+	Rng = setmetatable({}, {
+		__tostring = function()
+			return "Rng"
+		end,
+	})
+	Rng.__index = Rng
+	function Rng.new(...)
+		local self = setmetatable({}, Rng)
+		return self:constructor(...) or self
+	end
+	function Rng:constructor(...)
+		local seed = { ... }
+		local _binding = hashState(if #seed > 0 then words(seed) else entropy())
+		self.a = _binding[1]
+		self.b = _binding[2]
+		self.c = _binding[3]
+		self.d = _binding[4]
+	end
+	function Rng:fromState(state)
+		local rng = Rng.new(0)
+		for _, word in state do
+			if word % 1 ~= 0 or word < 0 or word >= WORD then
+				error(`a state word must be a uint32, got {word}`, 2)
+			end
+		end
+		-- ▼ ReadonlyArray.every ▼
+		local _result = true
+		local _callback = function(word)
+			return word == 0
+		end
+		for _k, _v in state do
+			if not _callback(_v, _k - 1, state) then
+				_result = false
+				break
+			end
+		end
+		-- ▲ ReadonlyArray.every ▲
+		if _result then
+			error("a state can't be all zeroes", 2)
+		end
+		local _binding = state
+		rng.a = _binding[1]
+		rng.b = _binding[2]
+		rng.c = _binding[3]
+		rng.d = _binding[4]
+		return rng
+	end
+	function Rng:state()
+		return { self.a, self.b, self.c, self.d }
+	end
+	function Rng:clone()
+		return Rng:fromState(self:state())
+	end
+	function Rng:fork()
+		return Rng.new(self:uint32(), self:uint32(), self:uint32(), self:uint32())
+	end
+	function Rng:uint32()
+		local result = (bit32.lrotate((self.b * 5) % WORD, 7) * 9) % WORD
+		local t = bit32.lshift(self.b, 9)
+		self.c = bit32.bxor(self.c, self.a)
+		self.d = bit32.bxor(self.d, self.b)
+		self.b = bit32.bxor(self.b, self.c)
+		self.a = bit32.bxor(self.a, self.d)
+		self.c = bit32.bxor(self.c, t)
+		self.d = bit32.lrotate(self.d, 11)
+		return result
+	end
+	function Rng:float(min, max)
+		local unit = (bit32.rshift(self:uint32(), 5) * 2 ^ 26 + bit32.rshift(self:uint32(), 6)) / DOUBLE
+		if min == nil or max == nil then
+			return unit
+		end
+		if not (min <= max) then
+			error(`float needs min <= max, got {min} and {max}`, 2)
+		end
+		return min + unit * (max - min)
+	end
+	function Rng:int(min, max)
+		if min % 1 ~= 0 or max % 1 ~= 0 then
+			error(`int needs integer bounds, got {min} and {max}`, 2)
+		end
+		local span = max - min + 1
+		if span < 1 then
+			error(`int needs min <= max, got {min} and {max}`, 2)
+		end
+		if span > WORD then
+			error(`int spans at most 2^32 values, got {span}`, 2)
+		end
+		local limit = WORD - (WORD % span)
+		local value = self:uint32()
+		while value >= limit do
+			value = self:uint32()
+		end
+		return min + (value % span)
+	end
+	function Rng:chance(probability)
+		return self:float() < probability
+	end
+	function Rng:normal(mean, deviation)
+		if mean == nil then
+			mean = 0
+		end
+		if deviation == nil then
+			deviation = 1
+		end
+		local radius = math.sqrt(-2 * math.log(1 - self:float()))
+		return mean + deviation * radius * math.cos(2 * math.pi * self:float())
+	end
+	function Rng:pick(items)
+		if #items == 0 then
+			error("can't pick from an empty array", 2)
+		end
+		return items[self:int(0, #items - 1) + 1]
+	end
+	function Rng:weightedIndex(weights)
+		local total = 0
+		for _, weight in weights do
+			if not (weight >= 0 and weight < math.huge) then
+				error(`a weight must be finite and non-negative, got {weight}`, 2)
+			end
+			total += weight
+		end
+		if total <= 0 then
+			error("weights must add up to more than zero", 2)
+		end
+		local roll = self:float() * total
+		local last = 0
+		for index = 0, #weights - 1 do
+			if weights[index + 1] <= 0 then
+				continue
+			end
+			last = index
+			roll -= weights[index + 1]
+			if roll < 0 then
+				return index
+			end
+		end
+		-- Rounding can leave a sliver of the roll past the last bucket.
+		return last
+	end
+	function Rng:weighted(items, weight)
+		local _exp = items
+		local _self = self
+		local _items = items
+		local _weight = weight
+		-- ▼ ReadonlyArray.map ▼
+		local _newValue = table.create(#_items)
+		for _k, _v in _items do
+			_newValue[_k] = _weight(_v, _k - 1, _items)
+		end
+		-- ▲ ReadonlyArray.map ▲
+		return _exp[_self:weightedIndex(_newValue) + 1]
+	end
+	function Rng:shuffle(items)
+		local _array = {}
+		local _length = #_array
+		table.move(items, 1, #items, _length + 1, _array)
+		local result = _array
+		for index = #result - 1, 1, -1 do
+			local other = self:int(0, index)
+			local _index = index + 1
+			local _index_1 = other + 1
+			result[_index], result[_index_1] = result[other + 1], result[index + 1]
+		end
+		return result
+	end
+	function Rng:sample(items, count)
+		if count % 1 ~= 0 or count < 0 or count > #items then
+			error(`sample needs a count from 0 to {#items}, got {count}`, 2)
+		end
+		local _array = {}
+		local _length = #_array
+		table.move(items, 1, #items, _length + 1, _array)
+		local pool = _array
+		local result = {}
+		do
+			local index = 0
+			local _shouldIncrement = false
+			while true do
+				if _shouldIncrement then
+					index += 1
+				else
+					_shouldIncrement = true
+				end
+				if not (index < count) then
+					break
+				end
+				local other = self:int(index, #pool - 1)
+				local _index = index + 1
+				local _index_1 = other + 1
+				pool[_index], pool[_index_1] = pool[other + 1], pool[index + 1]
+				local _arg0 = pool[index + 1]
+				table.insert(result, _arg0)
+			end
+		end
+		return result
+	end
+end
+return {
+	Rng = Rng,
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@trioforge/random",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Seeded, deterministic random numbers for roblox-ts that every client and server draws the same",
+  "keywords": [
+    "roblox",
+    "roblox-ts",
+    "random",
+    "rng",
+    "prng",
+    "seed",
+    "xoshiro"
+  ],
+  "bugs": "https://github.com/Trio-Forge-Studio/packages/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Trio-Forge-Studio/packages.git",
+    "directory": "packages/random"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "out/init.luau",
+  "types": "out/index.d.ts",
+  "files": [
+    "out",
+    "!**/*.tsbuildinfo",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@rbxts/compiler-types": "3.0.0-types.0",
+    "@rbxts/types": "^1.0.958",
+    "@types/node": "^24.19.2",
+    "roblox-ts": "^3.0.0",
+    "typescript": "5.5.3",
+    "vite-plus": "1.3.0"
+  },
+  "scripts": {
+    "build": "rbxtsc --type package",
+    "test": "vp test",
+    "check": "tsc -p test && vp test"
+  }
 }