教學 · 玩家資料

如何在 Roblox Studio 用 DataStore 儲存玩家資料

除非伺服器 Script 把資料存起來,否則 Roblox 在兩次遊玩之間不會記得玩家的任何事。這篇教學會帶你做出 PlayerData 模組,透過 DataStoreService 載入、在記憶體中保存並儲存每位玩家的資料,接著說明如何測試、有哪些限制,以及存檔資料是怎麼遺失的。

更新日期 2026年11月20日閱讀約 4 分鐘作者

重點摘要

在伺服器 Script 中使用 DataStoreService:玩家加入時用 GetAsync 載入他的資料,遊玩期間把資料放在表格中,並用 UpdateAsync 定時儲存,也在玩家離開時(PlayerRemoving)與伺服器關閉時(game:BindToClose)儲存。每個呼叫都包在 pcall 中,失敗時重試幾次。

  • 要在 Studio 中測試,請發布場景,並在另一個測試遊戲中開啟 File > Experience Settings > Security > Enable Studio Access to API Services:Studio 使用的資料和正式伺服器相同。
  • 如果玩家的資料沒有載入成功,就絕對不要儲存這位玩家。儲存預設值會蓋掉他真正的進度。
  • 每位玩家只用一個鍵存一個表格,例如 User_12345,並定時儲存,而不是每次變更都存。
  • 如果有交易或付費物品,請加上工作階段鎖定,讓兩台伺服器無法同時儲存同一位玩家。
本頁內容
  1. Studio 存取
  2. DataStore 如何運作
  3. GetAsync 與 UpdateAsync
  4. 1. PlayerData 模組
  5. 模組的結構
  6. 2. 使用資料
  7. 3. 提醒
  8. 4. 在 Studio 中測試
  9. 為什麼資料會遺失
  10. 工作階段鎖定
  11. 限制
  12. 版本與備份
  13. Common errors
  14. With RoCode
  15. 常見問題
  16. 來源與延伸閱讀

開始之前:在測試副本中開啟 Studio 存取

在 Studio 中執行的遊戲,在你允許之前無法存取資料儲存區。這個權限有一個 Roblox 文件特別提醒的陷阱:開啟後 Studio 讀寫的是和正式遊戲相同的資料儲存區,所以在 Studio 中把你的金幣歸零的測試,也會讓正式遊戲中的金幣歸零,而測試程式碼中的錯誤可能會毀掉真實玩家的鍵。

  1. 建立測試副本。把場景存成檔案,打開副本,選擇 File > Publish to Roblox As 並按下 Create new game。不要把它加成正式遊戲中的一個場景:同一個遊戲的所有場景都共用相同的資料儲存區。
  2. 在測試副本中打開 File > Experience Settings,切到 Security。
  3. 開啟 Enable Studio Access to API Services 並按下 Save。

資料儲存區的呼叫只能在伺服器的 Script 中運作;嘗試呼叫的 LocalScript 會收到錯誤,所以用戶端無法寫入存檔資料。當按鈕需要改變資料時,用戶端透過 RemoteEvent 請伺服器處理,由伺服器決定(請見RemoteEvents 教學,英文)。

資料儲存區如何保存玩家資料

示意畫面教學步驟 4 的測試加速版:Play,Stop 把這次遊玩存進資料儲存區,再按 Play 會載入它,所以 Output 顯示 200。

資料儲存區(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 秒、玩家離開時與伺服器關閉時儲存,並拒絕儲存資料沒有載入成功的玩家。

  1. 在 Explorer 中把滑鼠移到 ServerScriptService 上,按下 + 並插入 ModuleScript。把它重新命名為 PlayerData,並用下面的程式碼取代裡面的內容。
  2. ModuleScript 只有在某個 Script 載入(require)它時才會執行。在 ServerScriptService 中插入名為 Main 的 Script,寫上這一行:local PlayerData = require(game:GetService("ServerScriptService").PlayerData)。其他伺服器 Script 也用同樣的方式載入它。
  3. 依照你的遊戲修改 DEFAULTS 與 Data 型別,每個欄位都要是數字、字串、布林值或表格。
完成步驟 1 到 3 後的 Explorer
ServerScriptService
    PlayerData ModuleScript new
    Main Script new
StarterPlayer
    StarterPlayerScripts
        DataWarning LocalScript new
ModuleScript 位於 ServerScriptService 名稱為 PlayerData
-- 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 時顯示橫幅。

LocalScript 位於 StarterPlayerScripts 名稱為 DataWarning
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 存取的測試副本中進行。

  1. 給自己一些要儲存的東西。在 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)
  2. 按下 Play。Output 視窗(在 Window 選單或 Script 分頁)會顯示你的名字和 100(第一次執行時),沒有 Could not load 警告。
  3. 按下 Stop。結束測試會關閉伺服器,模組會在關閉前儲存你的資料。
  4. 再按一次 Play。Output 應該顯示 200,比上次多 100。如果它又顯示同一個數字,表示儲存沒有成功:請看它上面的警告。
  5. 測試失敗的情況。關閉 Studio 存取並按下 Play。經過幾秒的重試後,Output 會顯示 Could not load User_... 與 100,並出現步驟 3 的橫幅。停止測試,重新開啟存取並按下 Play:Output 會顯示 300,也就是你存下的 200 加上 100,因為失敗的那次遊玩從來沒有覆蓋你的資料。
  6. 從 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,或有序儲存區的 GetSortedAsync5 + 2 × 玩家數5 + 2 × 玩家數
刪除:RemoveAsync60 + 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。

RoCode 會做
  • 可以用 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 會讓所有人從零開始;絕對不要在正式遊戲中這樣做。

來源與延伸閱讀

程式碼如何驗證:本頁每一段 Script 都通過 Luau 嚴格型別檢查,並使用 Roblox API 定義(luau-lsp,2026年11月20日)。型別檢查能找出拼錯的 API 與錯誤的型別,但無法檢查遊戲邏輯,所以發布前請先在 Studio 中測試。

在你自己的遊戲裡試試 RoCode。

每天都有免費點數,不需要信用卡。安裝外掛程式,描述你要的功能,再看看 Studio 裡出現了什麼。