重點摘要
建立一個 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 Script
- 在 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 中你可能比這個 Script 更早進入,所以也替已經在場的人設定
for _, player in Players:GetPlayers() do
setupLeaderstats(player)
end
最後的迴圈在 Studio 測試時很重要:第一位玩家有時會在 PlayerAdded 連接之前就進入,沒有這個迴圈就會沒有數據。
步驟 2:安全地發放分數
要修改數據,就從伺服器 Script 設定它的 Value。這個金幣踏板會在玩家碰到時給 10 枚金幣。角色站在零件上時,Touched 每秒會觸發很多次,所以 Script 替每位玩家保留短暫的冷卻時間。
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 枚金幣後在終點踏板給 1 Win;點擊模擬器教學在按下按鈕時給 Coins,並在伺服器上限制點擊次數;劍的教學會替玩家死亡前最後一擊的人的 Kills 加 1;槍的教學則示範如何在一槍讓目標 Health 歸 0 時計入擊殺。
步驟 3:跨遊戲階段儲存數據
leaderstats 只在伺服器存在期間存在。要保留金幣和勝場,請在玩家進入時從 data store 載入,離開時儲存。這個版本取代步驟 1 的 Script。它絕對不會儲存資料沒有載入成功的玩家:大多數複製來的儲存 Script 正是因為這個錯誤而清掉玩家進度。
local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")
-- 在下面每個 pcall 裡呼叫,所以尚未發布的場景
-- (無法存取 data store)仍然會有排行榜
local function statsStore(): DataStore
return DataStoreService:GetDataStore("PlayerStats_v1")
end
-- 已成功載入儲存數據的玩家。不在這裡的玩家永遠不會被儲存,
-- 所以載入失敗不會用 0 蓋掉真正的進度。
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(撰寫本文時這是測試版功能,每個遊戲只能有一個啟用中的排行榜)。或者你可以自己把排名畫在遊戲世界中的看板上:這在任何遊戲都能用,外觀也能隨你設計。下面的 Script 用的是第二種方式,它以玩家的 user ID 作為鍵寫入分數,這也正是 Creator Hub 排行榜需要的格式。
- 在 Workspace 中加入一個 Anchored 的 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 的 Anchored Part。Script 會自己加入
-- 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 只存整數,所以分數請以整數儲存。Script 每分鐘寫入每位玩家一次,每分鐘讀取前 10 名一次,遠低於每台伺服器的標準上限(依 2026 年 9 月 30 日的文件,ordered data store 寫入為每分鐘 30 次加每位玩家 5 次,排序讀取為 5 次加每位玩家 2 次)。
常見錯誤與解法
下面的問題涵蓋了大部分「我的排行榜沒有作用」的狀況。請先檢查 Output 視窗(從 Studio 的 Window 選單或 Script 分頁開啟):如果 Script 出錯,那裡會有行號。
排行榜完全沒有出現
確認資料夾名稱是全部小寫的 leaderstats,它的父物件是 Player(而不是角色),而且程式碼是 ServerScriptService 中的 Script,不是 LocalScript。
其他玩家看不到我的數據變化
數值是在用戶端被修改的。把修改移到伺服器 Script;如果是按鈕或按鍵觸發的,就傳送 RemoteEvent,讓伺服器修改數值。
attempt to index nil with 'Coins'
程式碼在資料夾出現之前就試圖讀取 player.leaderstats.Coins,或名稱拼法不同。在伺服器上請使用 FindFirstChild 並檢查結果;在 LocalScript 中請使用 player:WaitForChild("leaderstats")。Script 錯誤教學詳細說明了這個錯誤。
碰一次金幣就加了 10、20 或 50
零件重疊時 Touched 會一再觸發。像步驟 2 那樣替每位玩家加上冷卻時間,或在撿起後刪除物品。
每次重新進入數據都歸零
Roblox 不會儲存 leaderstats。請加入步驟 3 的 Script。要在 Studio 中測試儲存,請發布場景,並在 Experience Settings 中開啟 Studio Access to API Services。
用 RoCode 來做
如果不想手動組裝,RoCode 可以在你開啟的場景中把全部建好。它是透過 Roblox Studio 外掛程式運作的 AI 代理,所以會在你的 Explorer 中建立 Script 與零件,而不是給你一段要貼上的程式碼。
加入一個有 Coins 和 Wins、能跨遊戲階段儲存的排行榜,並在重生點旁邊的零件上做一個勝場前 10 名看板。
- 可以先在場景中搜尋現有的 leaderstats 或 DataStore 程式碼,補強已經有的東西,而不是再加第二個排行榜
- 在 ServerScriptService 中建立伺服器 Script,並在 Workspace 中建立看板用的零件
- 結束前在 Studio 中檢查寫好的 Script 能否編譯
- 分批送出變更,每一批都會在 Studio 紀錄中標記為復原點
結果仍然要由你檢查,並在遊戲中親自測試數據與儲存:使用外掛程式 3.9 或更新版本,RoCode 可以執行短暫的試玩測試並讀取錯誤;使用外掛程式 3.9.11 或更新版本,它能操作測試角色並檢查 Coins 與 Wins 這類數值,但只檢查它自己選定的項目。Leaderstats 通常是遊戲眾多系統中的第一個:用同樣的方式一次要求一個系統,完成遊戲的其他部分。RoCode 如何連接 Studio。
常見問題
Roblox 的 leaderstats 是什麼?
一個名稱正好是 leaderstats、全部小寫、放在 Player 裡的 Folder。Roblox 會把裡面的每一個 IntValue、NumberValue 或 StringValue 顯示為玩家清單中的一欄。請像步驟 1 那樣從伺服器 Script 建立。
Roblox 的全球排行榜要怎麼做?
從伺服器把每位玩家的分數寫進 ordered data store,再把排在最前面的紀錄讀回來,顯示在遊戲世界中的看板上。步驟 4 有前 10 名的完整 Script。
Roblox 會自動儲存 leaderstats 嗎?
不會。leaderstats 只在玩家待在伺服器上時存在。請在玩家離開時用 data store 儲存數值,進入時載入,就像步驟 3。
可以把某個數值從排行榜隱藏嗎?
可以。只有 leaderstats 資料夾裡的數值會顯示。私密資料請放在玩家身上的另一個資料夾,或伺服器 Script 中的表格裡。
要怎麼隱藏整個玩家清單?
從 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 與上限
程式碼如何驗證:本頁每一段 Script 都通過 Luau 嚴格型別檢查,並使用 Roblox API 定義(luau-lsp,2026年11月20日)。型別檢查能找出拼錯的 API 與錯誤的型別,但無法檢查遊戲邏輯,所以發布前請先在 Studio 中測試。