In-Experience Leaderboards

Roblox has a built-in leaderboard system that lets you display user information like scores, currency, or the fastest time in a race.

Leaderboard Screen

Setting up the Leaderboard

To set up the leaderboard and add players when they enter the experience:

  1. Create a new Script within ServerScriptService and name it Leaderboard.

    Leaderboard Insert Script
  2. In the script, connect a function to the PlayerAdded event.


    local Players = game:GetService("Players")
    local function leaderboardSetup(player)
    end
    -- Connect the "leaderboardSetup()" function to the "PlayerAdded" event
    Players.PlayerAdded:Connect(leaderboardSetup)
  3. Inside the connected function, create a new Folder instance, name it leaderstats, and parent it to the player.


    local Players = game:GetService("Players")
    local function leaderboardSetup(player)
    local leaderstats = Instance.new("Folder")
    leaderstats.Name = "leaderstats"
    leaderstats.Parent = player
    end
    -- Connect the "leaderboardSetup()" function to the "PlayerAdded" event
    Players.PlayerAdded:Connect(leaderboardSetup)

Adding Stats

Leaderboards use value type objects to store and display player stats. This script will show a player's gold using an IntValue, a placeholder for an integer.

In the leaderboardSetup() function, add lines 8 through 11:


local Players = game:GetService("Players")
local function leaderboardSetup(player)
local leaderstats = Instance.new("Folder")
leaderstats.Name = "leaderstats"
leaderstats.Parent = player
local gold = Instance.new("IntValue")
gold.Name = "Gold"
gold.Value = 0
gold.Parent = leaderstats
end
-- Connect the "leaderboardSetup()" function to the "PlayerAdded" event
Players.PlayerAdded:Connect(leaderboardSetup)

These lines accomplish the following:

  1. An IntValue instance is created.

  2. The instance's Name is set to "Gold". This is exactly how the stat will appear on the leaderboard.

    Leaderboards Name Column
  3. The stat's initial Value is set to 0. This can be set to any value you wish, including a value stored in a data store if you're implementing persistent leaderboards.

  4. The instance is parented to the leaderstats folder which adds it to the leaderboard. When a player enters the experience, their name appears on the board.

    Leaderboards Multiple Players

Updating Stats

To update a player's leaderboard stat, change the Value property of that stat within their leaderstats folder. For example, you can attach the following Script to any pickup object to increase the Gold stat of the player collects it.


local Players = game:GetService("Players")
local goldChunk = script.Parent
local function onPartTouch(otherPart)
local partParent = otherPart.Parent
local player = Players:GetPlayerFromCharacter(partParent)
local leaderstats = player and player:FindFirstChild("leaderstats")
local goldStat = leaderstats and leaderstats:FindFirstChild("Gold")
if goldStat then
-- Destroy the pickup
goldChunk:Destroy()
-- Update the player's leaderboard stat
goldStat.Value += 10
end
end
goldChunk.Touched:Connect(onPartTouch)

Ordering Stats

There are three ways to control the order of stats in a leaderboard:

  • Add the stats in the order that you want them to appear.
  • Add a child BoolValue named IsPrimary to the stat and set its value to true to place the stat first in the leaderboard.
  • Add a child NumberValue named Priority to the stat and set its value to an integer. Higher priority values appear earlier in the leaderboard. Stats without a priority have a default priority of 0.

This code sample shows how to add an IsPrimary value to a stat:


local Players = game:GetService("Players")
local function leaderboardSetup(player)
local leaderstats = Instance.new("Folder")
leaderstats.Name = "leaderstats"
leaderstats.Parent = player
local gold = Instance.new("IntValue")
gold.Name = "Gold"
gold.Value = 0
gold.Parent = leaderstats
local isPrimary = Instance.new("BoolValue")
isPrimary.Name = "IsPrimary"
isPrimary.Value = true
isPrimary.Parent = gold
end
Players.PlayerAdded:Connect(leaderboardSetup)

Hiding the Leaderboard

To hide the leaderboard, such as on a menu screen or during a cutscene, place a LocalScript within StarterGui or StarterPlayerScripts containing a call to StarterGui.


local StarterGui = game:GetService("StarterGui")
StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, false)