Skip to content

Leaderboards

The Leaderboards namespace contains a set of functions for retrieving and updating player leaderboard data. Use the Global Leaderboards tab in the Core Editor to configure leaderboards for your game. Then drag a leaderboard from the Global Leaderboards tab to a NetReference custom property for use with the Leaderboards API.

Class Functions

Class Function Name Return Type Description Tags
Leaderboards.HasLeaderboards() boolean Returns true if any leaderboard data is available. Returns false if leaderboards are still being retrieved, or if there is no leaderboard data. None
Leaderboards.GetLeaderboard(NetReference leaderboardRef, LeaderboardType) Array<LeaderboardEntry> Returns a table containing a list of entries for the specified leaderboard. The NetReference parameter should be retrieved from a custom property, assigned from the Global Leaderboards tab in the editor. This returns a copy of the data that has already been retrieved, so calling this function does not incur any additional network cost. If the requested leaderboard type has not been enabled for this leaderboard, an empty table will be returned. Supported leaderboard types include:
LeaderboardType.GLOBAL
LeaderboardType.DAILY
LeaderboardType.WEEKLY
LeaderboardType.MONTHLY
None
Leaderboards.SubmitPlayerScore(NetReference leaderboardRef, Player player, number score, [string additionalData]) None Submits a new score for the given Player on the specified leaderboard. The NetReference parameter should be retrieved from a custom property, assigned from the Global Leaderboards tab in the editor. This score may be ignored if the player already has a better score on this leaderboard. The optional additionalData parameter may be used to store a very small amount of data with the player's entry. If provided, this string must be 8 characters or fewer. (More specifically, 8 bytes when encoded as UTF-8.) Server-Only

Examples

Example using:

HasLeaderboards

GetLeaderboard

SubmitPlayerScore

id

name

score

additionalData

The Leaderboards namespace contains a set of functions for retrieving and updating player leaderboard data. This is a special kind of persistence that lets you save high scores for a game, with the data being associated with the game itself, rather than any particular player.

In order to use these functions, you must first create a Global Leaderboard in the Core editor. (Select Global Leaderboards, under the Window menu.)

function PrintLeaderboardEntry(entry)
    print(string.format("%s (%s): %d [%s]", entry.name, entry.id, entry.score, entry.additionalData))
end

-- To create this reference, create a custom property of type 'netreference',
-- and drag a leaderboard into it, from the Global Leaderboards tab:
local propLeaderboardRef = script:GetCustomProperty("LeaderboardRef")

-- Verify that we actually have leaderboard data to load:
if (Leaderboards.HasLeaderboards()) then
    -- Save a score to the leaderboard:
    Leaderboards.SubmitPlayerScore(propLeaderboardRef, player, math.random(0, 1000), "Xyzzy")

    -- Print out all the global scores on the leaderboard:
    print("Global scores:")
    local leaderboard = Leaderboards.GetLeaderboard(propLeaderboardRef, LeaderboardType.GLOBAL)
    for k, v in pairs(leaderboard) do
        PrintLeaderboardEntry(v)
    end

    -- Print out all the daily scores on the leaderboard:
    print("Daily scores:")
    local leaderboard = Leaderboards.GetLeaderboard(propLeaderboardRef, LeaderboardType.DAILY)
    for k, v in pairs(leaderboard) do
        PrintLeaderboardEntry(v)
    end
end
local leaderboard = Leaderboards.GetLeaderboard(propLeaderboardRef, LeaderboardType.MONTHLY)
local leaderboard = Leaderboards.GetLeaderboard(propLeaderboardRef, LeaderboardType.WEEKLY)


Last update: March 1, 2021