Tutorial · Player data

How to make a leaderboard in Roblox Studio

The player list in the top right of a Roblox game is driven by one folder called leaderstats. This guide builds it from scratch: the server script, a safe way to award points, saving between sessions, and a global top 10.

Updated 14 November 202611 min readBeginnerLuauWritten by

In short

Create a Script in ServerScriptService that listens to Players.PlayerAdded, makes a Folder named exactly leaderstats (all lowercase) and parents it to the player. Every IntValue, NumberValue or StringValue inside that folder becomes a column in the top-right player list, titled with the value's Name. Change .Value from server scripts to update it.

  • Create and change stats on the server only. A change made by a LocalScript is seen by that one player and nobody else.
  • leaderstats is not saved. Load and save the values with a data store if they should survive the next session.
  • For a ranking across every player, write each score to an ordered data store and show it on a board in your world, or in the player list's Global view.

Get the script

Leaderboard script with saving

Coins and Wins in the player list, loaded from a data store when a player joins and saved when they leave or the server shuts down.

Script in ServerScriptService named Leaderstats
local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")

-- Called inside each pcall below, so a place that is not published yet
-- (no data store access) still gets its leaderboard
local function statsStore(): DataStore
	return DataStoreService:GetDataStore("PlayerStats_v1")
end

-- Players whose saved stats loaded. Anyone missing from here is never saved,
-- so a failed load cannot overwrite real progress with zeros.
local loaded: { [Player]: boolean } = {}

local function keyFor(player: Player): string
	return "player_" .. player.UserId
end

local function onPlayerAdded(player: Player)
	local leaderstats = Instance.new("Folder")
	leaderstats.Name = "leaderstats"

	local coins = Instance.new("IntValue")
	coins.Name = "Coins"
	coins.Parent = leaderstats

	local wins = Instance.new("IntValue")
	wins.Name = "Wins"
	wins.Parent = leaderstats

	local ok, data = pcall(function()
		return statsStore():GetAsync(keyFor(player))
	end)
	if ok then
		if type(data) == "table" then
			coins.Value = tonumber(data.Coins) or 0
			wins.Value = tonumber(data.Wins) or 0
		end
		loaded[player] = true
	else
		warn(`Could not load stats for {player.Name}: {data}`)
	end

	leaderstats.Parent = player
end

local function save(player: Player)
	if not loaded[player] then
		return
	end
	local leaderstats = player:FindFirstChild("leaderstats")
	local coins = leaderstats and leaderstats:FindFirstChild("Coins")
	local wins = leaderstats and leaderstats:FindFirstChild("Wins")
	if not (coins and coins:IsA("IntValue") and wins and wins:IsA("IntValue")) then
		return
	end
	local ok, err = pcall(function()
		statsStore():SetAsync(keyFor(player), { Coins = coins.Value, Wins = wins.Value })
	end)
	if not ok then
		warn(`Could not save stats for {player.Name}: {err}`)
	end
end

Players.PlayerAdded:Connect(onPlayerAdded)
for _, player in Players:GetPlayers() do
	task.spawn(onPlayerAdded, player)
end

Players.PlayerRemoving:Connect(function(player: Player)
	save(player)
	loaded[player] = nil
end)

-- When the server shuts down, save everyone before it closes
game:BindToClose(function()
	local pending = 0
	for _, player in Players:GetPlayers() do
		pending += 1
		task.spawn(function()
			save(player)
			pending -= 1
		end)
	end
	while pending > 0 do
		task.wait()
	end
end)

RoCode builds it in the place you have open in Roblox Studio, on Windows or macOS with a desktop browser; on a phone the button sends the prompt and the link to your computer. Free to start, with free credits every day. More Roblox Studio scripts

Where to put it

Explorer: one Script, nothing else to build
ServerScriptService
  Leaderstats Script new

Settings you can change

PlayerStats_v1In the script
The data store the stats save to. Rename it while you test to start every player from zero; once your game is live, keep it, or saved stats seem to vanish.

To test saving in Studio, publish the place and turn on Enable Studio Access to API Services (Step 3). To add a stat, repeat what the script does for Wins in onPlayerAdded and save.

What a cheater can and cannot doThe server creates and changes the stats, so a player who edits the values on their own device changes only their own screen. Give rewards from server scripts, as in Step 2.

Type-checked with luau-lsp strict against Roblox's API definitions on 18 October 2026. Playtested in Studio on 22 October 2026 (Play Solo in an unpublished place: Coins and Wins showed on the player list and the failed load was a warning; saving needs a published place and is untested).

Prompt for RoCode

Add a leaderboard to my place: a leaderstats folder with Coins and Wins for every player, made by a Script in ServerScriptService, loaded from a data store when they join and saved when they leave and when the server shuts down, never saving a player whose data failed to load. Check my place for an existing leaderstats script first and extend it instead of adding a second one.

On this page
  1. Get the script
  2. How leaderstats works
  3. 1. Create leaderstats
  4. 2. Award points
  5. 3. Save stats
  6. 4. Global top 10
  7. 5. Kills and time
  8. Common errors
  9. With RoCode
  10. Questions
  11. Sources

How leaderstats works

IllustrationThe finished leaderstats and coin pad scripts in a running game.

Roblox shows a player list in every game. When a player has a child Folder named leaderstats, the list adds a column for each value object inside it and shows that player's value in their row. The column title is the value object's Name.

Value objects you can put in leaderstats
ObjectHoldsGood for
IntValueWhole numbersCoins, kills, wins, level
NumberValueDecimal numbersBest lap time, distance
StringValueTextRank or team title

Two rules cause almost every broken leaderboard. The folder name must be leaderstats exactly: Leaderstats or leaderStats is ignored. And the folder must be made by a server Script, because the server is the only place a change replicates to every player. If you are unsure where code runs, read Script vs LocalScript vs ModuleScript first.

Step 1: Create the leaderstats script

  1. In the Explorer, hover over ServerScriptService, click the + button and insert a Script.
  2. Rename it Leaderstats so you can find it later.
  3. Replace its contents with the code below and press Play. Your name appears in the player list with Coins and Wins at 0.
Script in ServerScriptService named Leaderstats
local Players = game:GetService("Players")

local function setupLeaderstats(player: Player)
	local leaderstats = Instance.new("Folder")
	leaderstats.Name = "leaderstats" -- must be exactly this name, all lowercase

	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

	leaderstats.Parent = player -- parent last, once the values are inside
end

Players.PlayerAdded:Connect(setupLeaderstats)

-- In Studio you can join before this script runs, so set up anyone already here
for _, player in Players:GetPlayers() do
	setupLeaderstats(player)
end

The loop at the end matters in Studio testing: the first player sometimes joins before PlayerAdded is connected, and that player would get no stats.

Step 2: Give players points, safely

To change a stat, set its Value from a server script. This coin pad pays 10 coins when a player touches it. Touched fires many times a second while a character stands on a part, so the script keeps a short cooldown per player.

Script in a Part in Workspace named CoinPad
local Players = game:GetService("Players")

local part = script.Parent :: BasePart
local REWARD = 10
local COOLDOWN_SECONDS = 1

local lastReward: { [Player]: number } = {}

part.Touched:Connect(function(hit: BasePart)
	local character = hit:FindFirstAncestorOfClass("Model")
	local player = character and Players:GetPlayerFromCharacter(character)
	if not player then
		return
	end

	local now = os.clock()
	local last = lastReward[player]
	if last and now - last < COOLDOWN_SECONDS then
		return -- Touched fires many times per step; this stops one touch paying out ten times
	end
	lastReward[player] = now

	local leaderstats = player:FindFirstChild("leaderstats")
	local coins = leaderstats and leaderstats:FindFirstChild("Coins")
	if coins and coins:IsA("IntValue") then
		coins.Value += REWARD
	end
end)

Players.PlayerRemoving:Connect(function(player: Player)
	lastReward[player] = nil
end)

FindFirstAncestorOfClass("Model") finds the character even when the touching part is inside an accessory, which a plain hit.Parent check misses.

If points come from something the player does on their own screen, such as clicking a button, the LocalScript should ask the server with a RemoteEvent and the server should decide whether to pay. Never let the client send the amount. The RemoteEvents guide shows the pattern with validation.

Four worked examples: the first game guide pays 1 Coin for each coin a player touches on its course and a Win at the finish pad after 3 coins, the clicker simulator guide pays Coins for button clicks with a click limit on the server, the sword guide adds 1 to the Kills stat of whoever landed the last hit before a player died, and the gun guide shows how to count a kill when a shot takes a target's Health to 0.

Step 3: Save the stats between sessions

leaderstats lives only as long as the server. To keep coins and wins, load them from a data store when the player joins and save them when they leave. This version replaces the Step 1 script. It never saves a player whose data failed to load, which is the mistake that wipes progress in most copied save scripts.

Script in ServerScriptService named Leaderstats
local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")

-- Called inside each pcall below, so a place that is not published yet
-- (no data store access) still gets its leaderboard
local function statsStore(): DataStore
	return DataStoreService:GetDataStore("PlayerStats_v1")
end

-- Players whose saved stats loaded. Anyone missing from here is never saved,
-- so a failed load cannot overwrite real progress with zeros.
local loaded: { [Player]: boolean } = {}

local function keyFor(player: Player): string
	return "player_" .. player.UserId
end

local function onPlayerAdded(player: Player)
	local leaderstats = Instance.new("Folder")
	leaderstats.Name = "leaderstats"

	local coins = Instance.new("IntValue")
	coins.Name = "Coins"
	coins.Parent = leaderstats

	local wins = Instance.new("IntValue")
	wins.Name = "Wins"
	wins.Parent = leaderstats

	local ok, data = pcall(function()
		return statsStore():GetAsync(keyFor(player))
	end)
	if ok then
		if type(data) == "table" then
			coins.Value = tonumber(data.Coins) or 0
			wins.Value = tonumber(data.Wins) or 0
		end
		loaded[player] = true
	else
		warn(`Could not load stats for {player.Name}: {data}`)
	end

	leaderstats.Parent = player
end

local function save(player: Player)
	if not loaded[player] then
		return
	end
	local leaderstats = player:FindFirstChild("leaderstats")
	local coins = leaderstats and leaderstats:FindFirstChild("Coins")
	local wins = leaderstats and leaderstats:FindFirstChild("Wins")
	if not (coins and coins:IsA("IntValue") and wins and wins:IsA("IntValue")) then
		return
	end
	local ok, err = pcall(function()
		statsStore():SetAsync(keyFor(player), { Coins = coins.Value, Wins = wins.Value })
	end)
	if not ok then
		warn(`Could not save stats for {player.Name}: {err}`)
	end
end

Players.PlayerAdded:Connect(onPlayerAdded)
for _, player in Players:GetPlayers() do
	task.spawn(onPlayerAdded, player)
end

Players.PlayerRemoving:Connect(function(player: Player)
	save(player)
	loaded[player] = nil
end)

-- When the server shuts down, save everyone before it closes
game:BindToClose(function()
	local pending = 0
	for _, player in Players:GetPlayers() do
		pending += 1
		task.spawn(function()
			save(player)
			pending -= 1
		end)
	end
	while pending > 0 do
		task.wait()
	end
end)

This is enough for a small game. For retries, UpdateAsync, request limits and protecting against two servers writing the same player, continue with the DataStore tutorial.

Step 4: A global top 10

leaderstats only compares players in the same server. A global ranking needs an ordered data store: a data store that keeps one number per key and can return the keys sorted by value. Write each player's score to it from the server, then read the top entries back.

You have two ways to show it. Roblox's player list has Friends and Global views that read from an ordered data store you register in Creator Hub (a beta feature at the time of writing, one active leaderboard per game). Or you can draw the ranking yourself on a board in your world, which works in every game and lets you style it. The script below does the second, and the scores it writes use the player's user ID as the key, which is also the format the Creator Hub leaderboard expects.

  1. Add an anchored Part to Workspace, name it WinsBoard, and size it like a sign (for example 12 by 8 by 1 studs), front face towards your spawn.
  2. Insert a Script into ServerScriptService named GlobalWinsBoard with the code below.
  3. Play. The board fills once the first refresh has run, and updates every minute.
Script in ServerScriptService named GlobalWinsBoard
local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")

local winsBoard = DataStoreService:GetOrderedDataStore("GlobalWins_v1")

local TOP_N = 10
local REFRESH_SECONDS = 60

-- The board: an anchored Part named WinsBoard in Workspace. The script adds the
-- SurfaceGui and the rows itself, so the Part is all you have to build.
local boardPart = workspace:WaitForChild("WinsBoard") :: BasePart

local gui = Instance.new("SurfaceGui")
gui.Face = Enum.NormalId.Front
gui.SizingMode = Enum.SurfaceGuiSizingMode.PixelsPerStud
gui.PixelsPerStud = 50
gui.Parent = boardPart

local list = Instance.new("Frame")
list.Size = UDim2.fromScale(1, 1)
list.BackgroundColor3 = Color3.fromRGB(18, 11, 31)
list.Parent = gui

local layout = Instance.new("UIListLayout")
layout.SortOrder = Enum.SortOrder.LayoutOrder
layout.Parent = list

local nameCache: { [number]: string } = {}

local function nameFor(userId: number): string
	local cached = nameCache[userId]
	if cached then
		return cached
	end
	local ok, name = pcall(function()
		return Players:GetNameFromUserIdAsync(userId)
	end)
	local result = if ok then name else "Unknown player"
	nameCache[userId] = result
	return result
end

local function recordWins(player: Player)
	local leaderstats = player:FindFirstChild("leaderstats")
	local wins = leaderstats and leaderstats:FindFirstChild("Wins")
	if wins and wins:IsA("IntValue") then
		local ok, err = pcall(function()
			winsBoard:SetAsync(tostring(player.UserId), wins.Value)
		end)
		if not ok then
			warn(`Could not record wins for {player.Name}: {err}`)
		end
	end
end

local function refresh()
	local ok, pages = pcall(function()
		return winsBoard:GetSortedAsync(false, TOP_N)
	end)
	if not ok then
		warn(`Could not read the wins board: {pages}`)
		return
	end

	for _, child in list:GetChildren() do
		if child:IsA("TextLabel") then
			child:Destroy()
		end
	end

	for rank, entry in pages:GetCurrentPage() do
		local label = Instance.new("TextLabel")
		label.Size = UDim2.new(1, 0, 1 / TOP_N, 0)
		label.BackgroundTransparency = 1
		label.TextColor3 = Color3.new(1, 1, 1)
		label.TextScaled = true
		label.Text = `{rank}. {nameFor(tonumber(entry.key) or 0)}   {entry.value}`
		label.LayoutOrder = rank
		label.Parent = list
	end
end

while true do
	for _, player in Players:GetPlayers() do
		recordWins(player)
	end
	refresh()
	task.wait(REFRESH_SECONDS)
end

GetSortedAsync(false, 10) returns the 10 highest values first. Ordered data stores hold whole numbers only, so store scores as integers. The script writes each player once a minute and reads the top 10 once a minute, well inside the default per-server limits (30 + 5 per player per minute for ordered writes and 5 + 2 per player for sorted reads, as documented on 30 September 2026).

Step 5: Kills, deaths and time played

Most fighting games show Kills and Deaths, and many show minutes played. Roblox does not know who killed whom, so your weapon has to record it. Add one line to the server code that deals damage, just before TakeDamage: humanoid:SetAttribute("LastHitBy", attacker.UserId). The sword guide shows where it goes. This script reads that attribute when the Humanoid dies and adds a kill to that player.

Script in ServerScriptService named KillStats
local Players = game:GetService("Players")

-- Adds Kills, Deaths and Minutes to the leaderstats folder that your
-- Leaderstats script makes. Weapons record the attacker on the victim's
-- Humanoid with SetAttribute("LastHitBy", attacker.UserId) before damage.

local function addStat(leaderstats: Instance, name: string): IntValue
	local existing = leaderstats:FindFirstChild(name)
	if existing and existing:IsA("IntValue") then
		return existing
	end
	local stat = Instance.new("IntValue")
	stat.Name = name
	stat.Parent = leaderstats
	return stat
end

local function getStat(player: Player, name: string): IntValue?
	local leaderstats = player:FindFirstChild("leaderstats")
	local stat = leaderstats and leaderstats:FindFirstChild(name)
	if stat and stat:IsA("IntValue") then
		return stat
	end
	return nil
end

local function onCharacterAdded(player: Player, character: Model)
	local humanoid = character:WaitForChild("Humanoid", 10)
	if not (humanoid and humanoid:IsA("Humanoid")) then
		return
	end
	humanoid.Died:Connect(function()
		local deaths = getStat(player, "Deaths")
		if deaths then
			deaths.Value += 1
		end

		local attackerId = humanoid:GetAttribute("LastHitBy")
		if typeof(attackerId) ~= "number" or attackerId == player.UserId then
			return -- no attacker recorded, or the player killed themselves
		end
		local attacker = Players:GetPlayerByUserId(attackerId)
		local kills = attacker and getStat(attacker, "Kills")
		if kills then
			kills.Value += 1
		end
	end)
end

local function onPlayerAdded(player: Player)
	local leaderstats = player:WaitForChild("leaderstats", 30)
	if not leaderstats then
		warn(`No leaderstats for {player.Name}, so no kill stats`)
		return
	end
	addStat(leaderstats, "Kills")
	addStat(leaderstats, "Deaths")
	addStat(leaderstats, "Minutes")

	player.CharacterAdded:Connect(function(character)
		onCharacterAdded(player, character)
	end)
	if player.Character then
		onCharacterAdded(player, player.Character)
	end
end

Players.PlayerAdded:Connect(onPlayerAdded)
for _, player in Players:GetPlayers() do
	task.spawn(onPlayerAdded, player)
end

-- One minute of play time for everyone in the server, every minute
while true do
	task.wait(60)
	for _, player in Players:GetPlayers() do
		local minutes = getStat(player, "Minutes")
		if minutes then
			minutes.Value += 1
		end
	end
end

Keep your Step 1 or Step 3 Leaderstats script: this one waits for its folder and adds three columns. The Step 3 script saves only Coins and Wins, so add Kills, Deaths and Minutes to its save table and load them in onPlayerAdded if they should last between sessions.

  • Any weapon works if it sets LastHitBy on the server before damage. A gun, a fireball or a combat system can record the attacker the same way.
  • Falls and resets add a death but no kill when no one hit the player. If someone hit them earlier in that life, the kill still goes to that attacker, because the attribute stays on the Humanoid until the character respawns.
  • Minutes counts whole minutes in this server. A player who leaves after 59 seconds gets nothing for that minute.

Common errors and fixes

The problems below account for most "my leaderboard doesn't work" posts. Check the Output window first (open it from Studio's Window menu or the Script tab): if a script errored, the line number is there.

The leaderboard does not show at all

Check the folder name is leaderstats in lowercase, that it is parented to the Player (not the character), and that the code is a Script in ServerScriptService, not a LocalScript.

Other players do not see my stat change

The value was changed on the client. Move the change into a server Script, and if a button or key press triggers it, send a RemoteEvent and let the server change the value.

attempt to index nil with 'Coins'

Code tried to read player.leaderstats.Coins before the folder existed, or the name is spelled differently. On the server use FindFirstChild and check the result; in a LocalScript use player:WaitForChild("leaderstats"). The script errors guide explains this error in detail.

Coins go up by 10, 20 or 50 from one touch

Touched fires repeatedly while parts overlap. Add a per-player cooldown as in Step 2, or remove the pickup when it is collected.

Stats reset every time I rejoin

leaderstats is not saved by Roblox. Add the Step 3 script. To test saving in Studio, publish the place and enable Studio Access to API Services in Experience Settings.

Build it with RoCode

If you would rather not wire this up by hand, RoCode can build it inside the place you have open. It is an AI agent that works through a Roblox Studio plugin, so it creates the scripts and parts in your Explorer instead of giving you code to paste.

You type

Add a leaderboard with Coins and Wins that saves between sessions, and a top 10 wins board on a part near the spawn.

RoCode does
  • Can search your place for existing leaderstats or DataStore code first, so it can extend what you have rather than add a second leaderboard
  • Creates the server script in ServerScriptService and the board part in Workspace
  • Compile-checks the scripts it wrote inside Studio before it finishes
  • Sends its changes in batches, and each batch is marked as an undo point in Studio's history

You still review the result and play-test the stats and the saving yourself: with plugin 3.9 or newer RoCode can run a short playtest and read the errors, and with plugin 3.9.11 or newer it can control a test character and check values such as Coins and Wins, but it checks only what it chose to test. Leaderstats are usually the first of many systems in a game: build the rest of your game one system per prompt the same way. How RoCode connects to Studio.

Questions

What is leaderstats in Roblox?

A Folder named exactly leaderstats, all lowercase, inside a Player. Roblox shows every IntValue, NumberValue or StringValue in it as a column in the player list. Create it from a server Script, as in Step 1.

How do I make a global leaderboard in Roblox?

Write each player's score to an ordered data store from the server, then read the top entries back and show them on a board in your world. Step 4 has the full script for a top 10.

Does Roblox save leaderstats automatically?

No. leaderstats only exists while the player is in the server. Save the values with a data store when the player leaves and load them when they join, as in Step 3.

Can I hide a value from the leaderboard?

Yes. Only values inside the leaderstats folder are shown. Keep private data in another folder on the player, or in a table in a server script.

How do I hide the whole player list?

From a LocalScript, call StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, false). Pass true to show it again.

How do I make a kills leaderboard in Roblox?

Add a Kills IntValue to leaderstats, have your weapon set a LastHitBy attribute with the attacker's UserId on the Humanoid it damages, and give that player a kill when the Humanoid's Died event fires. Step 5 has the full script, with Deaths and Minutes too.

Why is my leaderboard not showing up?

Almost always one of three things: the folder is not named exactly leaderstats in lowercase, it is parented to the character instead of the Player, or a LocalScript made it. Use a Script in ServerScriptService, and read the Output for an error on the line that makes the folder. The common problems section covers the rest.

How do I change the order of leaderboard stats?

Stats appear in the order you add them. To force one first, give it a child BoolValue named IsPrimary set to true. Or give stats a child NumberValue named Priority: higher numbers come first. Roblox says IsPrimary wins over Priority.

How do I make the leaderboard Friends and Global tabs work?

They read an ordered data store that you register in Creator Hub, with one whole-number score per player keyed by UserId. Roblox marks it as a beta with one active leaderboard per game. Your server still writes the scores, as in Step 4.

Can I use a NumberValue for coins?

You can, but an IntValue is the better fit for whole-number currency, and ordered data stores only accept whole numbers if you later rank by it.

Sources and further reading

How the code was checked: every script on this page passes Luau's strict type checker against Roblox's API definitions (luau-lsp, 14 November 2026). A type check catches misspelt APIs and wrong types, not game logic, so playtest in Studio before you publish.

Try RoCode on your own place.

Free every day, no card required. Install the plugin, describe the feature, and review what lands in Studio.