要点
创建一个 ServerScriptService 中的 Script,监听 Players.PlayerAdded,创建一个名字正好是 leaderstats(全部小写)的 Folder,并把它设为玩家的子对象。这个文件夹里的每个 IntValue、NumberValue 或 StringValue 都会成为玩家列表中的一列。
- 只在服务端创建和修改数据。LocalScript 做的修改只有这个玩家自己能看到,其他人都看不到。
- leaderstats 不会自动保存。如果数值需要保留到下一次会话,请通过 data store 加载和保存。
- 要做所有玩家的排名,把每个分数写入 ordered data store,然后在你的世界里的展示板上显示,或者使用玩家列表的 Global 模式。
leaderstats 的工作原理
Roblox 在每个游戏中都会显示玩家列表。当玩家有一个名为 leaderstats 的子 Folder 时,列表会为里面的每个值对象添加一列,并在这名玩家的那一行显示他的数值。列标题就是值对象的 Name。
| 对象 | 存储内容 | 适合用于 |
|---|---|---|
IntValue | 整数 | 金币、击杀、胜场、等级 |
NumberValue | 小数 | 最快单圈时间、距离 |
StringValue | 文本 | 段位或队伍头衔 |
几乎每个不能用的排行榜都坏在两条规则上。文件夹的名字必须正好是 leaderstats:Leaderstats 或 leaderStats 会被忽略。并且文件夹必须由服务端 Script 创建,因为只有服务端的修改才会复制给所有玩家。如果不确定代码在哪里运行,请先阅读 Script vs LocalScript vs ModuleScript(英文)。
第 1 步:创建 leaderstats 脚本
- 在 Explorer 中把鼠标悬停在 ServerScriptService 上,点击 + 按钮,插入一个 Script。
- 把它重命名为
Leaderstats,方便以后查找。 - 用下面的代码替换它的内容,然后点击 Play。你的名字会出现在玩家列表中,Coins 和 Wins 都是 0。
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 每秒会触发很多次,所以脚本为每个玩家保留一个短暂的冷却时间。
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 步的脚本。它永远不会保存数据加载失败的玩家:大多数复制来的存档脚本正是因为这个错误而清空了进度。
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 排行榜所期望的格式。
- 在 Workspace 中添加一个锚定的 Part,命名为
WinsBoard,做成招牌大小(例如 12 x 8 x 1 个 stud),正面朝向出生点。 - 在 ServerScriptService 中插入一个名为
GlobalWinsBoard的 Script,写入下面的代码。 - 点击 Play。第一次刷新后展示板会被填满,之后每分钟更新一次。
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 名展示板。
- 可以先在场景中查找现有的 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 Creator Docs: Leaderboards(英文). leaderstats、数据项顺序以及持久的 Friends 和 Global 模式
- Roblox Creator Docs: Data stores(英文). GetAsync、SetAsync、ordered data store 和限制
代码如何验证:本页的所有脚本都已用 Roblox API 类型定义(luau-lsp,2026年11月20日)通过 Luau strict 类型检查。类型检查能发现 API 名称写错和类型不匹配,但发现不了游戏逻辑上的错误。发布前请务必在 Studio 中测试。