Skip to main content

RandomUtils

Utility functions involving random variables. This is quite useful for a variety of game mechanics.

tip

Each method generally takes a random object in as the last argument, which can be used to seed the randomness. This is especially useful for reproducting state in testing.

Functions​

choice​

</>
RandomUtils.choice(
list: {T},
random: Random?--

Optional

) → T?

Picks an option from a list. Returns nil if the list is empty.

local options = Players:GetPlayers()
local choice = RandomUtils.choice(options)
print(choice)

Deterministic version:

local options = { "apples", "oranges", "bananas" }
local random = Random.new()

print(RandomUtils.choice(options, random)) --> "apples"

shuffledCopy​

</>
RandomUtils.shuffledCopy(
list: {T},--

A new table to copy

random: Random?--

Optional random to use when shuffling

) → {T}

Creates a copy of the table, but shuffled using fisher-yates shuffle

local options = { "apples", "oranges", "bananas" }
local random = Random.new()

print(RandomUtils.shuffledCopy(options)) --> shuffled copy of table
print(RandomUtils.shuffledCopy(options, random)) --> deterministic shuffled copy of table

shuffle​

</>
RandomUtils.shuffle(
list: {T},
random: Random?--

Optional random to use when shuffling

) → ()

Shuffles the list in place using fisher-yates shuffle.

local options = { "apples", "oranges", "bananas" }
local random = Random.new()

RandomUtils.shuffle(options, random)
print(options) --> deterministic shuffled copy of table

RandomUtils.shuffle(options)
print(options) --> shuffled table

weightedChoice​

</>
RandomUtils.weightedChoice(
list: {T},--

List of options

weights: {number},--

Array the same length with weights.

random: Random?--

Optional random

) → T?--

May return nil if the list is empty

Like RandomUtils.choice but weighted options in a performance friendly way. Takes O(n) time.

warning

A weight of 0 may still be picked, and negative weights may result in undefined behavior. 

local weights = { 1, 3, 10 }
local options = { "a", "b", "c" }

print(RandomUtils.weightedChoice(options, weights)) --> "c"

gaussianRandom​

</>
RandomUtils.gaussianRandom(
random: Random?--

Optional random to use

) → number

Computes the gaussian random function which is the independent probability curve.

randomUnitVector3​

</>
RandomUtils.randomUnitVector3(
random?: Random?--

Optional random to use

) → Vector3
Show raw api
{
    "functions": [
        {
            "name": "choice",
            "desc": "Picks an option from a list. Returns nil if the list is empty.\n\n```lua\nlocal options = Players:GetPlayers()\nlocal choice = RandomUtils.choice(options)\nprint(choice)\n```\n\nDeterministic version:\n```lua\nlocal options = { \"apples\", \"oranges\", \"bananas\" }\nlocal random = Random.new()\n\nprint(RandomUtils.choice(options, random)) --> \"apples\"\n```",
            "params": [
                {
                    "name": "list",
                    "desc": "",
                    "lua_type": "{ T }"
                },
                {
                    "name": "random",
                    "desc": "Optional",
                    "lua_type": "Random?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "T?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 37,
                "path": "src/randomutils/src/Shared/RandomUtils.lua"
            }
        },
        {
            "name": "shuffledCopy",
            "desc": "Creates a copy of the table, but shuffled using fisher-yates shuffle\n\n```lua\nlocal options = { \"apples\", \"oranges\", \"bananas\" }\nlocal random = Random.new()\n\nprint(RandomUtils.shuffledCopy(options)) --> shuffled copy of table\nprint(RandomUtils.shuffledCopy(options, random)) --> deterministic shuffled copy of table\n```",
            "params": [
                {
                    "name": "list",
                    "desc": "A new table to copy",
                    "lua_type": "{ T }"
                },
                {
                    "name": "random",
                    "desc": "Optional random to use when shuffling",
                    "lua_type": "Random?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ T }"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 66,
                "path": "src/randomutils/src/Shared/RandomUtils.lua"
            }
        },
        {
            "name": "shuffle",
            "desc": "Shuffles the list in place using fisher-yates shuffle.\n\n```lua\nlocal options = { \"apples\", \"oranges\", \"bananas\" }\nlocal random = Random.new()\n\nRandomUtils.shuffle(options, random)\nprint(options) --> deterministic shuffled copy of table\n\nRandomUtils.shuffle(options)\nprint(options) --> shuffled table\n```",
            "params": [
                {
                    "name": "list",
                    "desc": "",
                    "lua_type": "{T}"
                },
                {
                    "name": "random",
                    "desc": "Optional random to use when shuffling",
                    "lua_type": "Random?"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 91,
                "path": "src/randomutils/src/Shared/RandomUtils.lua"
            }
        },
        {
            "name": "weightedChoice",
            "desc": "Like [RandomUtils.choice] but weighted options in a\nperformance friendly way. Takes O(n) time.\n\n:::warning\nA weight of 0 may still be picked, and negative weights may result in\nundefined behavior.\n:::\n\n```lua\nlocal weights = { 1, 3, 10 }\nlocal options = { \"a\", \"b\", \"c\" }\n\nprint(RandomUtils.weightedChoice(options, weights)) --> \"c\"\n```",
            "params": [
                {
                    "name": "list",
                    "desc": "List of options",
                    "lua_type": "{ T }"
                },
                {
                    "name": "weights",
                    "desc": "Array the same length with weights.",
                    "lua_type": "{ number }"
                },
                {
                    "name": "random",
                    "desc": "Optional random",
                    "lua_type": "Random?"
                }
            ],
            "returns": [
                {
                    "desc": "May return nil if the list is empty",
                    "lua_type": "T?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 126,
                "path": "src/randomutils/src/Shared/RandomUtils.lua"
            }
        },
        {
            "name": "gaussianRandom",
            "desc": "Computes the gaussian random function which is the independent probability curve.",
            "params": [
                {
                    "name": "random",
                    "desc": "Optional random to use",
                    "lua_type": "Random?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 170,
                "path": "src/randomutils/src/Shared/RandomUtils.lua"
            }
        },
        {
            "name": "randomUnitVector3",
            "desc": "",
            "params": [
                {
                    "name": "random?",
                    "desc": "Optional random to use",
                    "lua_type": "Random?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 187,
                "path": "src/randomutils/src/Shared/RandomUtils.lua"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "RandomUtils",
    "desc": "Utility functions involving random variables. This is quite useful\nfor a variety of game mechanics.\n\n:::tip\nEach method generally takes a random object in as the last argument,\nwhich can be used to seed the randomness. This is especially useful for\nreproducting state in testing.\n:::",
    "source": {
        "line": 13,
        "path": "src/randomutils/src/Shared/RandomUtils.lua"
    }
}