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: boolean
_lastSaved: number
_isFetching: boolean
_lastFetch: number
_threads: {thread}
_connections: {RBXScriptConnection}
_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) → Promise.TypedPromise<nil>
Destroy: (self: Leaderboard) → ()
new: (
leaderboardTypes: {LeaderboardType},
automationSettings: AutomationSettings?,
debugMode: boolean?
) → Leaderboard
}

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,
automationSettings: AutomationSettings?,
debugMode: boolean?
) → Leaderboard

Types

​

type LeaderboardTypeArgument = {[LeaderboardType]: any}

​

interface AutomationSettings {
Automation: boolean?
Interval: number?
RecordCount: number | {[string]: number}?
}

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() → ()

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

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<{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": "automationSettings",
                    "desc": "",
                    "lua_type": "AutomationSettings?"
                },
                {
                    "name": "debugMode",
                    "desc": "",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Leaderboard"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 224,
                "path": "lib/Leaderboard/init.luau"
            }
        },
        {
            "name": "SaveValues",
            "desc": "Updates the actual store value(s) (should only be used every 90-120 seconds)",
            "params": [],
            "returns": [],
            "function_type": "method",
            "yields": true,
            "source": {
                "line": 315,
                "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<{AllTopData}>"
                }
            ],
            "function_type": "method",
            "yields": true,
            "source": {
                "line": 366,
                "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": 424,
                "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": 464,
                "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": 502,
                "path": "lib/Leaderboard/init.luau"
            }
        },
        {
            "name": "Destroy",
            "desc": "Destroys the leaderboard",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 527,
                "path": "lib/Leaderboard/init.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "Updated",
            "desc": "Fired when the leaderboard is updated.",
            "lua_type": "Signal<{AllTopData}>",
            "readonly": true,
            "source": {
                "line": 181,
                "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": 188,
                "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]: any}",
            "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": "boolean",
                    "desc": ""
                },
                {
                    "name": "_lastSaved",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "_isFetching",
                    "lua_type": "boolean",
                    "desc": ""
                },
                {
                    "name": "_lastFetch",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "_threads",
                    "lua_type": "{thread}",
                    "desc": ""
                },
                {
                    "name": "_connections",
                    "lua_type": "{RBXScriptConnection}",
                    "desc": ""
                },
                {
                    "name": "_logger",
                    "lua_type": "Logger.Logger?",
                    "desc": ""
                }
            ],
            "source": {
                "line": 94,
                "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": 118,
                "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": 127,
                "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) -> Promise.TypedPromise<nil>",
                    "desc": ""
                },
                {
                    "name": "Destroy",
                    "lua_type": "(self: Leaderboard) -> ()",
                    "desc": ""
                },
                {
                    "name": "new",
                    "lua_type": "(leaderboardTypes: {LeaderboardType}, automationSettings: AutomationSettings?, debugMode: boolean?) -> Leaderboard",
                    "desc": ""
                }
            ],
            "source": {
                "line": 148,
                "path": "lib/Leaderboard/init.luau"
            }
        },
        {
            "name": "AutomationSettings",
            "desc": "",
            "fields": [
                {
                    "name": "Automation",
                    "lua_type": "boolean?",
                    "desc": ""
                },
                {
                    "name": "Interval",
                    "lua_type": "number?",
                    "desc": ""
                },
                {
                    "name": "RecordCount",
                    "lua_type": "number | {[string]: number}?",
                    "desc": ""
                }
            ],
            "source": {
                "line": 168,
                "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": 205,
        "path": "lib/Leaderboard/init.luau"
    }
}