Skip to main content

DebugRandom

A wrapper around Roblox's Random class that enables users to serialize and set the state of the Random object.

API differences:

Example use: Serialize a random number generator's state when an error occurs, so the error can be replicated using DebugRandom:SetSerializedState and DebugRandom.deserialize.

Types​

SerializedDebugRandom​

</>
type SerializedDebugRandom = {
ClassName: "DebugRandom",
Seed: number,
NumCount: number,
IntCount: number,
}

Properties​

ClassName​

This item is read only and cannot be modified. Read OnlyPrototype Property
</>
DebugRandom.ClassName: "DebugRandom"

Functions​

isDebugRandom​

</>
DebugRandom.isDebugRandom(obj: any) → boolean

Returns true if obj is a DebugRandom.

new​

</>
DebugRandom.new(seed: number?) → DebugRandom

Returns a new DebugRandom object.

deserialize​

</>
DebugRandom.deserialize(data: SerializedDebugRandom) → DebugRandom

Deserializes the data into a DebugRandom object. This data should have come from the DebugRandom:Serialize() method.

fromString​

</>
DebugRandom.fromString(data: string) → DebugRandom

Deserializes a string into a DebugRandom object. The string should have come from the DebugRandom:__tostring() metamethod.

Usage:

local rng = DebugRandom.new()
print(rng:NextNumber())

local str = tostring(rng)
local rngClone = DebugRandom.fromString(str)
assert(rngClone == rng)

__tostring​

</>
DebugRandom:__tostring() → string

This metamethod serializes self and transforms it into a string.

__eq​

</>
DebugRandom:__eq(other: DebugRandom) → boolean

This metamethod tests for self and other values to be equal and is used by the operators == and ~=.

Serialize​

</>
DebugRandom:Serialize() → SerializedDebugRandom

Returns a serialized version of the DebugRandom.

SetSerializedState​

</>
DebugRandom:SetSerializedState(data: SerializedDebugRandom) → ()

Set the DebugRandom's state. This state should have come from the DebugRandom:Serialize() method.

CopyStateFrom​

</>
DebugRandom:CopyStateFrom(other: DebugRandom) → ()

Set the state of the calling DebugRandom to the state of the other DebugRandom.

NextInteger​

</>
DebugRandom:NextInteger(
min: number,
max: number
) → number

Returns a pseudorandom integer uniformly distributed over [min, max].

NextNumber​

</>
DebugRandom:NextNumber() → number

Returns a pseudorandom number uniformly distributed over [0, 1).

NextNumber​

</>
DebugRandom:NextNumber(
min: number,
max: number
) → number

Returns a pseudorandom number uniformly distributed over [min, max).

NextUnitVector​

</>
DebugRandom:NextUnitVector() → Vector3

Returns a unit vector with a pseudorandom direction. Vectors returned from this function are uniformly distributed over the unit sphere.

Shuffle​

</>
DebugRandom:Shuffle(tb: table) → ()

Uniformly shuffles the array part of tb in-place using NextInteger to pick indices. If there are any nil "holes" in the array part of the table, Shuffle throws an error, since shuffling could change the length.

The hash part of tb is ignored. No metamethods of tb are invoked.

The shuffle is defined to be a Fisher-Yates shuffle so the number of NextInteger calls is guaranteed to be consistent between engine versions for a given size of table.

Clone​

</>
DebugRandom:Clone() → DebugRandom

Returns a new DebugRandom object with the same state as the original.

CloneRandom​

</>
DebugRandom:CloneRandom() → Random

Returns a clone of the DebugRandom's internal Random object.

Show raw api
{
    "functions": [
        {
            "name": "isDebugRandom",
            "desc": "Returns `true` if `obj` is a DebugRandom.",
            "params": [
                {
                    "name": "obj",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 82,
                "path": "src/init.luau"
            }
        },
        {
            "name": "new",
            "desc": "Returns a new DebugRandom object.",
            "params": [
                {
                    "name": "seed",
                    "desc": "",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "DebugRandom\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 91,
                "path": "src/init.luau"
            }
        },
        {
            "name": "deserialize",
            "desc": "Deserializes the data into a DebugRandom object. This data should have come from\nthe `DebugRandom:Serialize()` method.",
            "params": [
                {
                    "name": "data",
                    "desc": "",
                    "lua_type": "SerializedDebugRandom"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "DebugRandom\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 129,
                "path": "src/init.luau"
            }
        },
        {
            "name": "fromString",
            "desc": "Deserializes a string into a DebugRandom object. The string should have come from the `DebugRandom:__tostring()` metamethod.\n\n**Usage:**\n```lua\nlocal rng = DebugRandom.new()\nprint(rng:NextNumber())\n\nlocal str = tostring(rng)\nlocal rngClone = DebugRandom.fromString(str)\nassert(rngClone == rng)\n```",
            "params": [
                {
                    "name": "data",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "DebugRandom\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 164,
                "path": "src/init.luau"
            }
        },
        {
            "name": "__tostring",
            "desc": "This metamethod serializes `self` and transforms it into a string.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 182,
                "path": "src/init.luau"
            }
        },
        {
            "name": "__eq",
            "desc": "This metamethod tests for `self` and `other` values to be equal and is used by the operators `==` and `~=`.",
            "params": [
                {
                    "name": "other",
                    "desc": "",
                    "lua_type": "DebugRandom"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 198,
                "path": "src/init.luau"
            }
        },
        {
            "name": "Serialize",
            "desc": "Returns a serialized version of the DebugRandom.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "SerializedDebugRandom"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 209,
                "path": "src/init.luau"
            }
        },
        {
            "name": "SetSerializedState",
            "desc": "Set the DebugRandom's state. This state should have come from\nthe `DebugRandom:Serialize()` method.",
            "params": [
                {
                    "name": "data",
                    "desc": "",
                    "lua_type": "SerializedDebugRandom"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 226,
                "path": "src/init.luau"
            }
        },
        {
            "name": "CopyStateFrom",
            "desc": "Set the state of the calling DebugRandom to the state of the `other` DebugRandom.",
            "params": [
                {
                    "name": "other",
                    "desc": "",
                    "lua_type": "DebugRandom"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 262,
                "path": "src/init.luau"
            }
        },
        {
            "name": "NextInteger",
            "desc": "Returns a pseudorandom integer uniformly distributed over [min, max].",
            "params": [
                {
                    "name": "min",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "max",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 279,
                "path": "src/init.luau"
            }
        },
        {
            "name": "NextNumber",
            "desc": "Returns a pseudorandom number uniformly distributed over [0, 1).",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 293,
                "path": "src/init.luau"
            }
        },
        {
            "name": "NextNumber",
            "desc": "Returns a pseudorandom number uniformly distributed over [min, max).",
            "params": [
                {
                    "name": "min",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "max",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 303,
                "path": "src/init.luau"
            }
        },
        {
            "name": "NextUnitVector",
            "desc": "Returns a unit vector with a pseudorandom direction. Vectors returned from this function are uniformly distributed over the unit sphere.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 318,
                "path": "src/init.luau"
            }
        },
        {
            "name": "Shuffle",
            "desc": "Uniformly shuffles the array part of tb in-place using NextInteger to pick indices. If there are any nil \"holes\" in the array part of the table, Shuffle throws an error, since shuffling could change the length.\n\nThe hash part of tb is ignored. No metamethods of tb are invoked.\n\nThe shuffle is defined to be a Fisher-Yates shuffle so the number of NextInteger calls is guaranteed to be consistent between engine versions for a given size of table.",
            "params": [
                {
                    "name": "tb",
                    "desc": "",
                    "lua_type": "table"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 335,
                "path": "src/init.luau"
            }
        },
        {
            "name": "Clone",
            "desc": "Returns a new DebugRandom object with the same state as the original.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "DebugRandom"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 347,
                "path": "src/init.luau"
            }
        },
        {
            "name": "CloneRandom",
            "desc": "Returns a clone of the DebugRandom's internal Random object.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Random"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 364,
                "path": "src/init.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "ClassName",
            "desc": "",
            "lua_type": "\"DebugRandom\"",
            "tags": [
                "Prototype Property"
            ],
            "readonly": true,
            "source": {
                "line": 61,
                "path": "src/init.luau"
            }
        }
    ],
    "types": [
        {
            "name": "SerializedDebugRandom",
            "desc": "",
            "lua_type": "{ClassName: \"DebugRandom\", Seed: number, NumCount: number, IntCount: number,}",
            "source": {
                "line": 115,
                "path": "src/init.luau"
            }
        }
    ],
    "name": "DebugRandom",
    "desc": "A wrapper around Roblox's [Random](https://create.roblox.com/docs/reference/engine/datatypes/Random) class\nthat enables users to serialize and set the state of the Random object.\n\nAPI differences:\n- Added [DebugRandom.deserialize]\n- Added [DebugRandom.fromString]\n- Added [DebugRandom.isDebugRandom]\n- Added property [ClassName](#ClassName)\n- [DebugRandom:__tostring] yields a serialized result instead of \"Random\"\n- Added [DebugRandom:Serialize]\n- Added [DebugRandom:SetSerializedState]\n- Added [DebugRandom:CopyStateFrom]\n- Added [DebugRandom:CloneRandom]\n\nExample use:\nSerialize a random number generator's state when an error occurs, so the error can be replicated\nusing [DebugRandom:SetSerializedState] and [DebugRandom.deserialize].",
    "source": {
        "line": 55,
        "path": "src/init.luau"
    }
}