Tutorial · Dados do jogador

Como fazer um leaderboard no Roblox Studio

A lista de jogadores no canto superior direito de um jogo do Roblox é controlada por uma pasta chamada leaderstats. Este guia monta tudo do zero: o script de servidor, um jeito seguro de dar pontos, salvar entre sessões e um top 10 global.

Atualizado em 12 de novembro de 20268 min de leituraEscrito por

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
  1. Como funciona
  2. 1. Criar leaderstats
  3. 2. Dar pontos
  4. 3. Salvar stats
  5. 4. Top 10 global
  6. Erros comuns
  7. Com o RoCode
  8. Perguntas frequentes
  9. Fontes e leitura extra

Como o leaderstats funciona

IlustraçãoOs scripts de leaderstats e da plataforma de moedas prontos, em um jogo rodando.

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.

Objetos de valor que você pode colocar no leaderstats
ObjetoGuardaBom para
IntValueNúmeros inteirosMoedas, kills, vitórias, nível
NumberValueNúmeros decimaisMelhor tempo de volta, distância
StringValueTextoCargo 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

  1. No Explorer, passe o mouse sobre ServerScriptService, clique no botão + e insira um Script.
  2. Renomeie para Leaderstats para achar depois.
  3. 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.
Script em ServerScriptService chamado Leaderstats
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.

Script em uma Part do Workspace chamado 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 -- 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.

Script em ServerScriptService chamado Leaderstats
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.

  1. Adicione uma Part ancorada ao Workspace, chame de WinsBoard e dê o tamanho de uma placa (por exemplo 12 por 8 por 1 studs), com a face da frente virada para o seu spawn.
  2. Insira um Script no ServerScriptService chamado GlobalWinsBoard com o código abaixo.
  3. Jogue. O painel se preenche depois da primeira atualização, e atualiza a cada minuto.
Script em ServerScriptService chamado 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

-- 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.

Você digita

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.

O RoCode faz
  • 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

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.

Teste o RoCode no seu próprio jogo.

Créditos grátis todo dia, sem cartão. Instale o plugin, descreva o recurso e confira o que aparece no Studio.