重點摘要
在伺服器 Script 中使用 DataStoreService:玩家加入時用 GetAsync 載入他的資料,遊玩期間把資料放在表格中,並用 UpdateAsync 定時儲存,也在玩家離開時(PlayerRemoving)與伺服器關閉時(game:BindToClose)儲存。每個呼叫都包在 pcall 中,失敗時重試幾次。
- 要在 Studio 中測試,請發布場景,並在另一個測試遊戲中開啟 File > Experience Settings > Security > Enable Studio Access to API Services:Studio 使用的資料和正式伺服器相同。
- 如果玩家的資料沒有載入成功,就絕對不要儲存這位玩家。儲存預設值會蓋掉他真正的進度。
- 每位玩家只用一個鍵存一個表格,例如
User_12345,並定時儲存,而不是每次變更都存。 - 如果有交易或付費物品,請加上工作階段鎖定,讓兩台伺服器無法同時儲存同一位玩家。
本頁內容
開始之前:在測試副本中開啟 Studio 存取
在 Studio 中執行的遊戲,在你允許之前無法存取資料儲存區。這個權限有一個 Roblox 文件特別提醒的陷阱:開啟後 Studio 讀寫的是和正式遊戲相同的資料儲存區,所以在 Studio 中把你的金幣歸零的測試,也會讓正式遊戲中的金幣歸零,而測試程式碼中的錯誤可能會毀掉真實玩家的鍵。
- 建立測試副本。把場景存成檔案,打開副本,選擇 File > Publish to Roblox As 並按下 Create new game。不要把它加成正式遊戲中的一個場景:同一個遊戲的所有場景都共用相同的資料儲存區。
- 在測試副本中打開 File > Experience Settings,切到 Security。
- 開啟 Enable Studio Access to API Services 並按下 Save。
資料儲存區的呼叫只能在伺服器的 Script 中運作;嘗試呼叫的 LocalScript 會收到錯誤,所以用戶端無法寫入存檔資料。當按鈕需要改變資料時,用戶端透過 RemoteEvent 請伺服器處理,由伺服器決定(請見RemoteEvents 教學,英文)。
資料儲存區如何保存玩家資料
資料儲存區(data store)是 Roblox 伺服器上一組有名稱的鍵與值,由你遊戲的所有伺服器與所有場景共用。DataStoreService:GetDataStore("PlayerData") 會回傳一個這樣的儲存區。
Roblox 的建議可以歸納成一條規則:玩家資料用一個儲存區,每位玩家一個鍵,每個鍵一個表格。用玩家的 UserId 組成鍵,例如 User_12345,絕對不要用他可以更改的名稱。固定的 User_{UserId} 格式,也能讓 Roblox 的被遺忘權自動處理(如果你有設定)找到玩家的資料。
| 類型 | 能儲存嗎? | 備註 |
|---|---|---|
| 數字、字串、布林值、緩衝區 | 可以 | 字串必須是有效的 UTF-8。不要儲存 inf 或 nan。 |
| 表格 | 可以 | 前提是裡面的所有東西也都能儲存。數字鍵不是從 1 開始的表格(所以長度為 0),取回時這些鍵會變成字串。 |
Instance, Vector3, CFrame, Color3 | 不行 | 儲存時會出錯,或寫入 nil。請改存物品名稱,或用三個數字存位置。 |
每個請求都是一次網路呼叫,可能失敗、需要時間,而且會用掉每分鐘的額度。因此可靠的存檔系統會在玩家加入時讀取一次資料,遊玩期間把資料放在伺服器的表格中,然後不時寫回去。
GetAsync、SetAsync 還是 UpdateAsync:該選哪個
| 方法 | 作用 | 用途 |
|---|---|---|
GetAsync(key) | 讀取一個值。結果會在這台伺服器上快取 4 秒。 | 載入玩家資料 |
SetAsync(key, value) | 不讀取就直接覆寫值。一次寫入。 | 新的鍵,或與舊值無關的值 |
UpdateAsync(key, callback) | 讀取最新的值,傳給你的函式,並寫入函式回傳的內容。一次讀取加一次寫入。 | 儲存玩家資料,以及任何可能有多台伺服器寫入的鍵 |
IncrementAsync(key, delta) | 把一個整數加到存下來的整數上。 | 計數器 |
RemoveAsync(key) | 刪除鍵並回傳舊值。之前的版本仍然可以列出與讀取。 | 刪除玩家資料 |
SetAsync 是盲寫:如果兩台伺服器幾乎同時儲存同一個鍵,最後寫入的會勝出,不管內容是什麼。UpdateAsync 會先讀取目前的值,如果中間有另一台伺服器寫入,Roblox 會用新的值再執行一次你的函式。只要寫入內容取決於目前的值,或鍵可能有多台伺服器寫入,Roblox 都建議使用它,而玩家資料正是這種情況。這個函式有三條規則:
- 它不能讓出執行(yield):裡面不能有
task.wait()或其他資料儲存區呼叫。 - 它可能執行不只一次,所以只能計算新的值,絕對不要發放物品或觸發事件。
- 回傳
nil會取消寫入。模組用這一點來避免覆蓋由較新版本遊戲存下的資料。
步驟 1:建立 PlayerData 模組
這個 ModuleScript 是唯一和資料儲存區溝通的程式碼。它在玩家加入時載入資料、放在記憶體中,每 180 秒、玩家離開時與伺服器關閉時儲存,並拒絕儲存資料沒有載入成功的玩家。
- 在 Explorer 中把滑鼠移到 ServerScriptService 上,按下 + 並插入 ModuleScript。把它重新命名為
PlayerData,並用下面的程式碼取代裡面的內容。 - ModuleScript 只有在某個 Script 載入(require)它時才會執行。在 ServerScriptService 中插入名為
Main的 Script,寫上這一行:local PlayerData = require(game:GetService("ServerScriptService").PlayerData)。其他伺服器 Script 也用同樣的方式載入它。 - 依照你的遊戲修改
DEFAULTS與Data型別,每個欄位都要是數字、字串、布林值或表格。
ServerScriptService
PlayerData ModuleScript new
Main Script new
StarterPlayer
StarterPlayerScripts
DataWarning LocalScript new
-- PlayerData:玩家加入時載入他的資料,放在記憶體中,
-- 並定時、在玩家離開時與伺服器關閉時儲存。
-- 其他伺服器 Script 透過 PlayerData.Get(player) 讀取與修改資料。
local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")
local RunService = game:GetService("RunService")
local STORE_NAME = "PlayerData"
local SCHEMA_VERSION = 2 -- 資料結構改變時就調高,並在 migrate() 中加入一個步驟
local AUTOSAVE_SECONDS = 180
-- 在 Studio 中失敗的呼叫會立刻放棄,所以沒有儲存區存取權的測試跑得很快
local MAX_ATTEMPTS = if RunService:IsStudio() then 1 else 4
local FIRST_RETRY_SECONDS = 1 -- 每次失敗後加倍:1、2、4
export type Data = {
SchemaVersion: number,
Coins: number,
Level: number,
Inventory: { string },
}
-- 全新玩家的起始資料
local DEFAULTS: { [string]: any } = {
Coins = 0,
Level = 1,
Inventory = {},
}
type Session = {
key: string,
userId: number,
data: Data,
canSave: boolean, -- 載入失敗時為 false:預設資料絕不能取代真正的進度
}
-- 在下面每個 pcall 裡面呼叫,所以還沒發布的場景
-- (沒有儲存區存取權)仍然會用預設資料載入玩家
local function store(): DataStore
return DataStoreService:GetDataStore(STORE_NAME)
end
local sessions: { [Player]: Session } = {}
local pendingSaves: { [string]: number } = {} -- 還在進行中的儲存,依鍵分類
local loadedEvent = Instance.new("BindableEvent")
local PlayerData = {}
-- 玩家的資料準備好時,帶著玩家觸發。表格請透過 PlayerData.Get(player) 取得:
-- 透過 BindableEvent 傳送的表格會變成副本,修改它不會改變任何東西。
PlayerData.Loaded = loadedEvent.Event
local function deepCopy(value: any): any
if type(value) ~= "table" then
return value
end
local copy = {}
for key, item in value do
copy[key] = deepCopy(item)
end
return copy
end
local function defaultData(): Data
local data = deepCopy(DEFAULTS) -- 全新的副本,讓玩家永遠不會共用同一個 Inventory 表格
data.SchemaVersion = SCHEMA_VERSION
return data
end
-- 把存下來的資料轉成目前的結構。如果無法安全使用,就回傳 nil。
local function migrate(saved: any): Data?
if type(saved) ~= "table" then
return nil
end
local version = tonumber(saved.SchemaVersion) or 1
if version > SCHEMA_VERSION then
return nil -- 由較新版本的遊戲存下:這裡不要載入也不要覆寫
end
-- 每次結構變更一個步驟,從舊到新
if version < 2 then
-- 範例:在版本 1 中貨幣叫做 Gold。只有在沒有 Coins 時才複製它,
-- 讓已經有 Coins 但沒有 SchemaVersion 的舊資料保留原本的值。
if saved.Coins == nil then
saved.Coins = saved.Gold
end
saved.Gold = nil
end
-- 加入玩家上次存檔後才新增的欄位,並替換類型錯誤的值
for field, default in DEFAULTS do
if type(saved[field]) ~= type(default) then
saved[field] = deepCopy(default)
end
end
saved.SchemaVersion = SCHEMA_VERSION
return saved
end
-- 在 pcall 中執行資料儲存區呼叫。失敗時等待後再試,每次都把
-- 等待時間加倍,並加上一點隨機,讓伺服器不會全部同時重試。
local function withRetries(label: string, call: () -> any): (boolean, any)
for attempt = 1, MAX_ATTEMPTS do
local ok, result = pcall(call)
if ok then
return true, result
end
warn(`{label} failed (attempt {attempt} of {MAX_ATTEMPTS}): {result}`)
if attempt < MAX_ATTEMPTS then
local waitTime = FIRST_RETRY_SECONDS * 2 ^ (attempt - 1)
task.wait(waitTime + math.random() * waitTime / 2)
end
end
return false, nil
end
local function save(session: Session): boolean
if not session.canSave then
return false
end
local key = session.key
pendingSaves[key] = (pendingSaves[key] or 0) + 1
local newerSchema = false
local ok = withRetries(`Save {key}`, function()
return store():UpdateAsync(key, function(current: any)
if type(current) == "table" and (tonumber(current.SchemaVersion) or 1) > SCHEMA_VERSION then
newerSchema = true
return nil -- 回傳 nil 會取消寫入
end
-- 寫入目前整個表格,並標上玩家的 UserId
return session.data, { session.userId }
end)
end)
local left = (pendingSaves[key] or 1) - 1
if left > 0 then
pendingSaves[key] = left
else
pendingSaves[key] = nil
end
if newerSchema then
session.canSave = false
warn(`{key} was saved by a newer version of the game, so this server stopped saving it`)
end
return ok and not newerSchema
end
local function startAutosave(player: Player, session: Session)
task.spawn(function()
-- 從間隔中的隨機時間點開始,讓伺服器不會全部同時儲存
task.wait(math.random() * AUTOSAVE_SECONDS)
while sessions[player] == session do
save(session)
task.wait(AUTOSAVE_SECONDS)
end
end)
end
local function load(player: Player)
local key = "User_" .. player.UserId
-- 如果玩家剛離開這台伺服器又回來,先讓上一次儲存完成
while pendingSaves[key] do
task.wait()
end
local ok, saved = withRetries(`Load {key}`, function()
return store():GetAsync(key)
end)
if player.Parent ~= Players then
return -- 在載入中離開:什麼都沒變,沒有東西要存
end
local data: Data? = nil
if ok then
data = if saved == nil then defaultData() else migrate(saved)
end
local session: Session = {
key = key,
userId = player.UserId,
data = data or defaultData(),
canSave = data ~= nil,
}
if not session.canSave then
warn(`Could not load {key}. {player.Name} is playing on default data that will not be saved.`)
end
sessions[player] = session
player:SetAttribute("DataLoaded", session.canSave) -- GUI 可以讀取這個值並提醒玩家
startAutosave(player, session)
loadedEvent:Fire(player)
end
local function endSession(player: Player)
local session = sessions[player]
if not session then
return
end
sessions[player] = nil -- 停止自動存檔迴圈,再次呼叫也不會有任何作用
save(session)
end
-- 玩家目前的資料表格,載入前為 nil。只能從伺服器 Script 修改它。
function PlayerData.Get(player: Player): Data?
local session = sessions[player]
return if session then session.data else nil
end
-- 玩家資料已載入並會被儲存時為 true。任何販售之前都要先檢查。
function PlayerData.CanSave(player: Player): boolean
local session = sessions[player]
return session ~= nil and session.canSave
end
-- 不等計時器,立刻儲存,用於購買等重要時刻。
-- 會讓出執行,儲存成功時回傳 true。
function PlayerData.SaveNow(player: Player): boolean
local session = sessions[player]
return session ~= nil and save(session)
end
Players.PlayerAdded:Connect(load)
Players.PlayerRemoving:Connect(endSession)
for _, player in Players:GetPlayers() do
task.spawn(load, player) -- 在這個模組第一次被載入之前就加入的玩家
end
game:BindToClose(function()
-- 伺服器給這些函式 30 秒,所以同時儲存所有人
for player in sessions do
task.spawn(endSession, player)
end
-- 接著等待所有還在進行中的儲存,包括在 PlayerRemoving 中開始的
while next(pendingSaves) do
task.wait()
end
end)
return PlayerData
遊戲上線後,不要更改 STORE_NAME 與 User_ 鍵格式。更改其中任何一個都會讓模組指向空的鍵,每位玩家都會從預設值重新開始。
模組如何保護資料
預設值與結構版本
新玩家會拿到一份全新的 DEFAULTS 副本。這一定要是副本:如果所有玩家共用同一個 Inventory 表格,加給一位玩家的物品會出現在所有人身上。
每個存下來的表格都帶有 SchemaVersion。新增欄位不需要新版本,因為 migrate 會用預設值補上缺少的欄位。重新命名或重組則需要:調高 SCHEMA_VERSION 並加入一個步驟,就像範例把 Gold 重新命名為 Coins 那樣(新遊戲請刪掉它,從 1 開始)。版本比伺服器高的資料來自還在推出中的較新版本,所以舊伺服器不會動它。
載入失敗的資料絕不儲存
這條規則可以防止資料被整個清空。如果所有載入嘗試都失敗,玩家會用預設資料遊玩,但 canSave 為 false,所以這些值永遠不會覆蓋他真正的進度。模組也會把 DataLoaded 屬性設為 false,步驟 3 用它來通知玩家。Roblox 的參考範例也用同樣的方式處理載入失敗,並建議以此取代踢出玩家;如果你比較想踢出,就在模組輸出警告的地方呼叫帶有訊息的 player:Kick()。
逐漸拉長間隔的重試
withRetries 把每個呼叫包在 pcall 中。失敗後它會等 1 秒、2 秒、4 秒,每次再加上最多一半時間的隨機值,並在四次嘗試後停止(在 Studio 中一次後就停止,讓沒有儲存區存取權的場景立刻啟動)。隨機值能把大量伺服器在故障後的重試分散開來,而次數上限讓等待時間維持在大約 10 秒內,在伺服器關閉時可用的 30 秒之內。由於每次儲存都透過 UpdateAsync 寫入目前的整個表格,較晚完成的重試不會讓舊資料回來。
模組什麼時候儲存
| 時機 | 原因 |
|---|---|
| 玩家在伺服器上時每 180 秒一次 | 限制當機時的損失。第一次儲存落在間隔中的隨機時間點,讓伺服器不會全部同時儲存。Roblox 的參考範例也使用 180 秒。 |
玩家離開時(PlayerRemoving) | 一般的最後一次儲存。工作階段會先被移除,所以自動存檔會停止。 |
伺服器關閉時(game:BindToClose) | 還在伺服器上的所有人會同時儲存,函式會等待每個進行中的儲存。Roblox 給它 30 秒。 |
依需求,透過 PlayerData.SaveNow(player) | 在不能遺失的事情之後,例如購買。 |
如果玩家在最後一次儲存還在進行時重新加入同一台伺服器,新的載入會等到那次儲存完成,所以不會讀到舊的值。
步驟 2:從其他 Script 讀取與修改資料
所有載入這個模組的伺服器 Script 都操作同一組表格:
| 呼叫 | 作用 |
|---|---|
PlayerData.Get(player) | 玩家目前的資料表格,載入前為 nil。直接修改欄位,例如 data.Coins += 10,下一次儲存就會存下來。 |
PlayerData.Loaded | 玩家的資料準備好時,帶著玩家觸發,載入失敗後也一樣。它只傳送玩家,因為透過 BindableEvent 傳送的表格會變成副本。 |
PlayerData.CanSave(player) | 載入失敗時為 false。任何販售之前都要先檢查:無法儲存的購買會在玩家離開時消失。 |
PlayerData.SaveNow(player) | 立刻儲存,成功時回傳 true。會讓出執行。 |
模組是存檔資料唯一的存放處,leaderstats 只是顯示用:依照排行榜教學建立它,在 Loaded 處理函式中用 PlayerData.Get(player) 填入數值,並在值改變時兩邊都更新。絕對不要從 leaderstats 讀回存檔的值,也絕對不要讓第二個 Script 儲存同一個鍵。
在玩家加入之後才載入模組的 Script,會錯過這些玩家的 Loaded。先連接處理函式,再用迴圈走過 Players:GetPlayers(),處理所有 PlayerData.Get(player) 已經回傳表格的玩家。
要取代舊的存檔 Script,例如排行榜教學中的那個?它的值留在它自己的儲存區與鍵中,所以這個模組會讓所有人從預設值開始。上線之前,可以把 STORE_NAME 與 User_ 前綴指向舊的(migrate 會把沒有 SchemaVersion 的資料視為版本 1 並補上缺少的欄位),或是把舊的值搬過來,然後刪除舊的 Script。
用戶端絕對不能直接修改這些資料。商店按鈕觸發 RemoteEvent;伺服器檢查 CanSave,把價格和玩家的 Coins 比較,修改表格並呼叫 SaveNow。商店 GUI 教學會在伺服器端做出這樣的購買。
新增欄位的完整範例在點擊模擬器教學中:它把 PowerLevel 與 Rebirths 加到 DEFAULTS 與 Data 型別中,然後在 PlayerData.Get 回傳的表格中修改它們。migrate 會把新欄位發給有舊存檔的玩家。
步驟 3:告訴玩家他的資料沒有載入成功
資料沒有載入成功的玩家應該知道這次遊玩不會被儲存,這樣他才會重新加入,而不是白玩一場。這個 LocalScript 監看 DataLoaded 屬性,在它為 false 時顯示橫幅。
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local shown = false
local function showWarning()
if shown or player:GetAttribute("DataLoaded") ~= false then
return
end
shown = true
local gui = Instance.new("ScreenGui")
gui.Name = "DataWarning"
gui.ResetOnSpawn = false
local label = Instance.new("TextLabel")
label.AnchorPoint = Vector2.new(0.5, 0)
label.Position = UDim2.new(0.5, 0, 0, 12)
label.Size = UDim2.new(0.8, 0, 0, 48)
label.BackgroundColor3 = Color3.fromRGB(110, 28, 28)
label.TextColor3 = Color3.new(1, 1, 1)
label.TextScaled = true
label.Text = "Your saved progress could not be loaded. Nothing you do in this server will be saved, so rejoin later."
label.Parent = gui
gui.Parent = player:WaitForChild("PlayerGui")
end
-- 伺服器在嘗試載入這位玩家的資料後,會設定一次 DataLoaded
player:GetAttributeChangedSignal("DataLoaded"):Connect(showWarning)
showWarning()
步驟 4:在 Studio 中測試存檔
請在已開啟 Studio 存取的測試副本中進行。
- 給自己一些要儲存的東西。在
Main的 require 那一行下面加上:PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end) - 按下 Play。Output 視窗(在 Window 選單或 Script 分頁)會顯示你的名字和 100(第一次執行時),沒有
Could not load警告。 - 按下 Stop。結束測試會關閉伺服器,模組會在關閉前儲存你的資料。
- 再按一次 Play。Output 應該顯示 200,比上次多 100。如果它又顯示同一個數字,表示儲存沒有成功:請看它上面的警告。
- 測試失敗的情況。關閉 Studio 存取並按下 Play。經過幾秒的重試後,Output 會顯示
Could not load User_...與 100,並出現步驟 3 的橫幅。停止測試,重新開啟存取並按下 Play:Output 會顯示 300,也就是你存下的 200 加上 100,因為失敗的那次遊玩從來沒有覆蓋你的資料。 - 從
Main刪除測試用的那一行。
為什麼玩家資料會遺失
以下是存檔系統常見的進度遺失方式。模組在程式碼中處理了前四列與結構那一列;其他則取決於你存什麼、怎麼存,最後一列則需要工作階段鎖定。
| 發生什麼事 | 結果 | 如何避免 |
|---|---|---|
| 載入失敗,Script 卻照樣儲存 | 預設值蓋掉真正的進度:資料被整個清空 | 絕不儲存載入失敗的玩家 |
只在 PlayerRemoving 中儲存 | 伺服器當機或關閉時會漏掉儲存 | 自動存檔,再加上會等待自己儲存完成的 BindToClose |
沒有 pcall 或沒有重試 | 一個失敗的請求就會讓 Script 停止或遺失一次儲存 | pcall 加上幾次錯開時間的重試 |
| 每次變更都儲存 | 請求開始排隊;佇列中有 30 個時,新的請求會被捨棄 | 把資料放在記憶體中並定時儲存 |
| 儲存資料儲存區無法保存的東西 | 儲存時出錯,或取回的值為 nil | 儲存數字、字串、布林值以及由它們組成的表格 |
| 改變資料結構卻沒有遷移 | 舊存檔被載入到錯誤的欄位 | 結構版本與遷移步驟 |
| 兩個 Script 儲存同一個鍵 | 每次儲存都會蓋掉另一個 Script 的欄位 | 只由一個模組負責這個鍵 |
| 兩台伺服器同時持有同一位玩家 | 持有舊資料的伺服器最後儲存,蓋掉新的進度 | 工作階段鎖定 |
工作階段鎖定、「lock lost」與 ProfileStore
玩家一次只會連到一台伺服器,但他加入新伺服器時,舊伺服器的最後一次儲存可能還在進行:重試很慢、傳送,或很快就重新加入。如果新伺服器先載入資料,它拿到的就是舊資料,而最後儲存的伺服器會勝出。Roblox 文件指出,在有交易的遊戲中,這個空檔是物品被複製的常見原因。
工作階段鎖定可以填補這個空檔。伺服器載入玩家的鍵時,會在同一次 UpdateAsync 呼叫中把自己的鎖定 ID 寫進鍵的中繼資料。任何其他伺服器發現有未過期、且不是自己設定的鎖定時,都不會載入或儲存這個鍵。持有者會在每次自動存檔時更新鎖定,並在最後一次儲存時解除;如果它停止更新,鎖定就會過期,其他伺服器就能接手。
「lock lost」是什麼意思
在有工作階段鎖定的系統中,當玩家的鍵現在由另一台伺服器持有(因為鎖定過期或被搶走)時,原本的伺服器就失去了鎖定。它手上的副本可能已經過時,所以必須停止儲存這位玩家;常見的做法是帶著訊息把他踢出,讓他重新連線。如果你是以玩家身分看到「lock lost」,那是那個遊戲自己的存檔系統的訊息,只有它的開發者能解釋。
你需要它嗎?
這篇教學的模組沒有工作階段鎖定。沒有鎖定時,實際上最糟的情況是:在罕見的競爭狀況下,玩家會失去他在舊伺服器上、最後一次成功儲存之後賺到的東西。當物品被複製或遺失會讓玩家損失真正有價值的東西時,就加上鎖定:交易、developer product、稀有物品或頻繁的傳送。
| 選項 | 是什麼 | 需要知道的事 |
|---|---|---|
| 這篇教學的模組 | 載入、記憶體快取、重試、自動存檔、關閉時儲存與結構版本,沒有鎖定 | 夠短,可以整個讀完並修改 |
| Roblox 的玩家資料與購買範例 | Roblox 提供的參考程式碼,有工作階段鎖定、每個鍵依序重試,以及購買收據處理 | Roblox 說它沒有在熱門遊戲中經過時間考驗,不經過大量測試不應該直接使用 |
| ProfileStore | 免費的開放原始碼社群模組,是 ProfileService 的後繼者,以工作階段鎖定與自動存檔為核心 | 不是 Roblox 官方的。把現有遊戲改用它,需要遷移已經存下的資料 |
對任何第三方模組,Roblox 都建議先確認誰擁有它、是否還有維護,以及沒有它時你要怎麼取得自己的資料。同一份文件也把 DataStore2 列為過時的函式庫,新遊戲不應該使用。
資料儲存區的限制
這些是 Roblox 文件在 2026 年 9 月 30 日的限制。Roblox 會調整它們,所以在依賴確切數字之前,請先查看錯誤代碼與限制頁面(英文)。
| 請求類型 | 一般儲存區 | 有序儲存區 |
|---|---|---|
讀取:GetAsync、UpdateAsync 中的讀取 | 60 + 40 × 玩家數 | 60 + 40 × 玩家數 |
寫入:SetAsync、IncrementAsync、UpdateAsync 中的寫入 | 60 + 40 × 玩家數 | 30 + 5 × 玩家數 |
列出:ListKeysAsync,或有序儲存區的 GetSortedAsync | 5 + 2 × 玩家數 | 5 + 2 × 玩家數 |
刪除:RemoveAsync | 60 + 40 × 玩家數 | 30 + 5 × 玩家數 |
有 20 位玩家時,伺服器每分鐘可以進行 860 次一般寫入;這個模組的自動存檔大約用掉其中 7 次,再加上每位離開的玩家一次。每撿一枚金幣就儲存一次,才會把額度用完。第二個額度適用於整個遊戲,並與 Open Cloud 共用:每分鐘 300 次讀取加上每位線上玩家 40 次,以及 300 次寫入加上每位玩家 20 次。
| 限制 | 數值 |
|---|---|
| 儲存區名稱、鍵名稱、scope | 各 50 個字元 |
| 單一鍵中的值 | JSON 格式 4,194,304 個字元 |
| 所有伺服器讀取單一鍵 | 每分鐘 25 MB |
| 所有伺服器寫入單一鍵 | 每分鐘 4 MB,每個請求無條件進位到下一個 KB |
| 等待中的請求 | 每個佇列 30 個;超過時請求會以錯誤 301-306 失敗 |
| 整個遊戲的儲存空間 | 500 MB,再加上歷來每位使用者 1 MB |
用 #HttpService:JSONEncode(data) 測量玩家資料的大小,並用 DataStoreService:GetRequestBudgetForRequestType(Enum.DataStoreRequestType.StandardWrite) 查看正式伺服器剩下的額度。由 4 秒快取回應的 GetAsync 呼叫不會計入。Studio 的 Run 模式有自己的限制,可能更低,所以要測試請求限制時,Roblox 建議使用 Team Create。
版本與備份
一般資料儲存區會替你保存歷史。每個 UTC 小時中對鍵的第一次寫入會被保存為一個版本,同一小時中之後的寫入則互相覆蓋。舊版本在被較新的寫入取代 30 天後過期;最新的版本永遠不會過期。有序儲存區不保存版本。
要回復某位玩家的資料,打開 Data Stores Manager(Creations、你的遊戲、Configure > Data Stores Manager),選擇他的鍵,選一個較早的版本並按下 Revert;這需要 Edit 權限。請在玩家離線時進行,否則持有他工作階段的伺服器會把自己的副本存在回復的資料上面。在伺服器 Script 中,ListVersionsAsync 與 GetVersionAsync 可以找到並讀取舊版本,然後你再把它寫回去作為目前的值。
在發布會改變資料儲存方式的更新之前,Roblox 建議透過 Open Cloud Snapshot Data Stores API 建立快照(每個遊戲每天一次)。沒有快照的話,在 UTC 3:30 發生的錯誤儲存會蓋掉從 3:00 以來寫進這個鍵的所有內容,因為它落在同一個小時版本中。
常見錯誤與解法
資料儲存區的錯誤會出現在 Studio 的 Output 視窗中,而模組在每次嘗試失敗時都會輸出含有 Roblox 錯誤文字的警告。Script 錯誤教學說明一般該如何看懂 Output。
StudioAccessToApisNotAllowed(錯誤 403)
「Can't write to DataStore from Studio because API access is not enabled.」發布場景,然後在測試副本中開啟 File > Experience Settings > Security 裡的 Enable Studio Access to API Services。
DataStore request was added to queue
伺服器傳送請求的速度超過額度允許的範圍,或太常寫入同一個鍵,通常是因為每次變更或在迴圈中儲存。佇列中有 30 個請求時,新的請求會以錯誤 301-306 失敗。把資料放在記憶體中並定時儲存。
CantStoreValue(錯誤 104),或欄位取回時為 nil
表格中有資料儲存區無法儲存的東西,例如 Instance、Vector3 或 Color3。請改存名稱、ID 或單純的數字,並在載入時重建物件。
ValueTooLarge(錯誤 105)
單一鍵存了超過 4,194,304 個 JSON 字元。用 #HttpService:JSONEncode(data) 測量,移除可以重建的東西,或把資料拆到幾個固定的鍵中。
沒有錯誤,但資料沒有存下來
找找模組的 Could not load 警告:載入失敗後它會刻意拒絕儲存。否則,值很可能是在 LocalScript 中修改的,而那永遠不會傳到伺服器,或是有另一個 Script 在儲存同一個鍵。
每次重新加入資料都被重設
鍵在每次遊玩之間改變了(用 player.Name 組成,或你改了 STORE_NAME)、載入失敗所以你看到的是預設值,或是沒有任何 Script 載入模組,所以它根本沒有執行。檢查 Output,並確認 Main 有載入 PlayerData。
用 RoCode 來做
如果不想手動組裝,RoCode 可以直接在你開啟的場景中完成。它是獨立的 AI 代理,不是 Roblox 官方產品,透過 Roblox Studio 外掛程式運作:它寫出和任何 Script 一樣使用 DataStoreService 的 Luau,並在你的 Explorer 中建立 Script。它自己從來不會存取你的資料儲存區,但搭配 3.9 或更新版本的外掛程式,它可以按下 Play 進行簡短的試玩測試,讓你的 Script 像任何測試一樣執行。
替我的遊戲加入存檔:把 Coins、Level 與 Inventory 存在有自動存檔與伺服器關閉時儲存的 PlayerData 模組中,並在我已經有的 leaderstats 中顯示 Coins。
- 可以用 Search Scripts 與 Read Script 找出現有的 leaderstats 與 DataStore 程式碼,擴充你已經有的部分,而不是再加第二個存檔 Script。在大型場景中,請在訊息中寫出 Script 或資料夾的名稱。
- 用 Create Script 建立 ModuleScript 與載入它的 Script,或用 Edit Script 修改現有的
- 對寫出的每個 Script 執行 Check Script:在 Studio 中檢查能否編譯,並列出簡短的警告清單,不是型別檢查,也不是測試執行
- 分批送出變更,每一批都是 Studio 中的一個復原點(undo)
在測試副本中開啟 Studio Access to API Services 仍然要你自己來:RoCode 無法更改這個設定。搭配 3.9 或更新版本的外掛程式,它的簡短試玩測試會讀取錯誤,搭配 3.9.11 或更新版本,它還能操控測試角色來確認遊戲能運作,但它只會檢查它自己決定要檢查的部分,所以請自己玩一次,確認 Coins、Level 與 Inventory 有被儲存與載入。如果你的測試中儲存沒有成功,Check Output 可以讀取你執行的試玩測試中的 Server 訊息。存檔通常是在主要遊戲循環已經能運作之後才加入;用 AI 一次一個系統製作 Roblox 遊戲會說明這個順序。RoCode 如何連接 Studio。
常見問題
如何在 Roblox Studio 開啟 DataStore?
發布場景,打開 File > Experience Settings > Security,開啟 Enable Studio Access to API Services 並按下 Save。請在另一個測試遊戲中這樣做,因為開啟後 Studio 會使用和這個遊戲正式伺服器相同的資料儲存區。
Roblox 會自動儲存玩家資料嗎?
不會。除非伺服器 Script 透過 DataStoreService 儲存,否則玩家的任何資料都不會在遊玩結束後保留,leaderstats 也一樣。
該選 ProfileStore 還是直接用 DataStoreService?
ProfileStore 也是建立在資料儲存區上,所以問題在於你是否想讓別人替你寫好並維護工作階段鎖定。如果有交易、付費物品或頻繁的傳送,鎖定是值得的,可以用函式庫或 Roblox 的參考範例。規模較小的遊戲,用像這樣的模組比較容易閱讀與修改。
如何重設或刪除玩家資料?
在 Data Stores Manager 中找到鍵並選擇 Mark for Deletion,這在等待期間內可以取消,或從伺服器 Script 對這個鍵呼叫 RemoveAsync。請在玩家離線時進行,否則他所在伺服器的下一次儲存會把資料寫回去。在測試副本中更改 STORE_NAME 會讓所有人從零開始;絕對不要在正式遊戲中這樣做。
來源與延伸閱讀
- Roblox Creator Docs:Data stores(英文). Studio 存取、GetAsync、SetAsync、UpdateAsync、set 與 update
- Roblox Creator Docs:Best practices for data stores(英文). 每位玩家一個鍵、記憶體中的資料、逐漸拉長間隔的重試、第三方模組
- Roblox Creator Docs:Data store error codes and limits(英文). 錯誤代碼、伺服器與遊戲的請求限制、大小、傳輸量與儲存空間限制
- Roblox Creator Docs:Versioning, listing and caching(英文). 每小時版本、快照、4 秒快取、可以儲存的內容
- Roblox Creator Docs:Implement player data and purchasing systems(英文). 參考範例、工作階段鎖定、載入失敗、每 180 秒自動存檔
- Roblox Creator Docs:Data Stores Manager(英文). 檢視鍵、回復版本、刪除資料
- Roblox Engine API:DataModel:BindToClose(英文). 關閉時的 30 秒
程式碼如何驗證:本頁每一段 Script 都通過 Luau 嚴格型別檢查,並使用 Roblox API 定義(luau-lsp,2026年11月20日)。型別檢查能找出拼錯的 API 與錯誤的型別,但無法檢查遊戲邏輯,所以發布前請先在 Studio 中測試。