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.

   

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 in-game leaderboard.

   

3. The stat's initial Name 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.

   Value type objects such as IntValue, NumberValue, and StringValue must be set through their Value property, as in gold.Value = 0, not by direct declaration, as in gold = 0.

4. The instance is parented to the leaderstats folder which adds it to the leaderboard. When players enter the game, their names appear 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 humanoid = partParent:FindFirstChildWhichIsA("Humanoid")
	if humanoid then
		-- Destroy the pickup
		goldChunk:Destroy()
		-- Update the player's leaderboard stat
		local player = Players:GetPlayerFromCharacter(partParent)
		local leaderstats = player.leaderstats
		local goldStat = leaderstats and leaderstats:FindFirstChild("Gold")
		if goldStat then
			goldStat.Value = goldStat.Value + 10
		end
	end
end
goldChunk.Touched:Connect(onPartTouch)

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)