Add new_instance

Author: aglitchman

README.md

@@ -52,7 +52,7 @@ _RETURNS_
 * __value__ - Random element from the array.
 
 ### splitmix64.weightedchoice(t)
-Takes table `t` where keys are choices and values are weights. Returns a random key. Weights must be ≥ 0. If all weights are 0 or a weight is negative, an error is raised.
+Takes table `t` where keys are choices and values are weights. Returns a random key. Keys are sorted deterministically (numbers first, then strings lexicographically) before selection, so the result is reproducible for the same seed across all platforms. Weights must be ≥ 0. If all weights are 0 or a weight is negative, an error is raised.
 
 _PARAMETERS_
 * __t__ <kbd>table</kbd> - Table of key-weight pairs.
@@ -110,6 +110,34 @@ local state = splitmix64.state()
 splitmix64.randomseed(state)  -- restore exact state
 ```
 
+### splitmix64.new_instance([seed])
+Creates a new independent RNG instance. Each instance has its own internal state, completely isolated from the global module state and from other instances. This allows running multiple RNG streams in parallel without interference.
+
+_PARAMETERS_
+* __seed__ <kbd>number</kbd> or <kbd>string</kbd> _(optional)_ — Initial seed for the instance. Defaults to 0.
+
+_RETURNS_
+* __rng__ <kbd>table</kbd> — A table with the same set of functions as the module: `random`, `randomseed`, `state`, `randomchoice`, `weightedchoice`, `toss`, `dice`.
+
+#### Example
+
+```lua
+-- Create two independent generators
+local rng_enemies = splitmix64.new_instance(42)
+local rng_loot = splitmix64.new_instance(999)
+
+-- Each has its own state — they don't affect each other or the global module
+print(rng_enemies.random(1, 100))
+print(rng_loot.random(1, 100))
+
+-- The global state is unchanged
+print(splitmix64.random())
+
+-- Save/restore instance state
+local saved = rng_enemies.state()
+rng_enemies.randomseed(saved)
+```
+
 ### Advanced Usage
 
 You can also globally substitute the built-in `math.random` with `splitmix64`:

example/example.script

@@ -1,10 +1,27 @@
 local TINT_GREEN = vmath.vector4(0.3, 0.9, 0.3, 1)
 local TINT_RED = vmath.vector4(0.9, 0.3, 0.3, 1)
 local EPSILON = 0.00001
-local html5 = sys.get_sys_info().system_name == "HTML5"
 
 function init(self)
     msg.post("@render:", "use_fixed_fit_projection", { near = -1, far = 1 })
+
+    splitmix64.randomseed(123456)
+    local saved_state = splitmix64.state()
+
+    local rng = splitmix64.new_instance(42)
+    assert(math.abs(rng.random() - 0.74156487877182) < EPSILON, "rng.random() mismatch")
+    assert(rng.random(1, 100) == 92, "rng.random(1, 100) mismatch")
+    rng.randomseed(999)
+    assert(rng.state() == "999", "rng.state() mismatch")
+    assert(rng.randomchoice({"a", "b", "c"}) == "b", "rng.randomchoice mismatch")
+    assert(rng.weightedchoice({red = 1, blue = 2, green = 3}) == "red", "rng.weightedchoice mismatch")
+    assert(rng.toss() == 0, "rng.toss() mismatch")
+    local rolls, total = rng.dice(2, splitmix64.D6)
+    assert(rolls[1] == 4 and rolls[2] == 3, "rng.dice rolls mismatch")
+    assert(total == 7, "rng.dice total mismatch")
+
+    assert(saved_state == splitmix64.state(), "module state changed by new_instance calls")
+    print("new_instance test passed: module state unchanged")
 end
 
 local function equal_rng(actual, expected, label_url)

splitmix64/api/splitmix64.script_api

@@ -42,7 +42,7 @@
       desc: Random element from the array.
   - name: weightedchoice
     type: function
-    desc: Takes table t where keys are choices and values are weights. Returns a random key. Weights must be >= 0. If all weights are 0 or a weight is negative, an error is raised.
+    desc: Takes table t where keys are choices and values are weights. Returns a random key. Keys are sorted deterministically (numbers first, then strings lexicographically) before selection, so the result is reproducible for the same seed. Weights must be >= 0. If all weights are 0 or a weight is negative, an error is raised.
     parameters:
     - name: t
       type: table
@@ -58,6 +58,18 @@
     - name: value
       type: number
       desc: Returns 0 or 1.
+  - name: new_instance
+    type: function
+    desc: Creates a new RNG instance with independent state. Optional seed (number or string) for reproducibility.
+    parameters:
+    - name: seed
+      optional: true
+      type: number|string
+      desc: Optional seed for the new instance.
+    returns:
+    - name: rng
+      type: userdata
+      desc: RNG instance with methods random, randomseed, state, randomchoice, weightedchoice, toss, dice. Same API as the module but with isolated state.
   - name: dice
     type: function
     desc: Roll one or more dice of the given type. Returns a table of individual rolls and the total sum.