How to Create a Working Leaderboard from Scratch

Leaderboards are one of the most common features you’ll see in Roblox games. Whether you’re tracking coins, points, wins, or any other stat, leaderboards give players instant feedback and make your game feel more polished and professional. The good news? They’re surprisingly easy to create once you understand the basics!

In this tutorial, we’ll build a working leaderboard from scratch. By the end, you’ll understand exactly how leaderboards work and be able to customize them for any game you’re making.

What Is a Leaderboard?

In Roblox, a leaderboard is technically called a “leaderstats” folder. When a player joins your game, Roblox automatically displays any stats stored in a folder named “leaderstats” inside that player’s character data. These stats appear in the top-right corner of the screen and in the player list (accessed by pressing Tab).

The beauty of this system is that Roblox handles all the display work for you—you just need to create the folder and add the stats you want to track!

Setting Up Your Script

First, let’s create a server script that will run whenever a player joins the game. In Roblox Studio, follow these steps:

In the Explorer window, find ServerScriptService
Right-click it and select Insert Object > Script
Rename your script to something like “LeaderboardScript”

This script will run on the server, which is important because we want everyone in the game to see the same leaderboard data.

Creating the Leaderstats Folder

Now let’s write the code! We’ll use the PlayerAdded event, which fires whenever a new player joins the game. Here’s our basic setup:

local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
	-- This code runs when a player joins
	local leaderstats = Instance.new("Folder")
	leaderstats.Name = "leaderstats"
	leaderstats.Parent = player
end)

Let’s break down what’s happening here:

Line 1: We get the Players service, which manages all players in the game
Line 3: We connect a function to the PlayerAdded event—this function runs for each player who joins
Line 5: We create a new Folder instance
Line 6: We name it “leaderstats” (this exact name is crucial—it must be lowercase!)
Line 7: We parent it to the player, which puts it inside their data structure

Adding Stats to Your Leaderboard

A folder alone won’t show anything. We need to add actual stats! In Roblox, stats are stored as value objects. The most common types are IntValue (for whole numbers) and NumberValue (for decimals). Let’s add a Coins stat:

local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
	local leaderstats = Instance.new("Folder")
	leaderstats.Name = "leaderstats"
	leaderstats.Parent = player
	
	local coins = Instance.new("IntValue")
	coins.Name = "Coins"
	coins.Value = 0
	coins.Parent = leaderstats
end)

We’ve added four new lines that create a Coins stat. The Name property is what displays on the leaderboard, and Value is the starting amount (0 in this case). By parenting the IntValue to leaderstats, it becomes visible on the leaderboard.

Adding Multiple Stats

Want to track multiple things? Just create more value objects! Here’s a leaderboard with Coins, Wins, and Level:

local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
	local leaderstats = Instance.new("Folder")
	leaderstats.Name = "leaderstats"
	leaderstats.Parent = player
	
	local coins = Instance.new("IntValue")
	coins.Name = "Coins"
	coins.Value = 0
	coins.Parent = leaderstats
	
	local wins = Instance.new("IntValue")
	wins.Name = "Wins"
	wins.Value = 0
	wins.Parent = leaderstats
	
	local level = Instance.new("IntValue")
	level.Name = "Level"
	level.Value = 1
	level.Parent = leaderstats
end)

Notice that our Level stat starts at 1 instead of 0—you can set any starting value that makes sense for your game!

Changing Stat Values

Your leaderboard is now working, but the values won’t change on their own. To update a stat, you need to access it from other scripts. Here’s an example that gives a player 10 coins:

local player = game.Players.LocalPlayer -- or however you reference the player
local leaderstats = player:FindFirstChild("leaderstats")

if leaderstats then
	local coins = leaderstats:FindFirstChild("Coins")
	if coins then
		coins.Value = coins.Value + 10
	end
end

We use FindFirstChild to safely check if the leaderstats and Coins exist before trying to change them. This prevents errors if something isn’t set up correctly.

Recap and Next Steps

Congratulations! You’ve just created a fully functional leaderboard system. You learned how to create a leaderstats folder, add stats using value objects, and understand why Roblox automatically displays them for you.

The key takeaways are:

The folder must be named “leaderstats” (lowercase)
Stats are created using value objects like IntValue or NumberValue
The Name property determines what players see on the leaderboard
You can add as many stats as you need for your game

Now that you have a working leaderboard, try experimenting with different stats for your game! Next, you might want to learn about DataStores to save player stats between sessions, or explore RemoteEvents to trigger stat changes from LocalScripts. Happy scripting!

Author

karlito1501