> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rollingquest.kramgames.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Random — Seeded Random Number Generation in RollingQuest

> Reference for the Random class in RollingQuest Lua scripts. Covers seeded constructors, nextInteger, nextNumber, shuffle, nextElement, and serialization.

The `Random` class provides a seeded pseudo-random number generator you can use wherever you need unpredictable variety — spawning enemies, picking dialog lines, shuffling loot tables, or adding jitter to movement. Because each `Random` instance carries its own internal state, you can seed it with an integer or string to reproduce the same sequence across runs (great for procedural generation), or omit the seed to get a fresh random sequence every time. The state can also be serialised and deserialised, so you can save and restore a generator's position in its sequence across sessions.

## Constructors

```lua theme={null}
-- Unseeded — different sequence every run
local rng = Random.new()

-- Seeded with an integer — reproducible sequence
local seededRng = Random.new(42)

-- Seeded with a string
local namedRng = Random.new("level_3_seed")
```

| Signature                   | Description                                      |
| --------------------------- | ------------------------------------------------ |
| `Random.new()`              | Creates a generator with a random seed.          |
| `Random.new(seed: integer)` | Creates a generator with the given integer seed. |
| `Random.new(seed: string)`  | Creates a generator with the given string seed.  |

***

## Instance Methods

### `nextInteger`

Returns a random integer. Without arguments the range is `[1, max_integer]`. With one argument the range is `[1, maxInclusive]`. With two arguments the range is `[minInclusive, maxInclusive]`.

```lua theme={null}
--- @return integer
function Random:nextInteger()

--- @param maxInclusive integer
--- @return integer
function Random:nextInteger(maxInclusive)

--- @param minInclusive integer
--- @param maxInclusive integer
--- @return integer
function Random:nextInteger(minInclusive, maxInclusive)
```

### `nextNumber`

Returns a random floating-point number. Without arguments the range is `[0, 1)`. With one argument the range is `[0, maxExclusive)`. With two arguments the range is `[minInclusive, maxExclusive)`.

```lua theme={null}
--- @return number
function Random:nextNumber()

--- @param maxExclusive number
--- @return number
function Random:nextNumber(maxExclusive)

--- @param minInclusive number
--- @param maxExclusive number
--- @return number
function Random:nextNumber(minInclusive, maxExclusive)
```

### `nextGaussian`

Returns a random number drawn from a standard Gaussian (normal) distribution with mean 0 and standard deviation 1. Useful for adding natural-feeling variation.

```lua theme={null}
--- @return number
function Random:nextGaussian()
```

### `nextBoolean`

Returns `true` or `false` with equal probability.

```lua theme={null}
--- @return boolean
function Random:nextBoolean()
```

### `nextElement`

Returns a random element from the given table (array portion).

```lua theme={null}
--- @param table table
--- @return any
function Random:nextElement(table)
```

### `nextIndex`

Returns a random integer index into the given table (array portion).

```lua theme={null}
--- @param table table
--- @return integer
function Random:nextIndex(table)
```

### `shuffle`

Shuffles the elements of the given table in place using a Fisher-Yates algorithm seeded by this generator.

```lua theme={null}
--- @param table table
function Random:shuffle(table)
```

### `serializeToTable`

Captures the current generator state into a plain Lua table for persistence.

```lua theme={null}
--- @return table
function Random:serializeToTable()
```

### `serialize`

Captures the current generator state into a `LocalObject` for persistence.

```lua theme={null}
--- @return LocalObject
function Random:serialize()
```

***

## Static Methods

### `randomSeed`

Returns a fresh random integer that you can pass to `Random.new` to seed a new generator.

```lua theme={null}
--- @return integer
function Random.randomSeed()
```

### `randomStringSeed`

Returns a fresh random string suitable for use as a string seed.

```lua theme={null}
--- @return string
function Random.randomStringSeed()
```

### `deserializeFromTable`

Reconstructs a `Random` instance from a table previously produced by `serializeToTable`.

```lua theme={null}
--- @param table table
--- @return Random
function Random.deserializeFromTable(table)
```

### `deserialize`

Reconstructs a `Random` instance from a `LocalObject` previously produced by `serialize`.

```lua theme={null}
--- @param obj LocalObject
--- @return Random
function Random.deserialize(obj)
```

***

## Usage Examples

### Randomly enabling enemies at spawn

```lua theme={null}
local rng = Random.new()

local enemies = { enemy1, enemy2, enemy3, enemy4, enemy5 }

for _, enemy in ipairs(enemies) do
    -- Each enemy has a 60 % chance to be active at the start
    enemy.active = rng:nextNumber() < 0.6
end
```

### Random dialog choice

```lua theme={null}
local rng = Random.new()

local lines = {
    "The winds carry ill omens today.",
    "I wouldn't go that way if I were you.",
    "Have you spoken to the elder yet?",
    "Strange lights were seen near the ruins last night.",
}

function OnInteract()
    local chosen = rng:nextElement(lines)
    Dialog.show({ text = chosen })
end
```

### Shuffling a loot table

```lua theme={null}
local rng = Random.new()

local loot = { "sword", "shield", "potion", "gold", "key" }
rng:shuffle(loot)

-- Give the player the first two items after the shuffle
giveItem(player, loot[1])
giveItem(player, loot[2])
```

### Reproducible generation with a fixed seed

```lua theme={null}
-- Using the same seed always produces the same dungeon layout
local dungeonRng = Random.new("dungeon_floor_7")

local roomCount = dungeonRng:nextInteger(5, 12)
print("Rooms this floor: " .. tostring(roomCount))
```

### Saving and restoring generator state

```lua theme={null}
-- Capture the state mid-sequence
local savedState = rng:serializeToTable()

-- … later, restore and continue from the exact same point
local restoredRng = Random.deserializeFromTable(savedState)
```