Resumo
Crie um Script no ServerScriptService que escuta o Players.PlayerAdded, cria uma Folder chamada exatamente leaderstats (tudo minúsculo) e a coloca como filha do jogador. Cada IntValue, NumberValue ou StringValue dentro dessa pasta vira uma coluna na lista de jogadores.
- Crie e mude os stats só no servidor. Uma mudança feita por um LocalScript é vista só por aquele jogador e por mais ninguém.
- O leaderstats não é salvo. Carregue e salve os valores com um data store se eles devem durar até a próxima sessão.
- Para um ranking entre todos os jogadores, grave a pontuação de cada um em um ordered data store e mostre em um painel no seu mundo, ou na visão Global da lista de jogadores.
Nesta página
Como o leaderstats funciona
O Roblox mostra uma lista de jogadores em todo jogo. Quando um jogador tem uma Folder filha chamada leaderstats, a lista adiciona uma coluna para cada objeto de valor dentro dela e mostra o valor daquele jogador na linha dele. O título da coluna é o Name do objeto de valor.
| Objeto | Guarda | Bom para |
|---|---|---|
IntValue | Números inteiros | Moedas, kills, vitórias, nível |
NumberValue | Números decimais | Melhor tempo de volta, distância |
StringValue | Texto | Cargo ou título do time |
Duas regras causam quase todo leaderboard quebrado. O nome da pasta precisa ser exatamente leaderstats: Leaderstats ou leaderStats é ignorado. E a pasta precisa ser criada por um Script de servidor, porque o servidor é o único lugar de onde uma mudança é replicada para todos os jogadores. Se você não tem certeza de onde o código roda, leia antes Script vs LocalScript vs ModuleScript (em inglês).
Passo 1: Crie o script de leaderstats
- No Explorer, passe o mouse sobre ServerScriptService, clique no botão + e insira um Script.
- Renomeie para
Leaderstatspara achar depois. - Troque o conteúdo pelo código abaixo e aperte Play. O seu nome aparece na lista de jogadores com Coins e Wins em 0.
local Players = game:GetService("Players")
local function setupLeaderstats(player: Player)
local leaderstats = Instance.new("Folder")
leaderstats.Name = "leaderstats" -- precisa ser exatamente este nome, tudo minúsculo
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 -- define o pai por último, quando os valores já estão dentro
end
Players.PlayerAdded:Connect(setupLeaderstats)
-- No Studio você pode entrar antes de este script rodar, então configura quem já está aqui
for _, player in Players:GetPlayers() do
setupLeaderstats(player)
end
O loop do final importa nos testes do Studio: às vezes o primeiro jogador entra antes de o PlayerAdded estar conectado, e esse jogador ficaria sem stats.
Passo 2: Dê pontos aos jogadores com segurança
Para mudar um stat, defina o Value dele de um script de servidor. Esta plataforma de moedas paga 10 moedas quando um jogador encosta nela. O Touched dispara muitas vezes por segundo enquanto um personagem fica em cima de uma part, então o script mantém um cooldown curto por jogador.
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 -- o Touched dispara muitas vezes por passo; isto impede que um toque pague dez vezes
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)
O FindFirstAncestorOfClass("Model") acha o personagem mesmo quando a part que encostou está dentro de um acessório, o que uma checagem simples com hit.Parent deixa passar.
Se os pontos vêm de algo que o jogador faz na própria tela, como clicar em um botão, o LocalScript deve pedir ao servidor com um RemoteEvent, e o servidor decide se paga. Nunca deixe o cliente enviar o valor. O guia de RemoteEvents (em inglês) mostra o padrão com validação.
Quatro exemplos prontos: o guia do primeiro jogo paga 1 Coin por cada moeda que o jogador toca no percurso e uma Win na plataforma de chegada depois de 3 moedas, o guia de simulador de cliques paga Coins por cliques em um botão com um limite de cliques no servidor, o guia de espada soma 1 ao stat Kills de quem deu o último golpe antes de um jogador morrer, e o guia de arma mostra como contar uma kill quando um tiro leva a Health do alvo a 0 (em inglês).
Passo 3: Salve os stats entre sessões
O leaderstats só existe enquanto o servidor existe. Para manter moedas e vitórias, carregue os valores de um data store quando o jogador entra e salve quando ele sai. Esta versão substitui o script do Passo 1. Ela nunca salva um jogador cujos dados falharam ao carregar, que é o erro que apaga o progresso na maioria dos scripts de salvamento copiados.
local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")
-- Chamado dentro de cada pcall abaixo, então um jogo que ainda não foi publicado
-- (sem acesso a data store) ainda ganha o seu leaderboard
local function statsStore(): DataStore
return DataStoreService:GetDataStore("PlayerStats_v1")
end
-- Jogadores cujos stats salvos carregaram. Quem não está aqui nunca é salvo,
-- então um carregamento que falhou não sobrescreve progresso de verdade com 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)
-- Quando o servidor desliga, salva todo mundo antes de fechar
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)
Isto basta para um jogo pequeno. Para novas tentativas, UpdateAsync, limites de requisições e proteção contra dois servidores gravando o mesmo jogador, continue no tutorial de DataStore.
Passo 4: Um top 10 global
O leaderstats só compara jogadores no mesmo servidor. Um ranking global precisa de um ordered data store: um data store que guarda um número por chave e consegue devolver as chaves ordenadas pelo valor. Grave a pontuação de cada jogador nele a partir do servidor, depois leia as primeiras entradas.
Há dois jeitos de mostrar. A lista de jogadores do Roblox tem as visões Friends e Global, que leem de um ordered data store que você registra no Creator Hub (um recurso beta quando este texto foi escrito, um leaderboard ativo por jogo). Ou você pode desenhar o ranking você mesmo em um painel no seu mundo, o que funciona em todo jogo e deixa você escolher o visual. O script abaixo faz a segunda opção, e as pontuações que ele grava usam o user ID do jogador como chave, que também é o formato que o leaderboard do Creator Hub espera.
- Adicione uma Part ancorada ao Workspace, chame de
WinsBoarde dê o tamanho de uma placa (por exemplo 12 por 8 por 1 studs), com a face da frente virada para o seu spawn. - Insira um Script no ServerScriptService chamado
GlobalWinsBoardcom o código abaixo. - Jogue. O painel se preenche depois da primeira atualização, e atualiza a cada minuto.
local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")
local winsBoard = DataStoreService:GetOrderedDataStore("GlobalWins_v1")
local TOP_N = 10
local REFRESH_SECONDS = 60
-- O painel: uma Part ancorada chamada WinsBoard no Workspace. O script adiciona
-- a SurfaceGui e as linhas sozinho, então a Part é tudo o que você precisa construir.
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
O GetSortedAsync(false, 10) devolve os 10 maiores valores primeiro. Ordered data stores só guardam números inteiros, então salve as pontuações como inteiros. O script grava cada jogador uma vez por minuto e lê o top 10 uma vez por minuto, bem dentro dos limites padrão por servidor (30 + 5 por jogador por minuto para gravações ordenadas e 5 + 2 por jogador para leituras ordenadas, conforme a documentação em 30 de setembro de 2026).
Erros comuns e como resolver
Os problemas abaixo explicam a maioria dos posts de "meu leaderboard não funciona". Confira primeiro a janela Output (abra pelo menu Window do Studio ou pela aba Script): se um script deu erro, o número da linha está lá.
O leaderboard não aparece
Confira se o nome da pasta é leaderstats em minúsculas, se ela é filha do Player (não do personagem), e se o código é um Script no ServerScriptService, não um LocalScript.
Os outros jogadores não veem a mudança no meu stat
O valor foi mudado no cliente. Leve a mudança para um Script de servidor e, se um botão ou uma tecla a dispara, envie um RemoteEvent e deixe o servidor mudar o valor.
attempt to index nil with 'Coins'
O código tentou ler player.leaderstats.Coins antes de a pasta existir, ou o nome está escrito diferente. No servidor, use FindFirstChild e confira o resultado; em um LocalScript, use player:WaitForChild("leaderstats"). O guia de erros de script explica este erro em detalhes.
As moedas sobem 10, 20 ou 50 com um toque
O Touched dispara repetidas vezes enquanto as parts se sobrepõem. Adicione um cooldown por jogador como no Passo 2, ou remova o item quando ele for coletado.
Os stats zeram toda vez que eu entro de novo
O Roblox não salva o leaderstats. Adicione o script do Passo 3. Para testar o salvamento no Studio, publique o jogo e ative Studio Access to API Services em Experience Settings.
Crie com o RoCode
Se você prefere não montar isso à mão, o RoCode pode construir dentro do jogo que você tem aberto. Ele é um agente de IA que trabalha por meio de um plugin do Roblox Studio, então cria os scripts e as parts no seu Explorer em vez de te dar código para colar.
Adicione um leaderboard com Coins e Wins que salva entre sessões, e um painel de top 10 de vitórias em uma part perto do spawn.
- Pode procurar no seu jogo antes um código de leaderstats ou de DataStore que já existe, para ampliar o que você tem em vez de adicionar um segundo leaderboard
- Cria o script de servidor no ServerScriptService e a part do painel no Workspace
- Compila os scripts que escreveu dentro do Studio antes de terminar
- Envia as mudanças em lotes, e cada lote vira um ponto de desfazer no histórico do Studio
Você ainda revisa o resultado e testa os stats e o salvamento você mesmo: com o plugin 3.9 ou mais recente, o RoCode pode rodar um teste curto e ler os erros, e com o plugin 3.9.11 ou mais recente ele pode controlar um personagem de teste e conferir valores como Coins e Wins, mas ele confere só o que escolheu testar. O leaderstats costuma ser o primeiro de muitos sistemas em um jogo: construa o resto do seu jogo um sistema por prompt do mesmo jeito. Como o RoCode se conecta ao Studio.
Perguntas frequentes
O que é leaderstats no Roblox?
Uma Folder chamada exatamente leaderstats, tudo minúsculo, dentro de um Player. O Roblox mostra cada IntValue, NumberValue ou StringValue dentro dela como uma coluna na lista de jogadores. Crie a pasta a partir de um Script de servidor, como no Passo 1.
Como fazer um leaderboard global no Roblox?
Grave a pontuação de cada jogador em um ordered data store a partir do servidor, depois leia as primeiras entradas e mostre em um painel no seu mundo. O Passo 4 tem o script completo de um top 10.
O Roblox salva o leaderstats automaticamente?
Não. O leaderstats só existe enquanto o jogador está no servidor. Salve os valores com um data store quando o jogador sai e carregue quando ele entra, como no Passo 3.
Dá para esconder um valor do leaderboard?
Sim. Só os valores dentro da pasta leaderstats aparecem. Guarde dados privados em outra pasta no jogador, ou em uma tabela em um script de servidor.
Como esconder a lista de jogadores inteira?
Em um LocalScript, chame StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, false). Passe true para mostrar de novo.
Posso usar um NumberValue para as moedas?
Pode, mas um IntValue serve melhor para uma moeda de números inteiros, e ordered data stores só aceitam números inteiros se mais tarde você quiser fazer um ranking por ela.
Fontes e leitura extra
- Roblox Creator Docs: Leaderboards (em inglês). leaderstats, ordem dos stats e as visões persistentes Friends e Global
- Roblox Creator Docs: Data stores (em inglês). GetAsync, SetAsync, ordered data stores e limites
Como o código foi verificado: todo script desta página passa no verificador de tipos estrito do Luau com as definições da API do Roblox (luau-lsp, 12 de novembro de 2026). A verificação de tipos pega APIs com nome errado e tipos incorretos, não a lógica do jogo, então teste no Studio antes de publicar.