# pxstud.io Lua scripting API — Random

> Part of the pxstud.io Lua scripting reference, whose overview (https://pxstud.io/docs/scripting.md) explains its conventions. The option groups and types it refers to are in https://pxstud.io/docs/scripting/option-groups.md and https://pxstud.io/docs/scripting/types.md. Everything in one file: https://pxstud.io/llms-full.txt. The whole site's index: https://pxstud.io/llms.txt.

### Random
Seeded random numbers, computed inside the script (no round trip per call). The same seed gives the same results, so a script can be re-run, undone and redone, or shared, and look identical. Prefer these to math.random, which differs on every run. Generators are objects: call their methods with a colon (rng:int(1, 6)).

#### `app.random.hash(x, y, seed?)` — pure
A stateless float in [0, 1) from integer inputs (an integer avalanche hash): the same (x, y, seed) always gives the same value, in any order. For per-pixel noise or dithering without a generator.

- `x` (number) — Integer (floored).
- `y` (number) — Integer (floored).
- `seed` (number, optional) — Default 0.

Returns (number): A float, 0 <= x < 1.

#### `app.random.new(seed)` — pure
Creates a seeded random generator (mulberry32, the same algorithm the editor's spray and jumble use). The same seed always gives the same sequence. Prefer it to math.random, which is different on every run. Use the methods with a colon: local rng = app.random.new(app.config.seed); rng:int(1, 6).

- `seed` (number) — An integer 0-4294967295. Floats are floored; anything else is reduced to 32 bits.

Returns (table): A generator object; call its methods with a colon.

#### `app.random.seed()` — pure
A fresh random integer seed, 0-4294967295. NOT deterministic: it differs on every run, so print it or store it if you want to reproduce the result. Use it when the user leaves the seed field empty: app.random.new(app.config.seed or app.random.seed()).

Returns (number): An integer 0-4294967295.

#### `rng:chance(p)` — pure
true with probability p.

- `p` (number) — Probability 0-1.

Returns (boolean): true or false.

#### `rng:fork(label)` — pure
An independent child generator derived deterministically from this generator's current state and the label, WITHOUT advancing this one. Give each feature its own fork (rng:fork("leaves")) so adding a feature doesn't change every later roll. Forking twice at the same point with the same label gives identical children.

- `label` (string) — A string or a number naming the child.

Returns (table): A generator object; call its methods with a colon.

#### `rng:int(lo, hi)` — pure
A random integer from lo to hi, both included.

- `lo` (number) — Smallest result (floored).
- `hi` (number) — Largest result, inclusive (floored); at least lo.

Returns (number): An integer, lo <= x <= hi.

#### `rng:next()` — pure
The next float in [0, 1).

Returns (number): A float, 0 <= x < 1.

#### `rng:normal(mean?, sd?)` — pure
A normally distributed float (Box-Muller). Uses two rolls per call.

- `mean` (number, optional) — Default 0.
- `sd` (number, optional) — Standard deviation; default 1.

Returns (number): A float around mean.

#### `rng:pick(list)` — pure
A random element of the list; nil for an empty list (and the generator isn't advanced).

- `list` (table) — A list (1..#list).

Returns (table): One element of the list, or nil.

#### `rng:range(a, b)` — pure
A random float from a up to (not including) b.

- `a` (number)
- `b` (number)

Returns (number): A float in [a, b).

#### `rng:shuffle(list)` — pure
A new list with the same elements in random order (Fisher-Yates). The input list is not changed.

- `list` (table) — A list (1..#list).

Returns (table): A new shuffled list.