Накратко
Използвай DataStoreService от сървърен Script: зареждай данните на играча с 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 се изпълнява само когато някой скрипт го зареди (require). Вмъкни в ServerScriptService Script с името
Mainи този ред: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 е само показване: изгради го както в ръководството за класация, попълни го от PlayerData.Get(player) в обработчика на Loaded и обновявай и двете при промяна на стойност. Никога не чети запазените стойности обратно от 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.
- Дай си нещо за запазване. Под реда с require в
Mainдобави: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 към 30 септември 2026 г. 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 знака |
| Стойност в един ключ | 4 194 304 знака като JSON |
| Четене на един ключ от всички сървъри | 25 МБ на минута |
| Запис в един ключ от всички сървъри | 4 МБ на минута, всяка заявка се закръгля нагоре до следващия КБ |
| Чакащи заявки | 30 на опашка; над това заявките се провалят с грешки 301-306 |
| Хранилище за цялата игра | 500 МБ плюс 1 МБ за всеки потребител за цялото време |
Размера на данните на играча измервай с #HttpService:JSONEncode(data), а оставащия бюджет на жив сървър гледай с DataStoreService:GetRequestBudgetForRequestType(Enum.DataStoreRequestType.StandardWrite). Извикванията на GetAsync, на които е отговорил 4-секундният кеш, не се броят. Режимът Run в Studio има свои, вероятно по-ниски лимити, затова за проверка на лимитите на заявките 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, защото попада в същата часова версия.
Чести грешки и решения
Грешките на хранилищата за данни се появяват в прозореца Output на Studio, а модулът извежда предупреждение с текста на грешката от Roblox при всеки неуспешен опит. Ръководството за грешки в скриптовете обяснява как изобщо да четеш Output.
StudioAccessToApisNotAllowed (грешка 403)
„Can't write to DataStore from Studio because API access is not enabled.“ Публикувай плейса, после включи Enable Studio Access to API Services във File > Experience Settings > Security, в тестово копие.
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 може да го направи направо в плейса, който имаш отворен. Това е независим ИИ агент, не от Roblox, който работи чрез плъгин за Roblox Studio: пише Luau, който използва DataStoreService като всеки скрипт, и създава скриптове в твоя Explorer. Самият той никога не достъпва твоите хранилища за данни, но с плъгин 3.9 или по-нов може да натисне Play за кратък плейтест, в който скриптовете ти работят както във всеки тест.
Добави запазване в играта ми: пази Coins, Level и Inventory в модул PlayerData с автозапис и запазване при изключване на сървъра и показвай Coins в leaderstats, които вече имам.
- Може да потърси съществуващи leaderstats и код за DataStore чрез Search Scripts и Read Script, за да разшири това, което имаш, вместо да добавя втори скрипт за запазване. В голям плейс посочи скрипта или папката в съобщението.
- Създава ModuleScript и Script, който го зарежда, чрез Create Script или променя съществуващите чрез Edit Script
- Пуска Check Script за всеки написан скрипт: проверка на компилацията в Studio с кратък списък с предупреждения, а не проверка на типовете и не тестово пускане
- Изпраща промените на пакети, и всеки пакет е точка за отмяна (undo) в Studio
Studio Access to API Services в тестовото копие пак ще трябва да включиш сам: RoCode не може да променя тази настройка. С плъгин 3.9 или по-нов краткият му плейтест чете грешките, а с плъгин 3.9.11 или по-нов може да управлява тестов персонаж, за да провери дали играта работи, но проверява само това, което сам е решил да провери, затова изиграй я сам и се увери, че Coins, Level и Inventory се запазват и зареждат. Ако запазването не е минало в твоя тест, Check Output може да прочете редовете Server от плейтеста, който си пуснал. Запазването обикновено се добавя, когато основният игрови цикъл вече работи; създаване на игра в Roblox с ИИ по една система наведнъж показва този ред. Как RoCode се свързва със Studio.
Често задавани въпроси
Как да включа DataStore в Roblox Studio?
Публикувай плейса, отвори 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 секунди при изключване
Как е проверен кодът: всеки скрипт на тази страница минава строга проверка на типовете в Luau с дефинициите на Roblox API (luau-lsp, 20 ноември 2026 г.). Проверката на типовете хваща грешки в имената на API и грешни типове, но не и грешки в логиката на играта, затова тествай всичко в Studio, преди да публикуваш.