要点
在 服务端 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 请求服务器,由服务器决定(见 RemoteEvent 教程,英文)。
数据存储是怎么保存玩家数据的
数据存储(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 只有在某个脚本引用(require)它时才会运行。在 ServerScriptService 中插入一个名为
Main的 Script,写上这一行:local PlayerData = require(game:GetService("ServerScriptService").PlayerData)。其他服务端脚本也用同样的方式引用它。 - 按你的游戏修改
DEFAULTS和Data类型,每个字段都保持为数字、字符串、布尔值或表。
ServerScriptService
PlayerData ModuleScript new
Main Script new
StarterPlayer
StarterPlayerScripts
DataWarning LocalScript new
-- PlayerData:玩家进入时加载数据,把数据放在内存中,
-- 并定时、在玩家离开时和服务器关闭时保存。
-- 其他服务端脚本通过 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。只能在服务端脚本中修改它。
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 步:在其他脚本中读取和修改数据
所有引用这个模块的服务端脚本都操作同一批表:
| 调用 | 作用 |
|---|---|
PlayerData.Get(player) | 玩家的实时数据表,加载完成前为 nil。直接修改字段,例如 data.Coins += 10,下一次保存就会包含它。 |
PlayerData.Loaded | 玩家的数据准备好时带上这个玩家触发,加载失败后也会触发。只传递玩家,因为通过 BindableEvent 发送的表到达时是一份副本。 |
PlayerData.CanSave(player) | 加载失败时为 false。任何出售之前都要检查:无法保存的购买会在玩家离开时消失。 |
PlayerData.SaveNow(player) | 立即保存,成功时返回 true。会让出执行。 |
模块是保存的数据唯一存在的地方,leaderstats 只是用来显示:按 排行榜教程 搭建它,在 Loaded 处理函数中用 PlayerData.Get(player) 填充,值变化时两边都更新。永远不要从 leaderstats 读回保存的值,也永远不要让第二个脚本保存同一个键。
在玩家进入之后才引用模块的脚本,会错过这些玩家的 Loaded。先连接处理函数,然后再遍历 Players:GetPlayers(),处理所有 PlayerData.Get(player) 已经返回表的玩家。
要替换旧的保存脚本,例如排行榜教程中的那个?它的值留在它自己的存储和键中,所以这个模块会让所有人从默认值开始。上线前,要么把 STORE_NAME 和前缀 User_ 指向旧的(migrate 会把没有 SchemaVersion 的数据当作版本 1 并补上缺少的字段),要么迁移旧值,然后删掉旧脚本。
客户端永远不会直接修改这些数据。商店按钮触发一个 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中删掉测试代码。
玩家数据为什么会丢失
下面是保存系统丢失进度的常见方式。模块在代码中解决了前四条和关于结构的那一条;其余的取决于你保存什么以及怎么保存,最后一条则需要会话锁。
| 发生了什么 | 结果 | 如何预防 |
|---|---|---|
| 加载失败,但脚本照样保存 | 默认值覆盖真实进度:数据被彻底抹掉 | 永远不要保存加载失败的玩家 |
只在 PlayerRemoving 中保存 | 服务器崩溃或关闭时漏掉保存 | 自动保存,再加上等待自己的保存完成的 BindToClose |
没有 pcall 或没有重试 | 一次失败的请求就会让脚本停止或丢失一次保存 | pcall 加上几次时间错开的重试 |
| 每次改动都保存 | 请求排起队;队列满 30 个时新的请求会被丢弃 | 把数据放在内存中并定时保存 |
| 保存存储无法保存的东西 | 保存时报错,或者取回的值为 nil | 保存数字、字符串、布尔值以及由它们组成的表 |
| 改变数据结构却不做迁移 | 旧存档被加载进错误的字段 | 结构版本和迁移步骤 |
| 两个脚本保存同一个键 | 每次保存都覆盖另一个脚本的字段 | 一个键只归一个模块管理 |
| 两台服务器持有同一个玩家 | 持有旧数据的服务器最后保存,覆盖了新的进度 | 会话锁 |
会话锁、“lock lost”和 ProfileStore
玩家同一时间只连接一台服务器,但当他进入新服务器时,旧服务器的最后一次保存可能还在进行:缓慢的重试、传送或快速重进。如果新服务器先加载数据,它拿到的就是旧数据,而最后保存的那台服务器会获胜。Roblox 文档指出,在有交易的游戏中,这个时间窗口是物品复制的常见原因。
会话锁 关闭了这个窗口。服务器加载玩家的键时,会在同一次 UpdateAsync 调用中把自己的锁 ID 写进键的元数据。任何其他服务器发现一个未过期、且不是自己设置的锁时,都不会加载或保存这个键。持有者在每次自动保存时刷新锁,并在最后一次保存时释放它;如果它不再刷新,锁就会过期,其他服务器可以接手。
“lock lost”是什么意思
在使用会话锁的系统中,当玩家的键现在归另一台服务器所有时(因为锁过期或被抢走),这台服务器就失去了锁。它的副本可能已经过时,所以它必须停止保存这个玩家;常见的处理方式是:带消息把他踢出,让他重新连接。如果你作为玩家看到了“lock lost”,那是那个游戏自己的保存系统发出的消息,只有它的开发者能解释。
你需要它吗?
本教程的模块不使用会话锁。没有锁时,真实的最坏情况是:在罕见的竞争中,玩家会丢失他在旧服务器上最后一次成功保存之后获得的东西。当复制或丢失会让玩家损失真正有价值的东西时再加上锁:交易、developer products、稀有物品或频繁传送。
| 方案 | 是什么 | 需要知道的 |
|---|---|---|
| 本教程的模块 | 加载、内存缓存、重试、自动保存、关闭时保存和结构版本,没有锁 | 足够短,可以完整读懂并修改 |
| 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 权限。请在玩家不在线时操作,否则持有他会话的服务器会把自己的副本保存到回滚之上。在服务端脚本中,ListVersionsAsync 和 GetVersionAsync 可以找到并读取旧版本,然后你再把它作为当前值写回去。
在发布会改变数据保存方式的更新之前,Roblox 建议通过 Open Cloud Snapshot Data Stores API 做一次快照(每个游戏每天一次)。没有快照的话,3:30 UTC 的一次错误保存会覆盖从 3:00 起写入这个键的所有内容,因为它落在同一个小时版本中。
常见错误与解决办法
数据存储错误会出现在 Studio 的 Output 窗口中,模块在每次尝试失败时都会输出带有 Roblox 错误文本的警告。脚本错误教程 解释了 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 中修改的,而那永远不会到达服务器,或者另一个脚本在保存同一个键。
每次重新进入数据都被重置
键在两次会话之间变了(用 player.Name 组成,或者你改了 STORE_NAME),加载失败而你看到的是默认值,或者没有任何脚本引用这个模块,所以它根本没有运行。检查 Output,并确认 Main 引用了 PlayerData。
用 RoCode 构建
如果不想手动搭建这些,RoCode 可以直接在你打开的场景里完成。它是独立的 AI 代理,并非 Roblox 出品,通过 Roblox Studio 插件工作:它编写像任何脚本一样使用 DataStoreService 的 Luau,并在你的 Explorer 中创建脚本。它自己从不访问你的数据存储,但使用插件 3.9 及以上时,它可以点击 Play 进行简短的试玩测试,你的脚本会像在任何测试中一样运行。
给我的游戏加上保存功能:在 PlayerData 模块中保存 Coins、Level 和 Inventory,带自动保存和服务器关闭时保存,并在我已有的 leaderstats 中显示 Coins。
- 可以用 Search Scripts 和 Read Script 查找已有的 leaderstats 和 DataStore 代码,以便扩展你已有的东西,而不是再加第二个保存脚本。在大型场景中,请在消息里写明脚本或文件夹的名字。
- 用 Create Script 创建 ModuleScript 和引用它的 Script,或者用 Edit 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 会自动保存玩家数据吗?
不会。除非服务端脚本通过 DataStoreService 保存,否则玩家的任何东西在会话结束后都不会保留,leaderstats 也一样。
选 ProfileStore 还是直接用 DataStoreService?
ProfileStore 同样建立在数据存储之上,所以问题在于你是否希望别人替你编写和维护会话锁。对于交易、付费物品或频繁传送,锁是值得的,可以来自这个库或 Roblox 的参考示例。对于小一些的游戏,像这样的模块更容易阅读和修改。
怎么重置或删除玩家的数据?
在 Data Stores Manager 中找到键并选择 Mark for Deletion,这在等待期内可以撤销;或者在服务端脚本中对这个键调用 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 秒
代码如何验证:本页的所有脚本都已用 Roblox API 类型定义(luau-lsp,2026年11月20日)通过 Luau strict 类型检查。类型检查能发现 API 名称写错和类型不匹配,但发现不了游戏逻辑上的错误。发布前请务必在 Studio 中测试。