Global Leaderboards store data for players across play sessions which is automatically sorted by the entry scores. This can be used to call out player excellence in metrics that fit your game, but can also be used for tracking data for players who are not currently connected to your game.
There is a limited number of Leaderboards and Leaderboard Entries per project, and entries per board.
- Each Leaderboard can only have one entry per player.
- The maximum entries on a Leaderboard must be between 10 and 100 entries.
- One project can have up to 100 Leaderboards.
- Combined, Leaderboards in a project can have up to 1000 total entries.
Each Leaderboard has the option to track Daily, Weekly, and Monthly scores, by creating a separate copy of the Leaderboard which deletes entries that are more than 1, 7, or 30 days old.
Each Daily, Weekly, or Monthly Leaderboard contributes to the total number of entries. that a project can have.
Leaderboards are created through the Global Leaderboards window, and can be referenced in scripts using a NetRef.
- Click Window in the top menu toolbar, and then select Global Leaderboards.
- Click the Create New Leaderboard button.
- Give the Leaderboard a name that reflects the information it tracks.
- Choose Higher Is Better or Lower is Better depending on which should put a player at the top of the Leaderboard.
- Specify how many total entries the Leaderboard should track in the Rank Entries field.
- Check the boxes by Track Daily Data, Track Weekly Data, or Track Monthly Data to create additional copies of the Leaderboard that delete entries after a certain amount of time.
To reference a Leaderboard in a script, use a NetReference.
- In the Hierarchy, select the script that will reference the Leaderboard, and open the Properties window.
- Open the Global Leaderboards window, and find the Leaderboard to add.
- Select the name of the Leaderboard and click and drag it onto the Custom Properties.
- Copy the generated variable reference in the box below, and add paste it in the contents of the script.
Leaderboards do not instantly load, so the HasLeaderboards function can be used to check if it is loaded before displaying or adding new entries.
This code shows an example of using Task.Spawn with Task.Wait, to continue checking for a loaded Leaderboard before continuing to the next step
function loadLeaderboard() while not Leaderboards.HasLeaderboards() do -- just keep checking until this until the Leaderboards are loaded Task.Wait(1) -- wait one second end -- Code to display Leaderboard or add an entry goes here end -- spawn this task instead of just calling the function so that the Task.Wait doesn't make anything else wait. Task.Spawn(loadLeaderboard)
The Leaderboards AddEntry function allows you to submit a score for a player to the Leaderboard, which will automatically be sorted.
local propExampleLeaderboard = script:GetCustomProperty("ExampleLeaderboard") -- NetRef for the Leaderboard -- example function for any event that would create a score for the Leaderboard function WhenAPlayerScoresPoints(player, points) Leaderboards.SubmitPlayerScore(propExampleLeaderboard, player, points) end -- connect the WhenAPlayerScoresPoints() function to an event here
You can add a string of up to 8 characters of additional data as a fourth parameter. See the Leaderboards namespace for more details.
Leaderboards can be access by NetRef from client-side scripts, making it easy to show entries through UI Text Box and World Text. The Leaderboards GetLeaderboard method returns a table of LeaderboardEntry objects which have name, id, score, and additionalData properties that can be used to display the data.
You can create a text asset that is spawned for each Leaderboard entry, or create a group of texts ahead of time for the total number of entries, and update their
local propExampleLeaderboard = script:GetCustomProperty("ExampleLeaderboard") -- NetRef for the Leaderboard function showExampleLeaderboard() local entryTable = Leaderboards.GetLeaderboard() for _, entry in ipairs(entryTable) do print("name: " .. entry.name .. " score: " .. entry.score) -- This will only print to Event Log -- Create a UI Text or World Text asset to change here instead. end end -- call the showExampleLeaderboard function in a loadLeaderboard function like in the Loading Leaderboards example.
Leaderboards is a component that simplifies the process of adding a global leaderboard to a game. It is as simple as dragging and dropping a leaderboard template into the hierarchy and adjusting to meet your needs.