教程 · 玩家数据

Roblox Studio 怎么做排行榜

Roblox 游戏右上角的玩家列表由一个名为 leaderstats 的文件夹控制。本教程从零开始搭建它:服务端脚本、安全发放分数的方法、在会话之间保存,以及全球前 10 名。

更新于 2026年11月20日阅读约 3 分钟作者

要点

创建一个 ServerScriptService 中的 Script,监听 Players.PlayerAdded,创建一个名字正好是 leaderstats(全部小写)的 Folder,并把它设为玩家的子对象。这个文件夹里的每个 IntValue、NumberValue 或 StringValue 都会成为玩家列表中的一列。

  • 只在服务端创建和修改数据。LocalScript 做的修改只有这个玩家自己能看到,其他人都看不到。
  • leaderstats 不会自动保存。如果数值需要保留到下一次会话,请通过 data store 加载和保存。
  • 要做所有玩家的排名,把每个分数写入 ordered data store,然后在你的世界里的展示板上显示,或者使用玩家列表的 Global 模式。
本页内容
  1. leaderstats 的工作原理
  2. 1. 创建 leaderstats
  3. 2. 发放分数
  4. 3. 保存
  5. 4. 全球前 10 名
  6. Common errors
  7. 用 RoCode
  8. 常见问题
  9. 参考资料

leaderstats 的工作原理

示意运行中的游戏里,完成的 leaderstats 脚本和金币踏板。

Roblox 在每个游戏中都会显示玩家列表。当玩家有一个名为 leaderstats 的子 Folder 时,列表会为里面的每个值对象添加一列,并在这名玩家的那一行显示他的数值。列标题就是值对象的 Name。

可以放进 leaderstats 的值对象
对象存储内容适合用于
IntValue整数金币、击杀、胜场、等级
NumberValue小数最快单圈时间、距离
StringValue文本段位或队伍头衔

几乎每个不能用的排行榜都坏在两条规则上。文件夹的名字必须正好是 leaderstats:Leaderstats 或 leaderStats 会被忽略。并且文件夹必须由服务端 Script 创建,因为只有服务端的修改才会复制给所有玩家。如果不确定代码在哪里运行,请先阅读 Script vs LocalScript vs ModuleScript(英文)。

第 1 步:创建 leaderstats 脚本

  1. 在 Explorer 中把鼠标悬停在 ServerScriptService 上,点击 + 按钮,插入一个 Script。
  2. 把它重命名为 Leaderstats,方便以后查找。
  3. 用下面的代码替换它的内容,然后点击 Play。你的名字会出现在玩家列表中,Coins 和 Wins 都是 0。
Script 位置: ServerScriptService 名称: Leaderstats
local Players = game:GetService("Players")

local function setupLeaderstats(player: Player)
	local leaderstats = Instance.new("Folder")
	leaderstats.Name = "leaderstats" -- 名字必须完全一致,全部小写

	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 -- 最后再设置父对象,此时数值已经放进去了
end

Players.PlayerAdded:Connect(setupLeaderstats)

-- 在 Studio 中你可能比这个脚本先进入游戏,所以也要为已经在场的玩家进行设置
for _, player in Players:GetPlayers() do
	setupLeaderstats(player)
end

在 Studio 中测试时,结尾的循环很重要:第一个玩家有时会在 PlayerAdded 连接之前就进入游戏,没有这个循环他就没有数据。

第 2 步:安全地发放分数

要修改一项数据,在服务端脚本中设置它的 Value。这个金币踏板会在玩家碰到它时给 10 个金币。角色站在零件上时,Touched 每秒会触发很多次,所以脚本为每个玩家保留一个短暂的冷却时间。

Script 位置: Workspace 中的零件 名称: 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 每一步会触发很多次;这样可以防止一次触碰付款十次
	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") 也能找到角色,而简单的 hit.Parent 检查会漏掉这种情况。

如果分数是因为玩家在自己屏幕上做的事情而发放的,例如点击按钮,LocalScript 应该通过 RemoteEvent 向服务端请求,由服务端决定是否发放。永远不要让客户端发送数额。RemoteEvent 教程 展示了带检查的这种模式。

四个现成的例子:第一个游戏教程 在赛道上每碰到一枚硬币给 1 Coin,收集 3 枚硬币后在终点踏板给一次 Win;点击模拟器教程 在点击按钮时给 Coins,并在服务端限制点击次数;剑的教程 给在玩家死亡前打出最后一击的人的 Kills 加 1;枪的教程 展示了射击让目标 Health 降到 0 时如何计入击杀。

第 3 步:在会话之间保存数据

leaderstats 只在服务器存在期间存在。要保存金币和胜场,在玩家进入时从 data store 加载它们,在玩家离开时保存。这个版本替换第 1 步的脚本。它永远不会保存数据加载失败的玩家:大多数复制来的存档脚本正是因为这个错误而清空了进度。

Script 位置: ServerScriptService 名称: Leaderstats
local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")

-- 在下面的每个 pcall 内部调用,所以尚未发布的场景
-- (没有 data store 访问权限)仍然能得到排行榜
local function statsStore(): DataStore
	return DataStoreService:GetDataStore("PlayerStats_v1")
end

-- 已成功加载存档数据的玩家。不在这里的玩家永远不保存,
-- 这样加载失败就不会用零覆盖真实的进度。
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)

-- 服务器关闭时,在关闭前保存所有人
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)

对于小游戏来说这就够了。关于重试、UpdateAsync、请求限制,以及防止两个服务器同时写入同一个玩家,请继续阅读 DataStore 教程。

第 4 步:全球前 10 名

leaderstats 只比较同一台服务器上的玩家。全球排名需要 ordered data store:一种每个键存一个数字、并能按数值排序返回键的 data store。从服务端把每个玩家的分数写进去,然后读回排在最前面的记录。

有两种显示方式。Roblox 的玩家列表有 Friends 和 Global 模式,它们读取在 Creator Hub 中注册的 ordered data store(撰写本文时这是一项测试版功能,每个游戏只能有一个活动排行榜)。或者你可以自己在世界里的展示板上绘制排名:这在任何游戏中都能用,而且可以随意设计样式。下面的脚本采用第二种方式,它以玩家的 user ID 作为键写入分数,这也正是 Creator Hub 排行榜所期望的格式。

  1. 在 Workspace 中添加一个锚定的 Part,命名为 WinsBoard,做成招牌大小(例如 12 x 8 x 1 个 stud),正面朝向出生点。
  2. 在 ServerScriptService 中插入一个名为 GlobalWinsBoard 的 Script,写入下面的代码。
  3. 点击 Play。第一次刷新后展示板会被填满,之后每分钟更新一次。
Script 位置: ServerScriptService 名称: 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

-- 展示板:Workspace 中名为 WinsBoard 的锚定 Part。脚本会自己添加
-- SurfaceGui 和各行,所以只需要搭建 Part。
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) 先返回最大的 10 个值。Ordered data store 只存储整数,所以请把分数存为整数。脚本每分钟写入每个玩家一次,每分钟读取一次前 10 名,远在每台服务器的标准限制之内(根据 2026 年 9 月 30 日的文档,ordered data store 的写入为每分钟 30 + 每个玩家 5 次,排序读取为 5 + 每个玩家 2 次)。

常见错误与解决办法

下面的问题涵盖了大多数“我的排行榜不能用”的抱怨。先查看 Output 窗口(在 Studio 的 Window 菜单或 Script 选项卡中打开):如果脚本因错误而停止,那里会有行号。

排行榜完全不显示

检查文件夹是否叫小写的 leaderstats,它的父对象是否是 Player(而不是角色),以及代码是否是 ServerScriptService 中的 Script,而不是 LocalScript。

其他玩家看不到我的数据变化

数值是在客户端修改的。把修改移到服务端 Script 中;如果是按钮或按键触发的,就发送 RemoteEvent,让服务端修改数值。

attempt to index nil with 'Coins'

代码在文件夹出现之前就尝试读取 player.leaderstats.Coins,或者名字拼写不同。在服务端使用 FindFirstChild 并检查结果;在 LocalScript 中使用 player:WaitForChild("leaderstats")。脚本错误教程 详细讲解了这个错误。

一次触碰金币加了 10、20 或 50

零件相交时 Touched 会一次又一次地触发。像第 2 步那样为每个玩家添加冷却时间,或者在拾取后删除物品。

每次重新进入数据都会重置

Roblox 不会保存 leaderstats。添加第 3 步的脚本。要在 Studio 中测试保存,请发布场景,并在 Experience Settings 中启用 Studio Access to API Services。

用 RoCode 来做

如果不想手动搭建,RoCode 可以在你打开的场景里把这一切都做好。它是通过 Roblox Studio 插件工作的 AI 代理,所以它会在你的 Explorer 中创建脚本和零件,而不是给你一段代码让你粘贴。

你输入

添加一个带 Coins 和 Wins 的排行榜,要能在会话之间保存,再在出生点旁边的零件上做一个按胜场排名的前 10 名展示板。

RoCode 的操作
  • 可以先在场景中查找现有的 leaderstats 或 DataStore 代码,在已有内容的基础上补充,而不是再添加第二个排行榜
  • 在 ServerScriptService 中创建服务端脚本,并在 Workspace 中创建展示板零件
  • 完成之前在 Studio 内检查所写脚本能否编译
  • 分批发送修改,每一批都会在 Studio 历史记录中标记为一个撤销点

结果仍然需要你自己检查,并亲自在游戏中测试数据和保存:使用插件 3.9 或更新版本时,RoCode 可以运行一次简短的游戏测试并读取错误,使用插件 3.9.11 或更新版本时,它还可以控制测试角色并检查 Coins 和 Wins 等数值,但它只检查自己选择测试的内容。Leaderstats 通常是游戏众多系统中的第一个:用同样的方式 每个提示词一个系统,搭建游戏的其余部分。RoCode 如何连接 Studio。

常见问题

Roblox 里的 leaderstats 是什么?

Player 内部一个名字正好是 leaderstats(全部小写)的 Folder。Roblox 会把里面的每个 IntValue、NumberValue 或 StringValue 显示为玩家列表中的一列。请像 第 1 步 那样用服务端 Script 创建它。

Roblox 怎么做全球排行榜?

从服务端把每个玩家的分数写入 ordered data store,然后读回排在最前面的记录,并显示在你世界里的展示板上。第 4 步 有前 10 名的完整脚本。

Roblox 会自动保存 leaderstats 吗?

不会。leaderstats 只在玩家留在服务器期间存在。像第 3 步那样,在玩家离开时通过 data store 保存数值,在玩家进入时加载。

能把某个数值从排行榜中隐藏吗?

可以。只有 leaderstats 文件夹里的数值会显示。把私密数据放在玩家身上的另一个文件夹里,或者放在服务端脚本的表中。

怎么隐藏整个玩家列表?

在 LocalScript 中调用 StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, false)。传入 true 可以重新显示。

金币可以用 NumberValue 吗?

可以,但对于整数货币,IntValue 更合适;而且如果以后想用它们做排名,ordered data store 只接受整数。

参考资料

代码如何验证:本页的所有脚本都已用 Roblox API 类型定义(luau-lsp,2026年11月20日)通过 Luau strict 类型检查。类型检查能发现 API 名称写错和类型不匹配,但发现不了游戏逻辑上的错误。发布前请务必在 Studio 中测试。

在你自己的游戏里试试 RoCode。

每天有免费额度,无需绑定银行卡。安装插件,描述你想要的功能,然后看看它在 Studio 里做了什么。