Урок · Данни на играча

Как да запазваш данните на играча в Roblox Studio с DataStore

Roblox не помни нищо за играча между сесиите, ако сървърен скрипт не го е запазил. В това ръководство ще изградиш модул PlayerData, който зарежда, държи в паметта и запазва данните на всеки играч чрез DataStoreService, а после ще разгледаш проверката, лимитите и начините, по които запазените данни се губят.

Обновено 20 ноември 2026 г.17 мин четенеАвтор:

Накратко

Използвай DataStoreService от сървърен Script: зареждай данните на играча с 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 се изпълнява само когато някой скрипт го зареди (require). Вмъкни в ServerScriptService Script с името Main и този ред: local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Другите сървърни скриптове го зареждат по същия начин.
  3. Промени DEFAULTS и типа Data според играта си, като всяко поле остава число, низ, булева стойност или таблица.
Explorer след стъпки 1-3
ServerScriptService
    PlayerData ModuleScript new
    Main Script new
StarterPlayer
    StarterPlayerScripts
        DataWarning LocalScript new
ModuleScript в ServerScriptService с име PlayerData
-- 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.

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. Дай си нещо за запазване. Под реда с 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)
  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.

Защо се губят данните на играчите

Ето обичайните начини, по които системата за запазване губи напредък. Модулът покрива в кода първите четири реда и реда за схемата; останалите зависят от това какво и как пазиш, а за последния трябва заключване на сесията.

Какво се случваРезултатКак да се предотврати
Зареждането не е успяло, а скриптът пак запазваСтойностите по подразбиране изтриват истинския напредък: пълно изтриванеНикога не запазвай играч, чието зареждане не е успяло
Запазване само в 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, четене в UpdateAsync60 + 40 × играчи60 + 40 × играчи
Запис: SetAsync, IncrementAsync, запис в UpdateAsync60 + 40 × играчи30 + 5 × играчи
Списък: ListKeysAsync или GetSortedAsync за подредени хранилища5 + 2 × играчи5 + 2 × играчи
Изтриване: RemoveAsync60 + 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, които вече имам.

RoCode прави
  • Може да потърси съществуващи 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 започва всички от нулата; никога не го прави в живата игра.

Източници и какво да прочетеш

Как е проверен кодът: всеки скрипт на тази страница минава строга проверка на типовете в Luau с дефинициите на Roblox API (luau-lsp, 20 ноември 2026 г.). Проверката на типовете хваща грешки в имената на API и грешни типове, но не и грешки в логиката на играта, затова тествай всичко в Studio, преди да публикуваш.

Пробвай RoCode в своята игра.

Безплатни кредити всеки ден, без карта. Инсталирай плъгина, опиши функцията и виж какво се е появило в Studio.