leaderstats — the player leaderboard

The little list at the top-right of every Roblox game — the one showing each player's score or cash — is called the leaderboard. It's the first place you'll see your data working, and it's built from a folder called leaderstats.

#The recipe

Every player object in Roblox automatically carries a folder: player.leaderstats. Whatever you put inside it shows up on the leaderboard. The recipe is:

1. When a player joins, create their leaderstats folder.
2. Add a child — usually a NumberValue — for each stat.
3. Change the Value of that NumberValue, and the leaderboard updates itself.

#The join hook

A player joining is an event — PlayerAdded:

local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
    local stats = Instance.new("Folder")
    stats.Name = "leaderstats"
    stats.Parent = player

    local coins = Instance.new("NumberValue")
    coins.Name = "Coins"
    coins.Value = 0
    coins.Parent = stats
end)

• game:GetService("Players") — the service that manages players.
• Players.PlayerAdded:Connect(function(player) ... end) — an event; player is the new player.
• Instance.new("Folder") creates a Folder named leaderstats, parented to the player.
• Instance.new("NumberValue") creates a NumberValue named Coins, set to 0, parented into the folder.

#Updating stats

The magic: change the NumberValue's Value, and the leaderboard updates live.

local coin = workspace.Coin

coin.ClickDetector.MouseClick:Connect(function(player)
    local coins = player.leaderstats.Coins
    coins.Value = coins.Value + 10
end)

player.leaderstats.Coins reaches into the player's folder and grabs the NumberValue. You read it, add 10, write it back. The leaderboard reflects it instantly.

-- reward the player

#Common mistakes

• Misspelling leaderstats. Capital L, lowercase rest, no space. The contract is exact.
• Parenting the folder to the wrong thing. It must go on the player, not Workspace, not a part.
• Creating leaderstats before the player exists. That's why it lives in PlayerAdded — at that moment you have the player object.
• Expecting a normal Folder to show up. Only the folder named leaderstats is special.

Next: getting to know the player themselves — the Players service.