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.

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.

   

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)

   It's essential that the folder is named leaderstats with all lowercase letters. Roblox doesn't add the player to the leaderboard if you name it any other way.

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.

   

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.

   Note that the value of objects such as IntValue, NumberValue, and StringValue must be set through their Value property, as in gold.Value on line 10.

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.

   

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)