Skip to main content

Leaderboard

Leaderboard allows you to create a leaderboard that can be used to store and retrieve data for a specific service key.

For example:

local Leaderboard = require(game:GetService("ReplicatedStorage").Leaderboard);
local MoneyLeaderboard = Leaderboard.new({
	Daily = "DailyMoneyKey1",
	Weekly = "WeeklyMoneyKey1"
});

Types​

Leaderboard​

</>
type Leaderboard = () → Leaderboard

LeaderboardType​

</>
type LeaderboardType = "Hourly" | "Daily" | "Weekly" | "Monthly" | "Yearly" | "AllTime" | string;

LeaderboardArguments​

</>
interface LeaderboardArguments {
Updated: Signal<{AllTopData}>
BoardUpdated: Signal<{
Type: LeaderboardType,
Data: {TopData}
}>
_serviceKey: string
_boards: {[LeaderboardType]: Board}
_valueQueue: ValueQueueType
_isSaving: {[LeaderboardType]: boolean}
_lastSaved: number
_isFetching: boolean
_lastFetch: number
_logger: Logger.Logger?
}

OperationType​

</>
type OperationType = "Set" | "Increment"

The type of operation to perform on the leaderboard value.

  • "Set": Sets the value to the specified amount or result of the transform function
  • "Increment": Adds the specified amount or result of the transform function to the current value

Board​

</>
interface Board {
GetRecords: (
self: Board,
amount: number,
sortDirection: string
) → Promise.TypedPromise<{TopData}>
Update: (
self: Board,
userId: number,
value: number | (number) → (number)
) → boolean
Destroy: (self: Board) → ()
}

Object​

</>
interface Object {
IncrementValues: (
self: Leaderboard,
boardTypes: {LeaderboardType} | string,
userId: number,
amount: number
) → ()
SetValues: (
self: Leaderboard,
boardTypes: {LeaderboardType} | string,
userId: number,
value: number | (number) → (number)
) → ()
UpdateStoreValues: (
self: Leaderboard,
boardTypes: {LeaderboardType} | string,
userId: number,
value: number | (number) → (number)
) → ()
GetRecords: (
self: Leaderboard,
boardTypes: {LeaderboardType} | string,
optionalRange: {[LeaderboardType | string]: number} | number,
sortDirection: string
) → Promise.TypedPromise<{AllTopData}>
SaveValues: (
self: Leaderboard,
boardType: LeaderboardType?
) → Promise.TypedPromise<number>
Destroy: (self: Leaderboard) → ()
new: (
leaderboardTypes: LeaderboardTypeArgument,
debugMode: boolean?
) → Leaderboard
}

BoardConfig​

</>
interface BoardConfig {
Name: string
Automation: boolean?
MaxRecords: number?
DisplayCount: number?
SaveInterval: number?
RefreshInterval: number?
Shards: number?
}

Properties​

Updated​

This item is read only and cannot be modified. Read Only
</>
Leaderboard.Updated: Signal<{AllTopData}>

Fired when the leaderboard is updated.

BoardUpdated​

This item is read only and cannot be modified. Read Only
</>
Leaderboard.BoardUpdated: Signal<{
Type: LeaderboardType,
Data: {TopData}
}>

Fired when a specific board is updated.

Functions​

new​

</>
Leaderboard.new(
leaderboardTypes: LeaderboardTypeArgument,
debugMode: boolean?
) → Leaderboard

Types

​

type LeaderboardTypeArgument = {[LeaderboardType]: BoardConfig | string | {number & string}}

Constructs a new leaderboard.

SaveValues​

This is a yielding function. When called, it will pause the Lua thread that called the function until a result is ready to be returned, without interrupting other scripts. Yields
</>
Leaderboard:SaveValues(
boardType: LeaderboardType?--

Optional board type to filter by. If nil, processes all boards.

) → Promise.TypedPromise<number>--

Returns the number of items processed

Processes all items in the value queue for the specified board type (or all boards if nil). Continues processing until the queue is empty for that board type.

GetRecords​

This is a yielding function. When called, it will pause the Lua thread that called the function until a result is ready to be returned, without interrupting other scripts. Yields
</>
Leaderboard:GetRecords(
boardTypes: {LeaderboardType} | "All",
optionalRange: {[string]: number} | number,
sortDirection: string
) → Promise.TypedPromise<{AllTopData}>

Types

​

interface TopData {
Rank: number
UserId: number
Value: number
Username: string
DisplayName: string
}

​

interface AllTopData {
Data: {TopData}
}

Gets the data for all the top boards (should only be used every 90-120 seconds)

IncrementValues​

</>
Leaderboard:IncrementValues(
boardTypes: {LeaderboardType} | "All",
userId: number,
amount: number
) → ()

Increments the queued value(s)

Increments the queued value(s)

SetValues​

</>
Leaderboard:SetValues(
boardTypes: {LeaderboardType} | "All",
userId: number,
value: number | (number) → (number)
) → ()

Updates the queued value(s)

Updates the queued value(s)

UpdateStoreValues​

This is a yielding function. When called, it will pause the Lua thread that called the function until a result is ready to be returned, without interrupting other scripts. Yields
</>
Leaderboard:UpdateStoreValues(
boardTypes: {LeaderboardType} | "All",
userId: number,
value: number | (number) → (number)
) → ()

Updates the actual store value(s) (should only be used every 90-120 seconds)

Updates the actual store value(s) (should only be used every 90-120 seconds)

Destroy​

</>
Leaderboard:Destroy() → ()

Destroys the leaderboard

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Constructs a new leaderboard.",
            "params": [
                {
                    "name": "leaderboardTypes",
                    "desc": "",
                    "lua_type": "LeaderboardTypeArgument"
                },
                {
                    "name": "debugMode",
                    "desc": "",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Leaderboard"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 236,
                "path": "lib/Leaderboard/init.luau"
            }
        },
        {
            "name": "SaveValues",
            "desc": "Processes all items in the value queue for the specified board type (or all boards if nil).\nContinues processing until the queue is empty for that board type.",
            "params": [
                {
                    "name": "boardType",
                    "desc": "Optional board type to filter by. If nil, processes all boards.",
                    "lua_type": "LeaderboardType?"
                }
            ],
            "returns": [
                {
                    "desc": "Returns the number of items processed",
                    "lua_type": "Promise.TypedPromise<number>"
                }
            ],
            "function_type": "method",
            "yields": true,
            "source": {
                "line": 437,
                "path": "lib/Leaderboard/init.luau"
            }
        },
        {
            "name": "GetRecords",
            "desc": "Gets the data for all the top boards (should only be used every 90-120 seconds)",
            "params": [
                {
                    "name": "boardTypes",
                    "desc": "",
                    "lua_type": "{LeaderboardType} | \"All\""
                },
                {
                    "name": "optionalRange",
                    "desc": "",
                    "lua_type": "{[string]: number} | number"
                },
                {
                    "name": "sortDirection",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise.TypedPromise<{AllTopData}>"
                }
            ],
            "function_type": "method",
            "yields": true,
            "source": {
                "line": 584,
                "path": "lib/Leaderboard/init.luau"
            }
        },
        {
            "name": "IncrementValues",
            "desc": "Increments the queued value(s)\n\nIncrements the queued value(s)",
            "params": [
                {
                    "name": "boardTypes",
                    "desc": "",
                    "lua_type": "{LeaderboardType} | \"All\""
                },
                {
                    "name": "userId",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "amount",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 643,
                "path": "lib/Leaderboard/init.luau"
            }
        },
        {
            "name": "SetValues",
            "desc": "Updates the queued value(s)\n\nUpdates the queued value(s)",
            "params": [
                {
                    "name": "boardTypes",
                    "desc": "",
                    "lua_type": "{LeaderboardType} | \"All\""
                },
                {
                    "name": "userId",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "number | (number) -> (number)"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 684,
                "path": "lib/Leaderboard/init.luau"
            }
        },
        {
            "name": "UpdateStoreValues",
            "desc": "Updates the actual store value(s) (should only be used every 90-120 seconds)\n\nUpdates the actual store value(s) (should only be used every 90-120 seconds)",
            "params": [
                {
                    "name": "boardTypes",
                    "desc": "",
                    "lua_type": "{LeaderboardType} | \"All\""
                },
                {
                    "name": "userId",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "number | (number) -> (number)"
                }
            ],
            "returns": [],
            "function_type": "method",
            "yields": true,
            "source": {
                "line": 723,
                "path": "lib/Leaderboard/init.luau"
            }
        },
        {
            "name": "Destroy",
            "desc": "Destroys the leaderboard",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 749,
                "path": "lib/Leaderboard/init.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "Updated",
            "desc": "Fired when the leaderboard is updated.",
            "lua_type": "Signal<{AllTopData}>",
            "readonly": true,
            "source": {
                "line": 186,
                "path": "lib/Leaderboard/init.luau"
            }
        },
        {
            "name": "BoardUpdated",
            "desc": "Fired when a specific board is updated.",
            "lua_type": "Signal<{Type: LeaderboardType, Data: {TopData}}>",
            "readonly": true,
            "source": {
                "line": 193,
                "path": "lib/Leaderboard/init.luau"
            }
        }
    ],
    "types": [
        {
            "name": "TopData",
            "desc": "",
            "fields": [
                {
                    "name": "Rank",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "UserId",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "Value",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "Username",
                    "lua_type": "string",
                    "desc": ""
                },
                {
                    "name": "DisplayName",
                    "lua_type": "string",
                    "desc": ""
                }
            ],
            "source": {
                "line": 37,
                "path": "lib/Leaderboard/init.luau"
            }
        },
        {
            "name": "AllTopData",
            "desc": "",
            "fields": [
                {
                    "name": "Type",
                    "lua_type": "LeaderboardType",
                    "desc": ""
                },
                {
                    "name": "Data",
                    "lua_type": "{TopData}",
                    "desc": ""
                }
            ],
            "source": {
                "line": 51,
                "path": "lib/Leaderboard/init.luau"
            }
        },
        {
            "name": "Leaderboard",
            "desc": "",
            "lua_type": "() -> Leaderboard",
            "source": {
                "line": 61,
                "path": "lib/Leaderboard/init.luau"
            }
        },
        {
            "name": "LeaderboardType",
            "desc": "",
            "lua_type": "\"Hourly\" | \"Daily\" | \"Weekly\" | \"Monthly\" | \"Yearly\" | \"AllTime\" | string;",
            "source": {
                "line": 67,
                "path": "lib/Leaderboard/init.luau"
            }
        },
        {
            "name": "LeaderboardTypeArgument",
            "desc": "",
            "lua_type": "{[LeaderboardType]: BoardConfig | string | {number & string}}",
            "source": {
                "line": 73,
                "path": "lib/Leaderboard/init.luau"
            }
        },
        {
            "name": "LeaderboardArguments",
            "desc": "",
            "fields": [
                {
                    "name": "Updated",
                    "lua_type": "Signal<{AllTopData}>",
                    "desc": ""
                },
                {
                    "name": "BoardUpdated",
                    "lua_type": "Signal<{Type: LeaderboardType, Data: {TopData}}>",
                    "desc": ""
                },
                {
                    "name": "_serviceKey",
                    "lua_type": "string",
                    "desc": ""
                },
                {
                    "name": "_types",
                    "lua_type": "LeaderboardTypeArgument",
                    "desc": ""
                },
                {
                    "name": "_boards",
                    "lua_type": "{[LeaderboardType]: Board}",
                    "desc": ""
                },
                {
                    "name": "_valueQueue",
                    "lua_type": "ValueQueueType",
                    "desc": ""
                },
                {
                    "name": "_isSaving",
                    "lua_type": "{[LeaderboardType]: boolean}",
                    "desc": ""
                },
                {
                    "name": "_lastSaved",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "_isFetching",
                    "lua_type": "boolean",
                    "desc": ""
                },
                {
                    "name": "_lastFetch",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "_logger",
                    "lua_type": "Logger.Logger?",
                    "desc": ""
                }
            ],
            "source": {
                "line": 92,
                "path": "lib/Leaderboard/init.luau"
            }
        },
        {
            "name": "OperationType",
            "desc": "The type of operation to perform on the leaderboard value.\n- \"Set\": Sets the value to the specified amount or result of the transform function\n- \"Increment\": Adds the specified amount or result of the transform function to the current value",
            "lua_type": "\"Set\" | \"Increment\"",
            "source": {
                "line": 115,
                "path": "lib/Leaderboard/init.luau"
            }
        },
        {
            "name": "Board",
            "desc": "",
            "fields": [
                {
                    "name": "GetRecords",
                    "lua_type": "(self: Board, amount: number, sortDirection: string) -> Promise.TypedPromise<{TopData}>",
                    "desc": ""
                },
                {
                    "name": "Update",
                    "lua_type": "(self: Board, userId: number, value: number | (number) -> (number)) -> boolean",
                    "desc": ""
                },
                {
                    "name": "Destroy",
                    "lua_type": "(self: Board) -> ()",
                    "desc": ""
                }
            ],
            "source": {
                "line": 124,
                "path": "lib/Leaderboard/init.luau"
            }
        },
        {
            "name": "Object",
            "desc": "",
            "fields": [
                {
                    "name": "IncrementValues",
                    "lua_type": "(self: Leaderboard, boardTypes: {LeaderboardType} | string, userId: number, amount: number) -> ()",
                    "desc": ""
                },
                {
                    "name": "SetValues",
                    "lua_type": "(self: Leaderboard, boardTypes: {LeaderboardType} | string, userId: number, value: number | (number) -> (number)) -> ()",
                    "desc": ""
                },
                {
                    "name": "UpdateStoreValues",
                    "lua_type": "(self: Leaderboard, boardTypes: {LeaderboardType} | string, userId: number, value: number | (number) -> (number)) -> ()",
                    "desc": ""
                },
                {
                    "name": "GetRecords",
                    "lua_type": "(self: Leaderboard, boardTypes: {LeaderboardType} | string, optionalRange: {[LeaderboardType | string]: number} | number, sortDirection: string) -> Promise.TypedPromise<{AllTopData}>",
                    "desc": ""
                },
                {
                    "name": "SaveValues",
                    "lua_type": "(self: Leaderboard, boardType: LeaderboardType?) -> Promise.TypedPromise<number>",
                    "desc": ""
                },
                {
                    "name": "Destroy",
                    "lua_type": "(self: Leaderboard) -> ()",
                    "desc": ""
                },
                {
                    "name": "new",
                    "lua_type": "(leaderboardTypes: LeaderboardTypeArgument, debugMode: boolean?) -> Leaderboard",
                    "desc": ""
                }
            ],
            "source": {
                "line": 145,
                "path": "lib/Leaderboard/init.luau"
            }
        },
        {
            "name": "BoardConfig",
            "desc": "",
            "fields": [
                {
                    "name": "Name",
                    "lua_type": "string",
                    "desc": ""
                },
                {
                    "name": "Automation",
                    "lua_type": "boolean?",
                    "desc": ""
                },
                {
                    "name": "MaxRecords",
                    "lua_type": "number?",
                    "desc": ""
                },
                {
                    "name": "DisplayCount",
                    "lua_type": "number?",
                    "desc": ""
                },
                {
                    "name": "SaveInterval",
                    "lua_type": "number?",
                    "desc": ""
                },
                {
                    "name": "RefreshInterval",
                    "lua_type": "number?",
                    "desc": ""
                },
                {
                    "name": "Shards",
                    "lua_type": "number?",
                    "desc": ""
                }
            ],
            "source": {
                "line": 169,
                "path": "lib/Leaderboard/init.luau"
            }
        }
    ],
    "name": "Leaderboard",
    "desc": "Leaderboard allows you to create a leaderboard that can be used to store and retrieve data for a specific service key.\n\nFor example:\n```lua\nlocal Leaderboard = require(game:GetService(\"ReplicatedStorage\").Leaderboard);\nlocal MoneyLeaderboard = Leaderboard.new({\n\tDaily = \"DailyMoneyKey1\",\n\tWeekly = \"WeeklyMoneyKey1\"\n});\n```",
    "source": {
        "line": 210,
        "path": "lib/Leaderboard/init.luau"
    }
}