Коротко
Використовуйте 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 перед публікацією.