Poradnik · Dane gracza

Jak zapisywać dane gracza w Roblox Studio przez DataStore

Roblox nic nie pamięta o graczu między sesjami, jeśli skrypt serwerowy tego nie zapisał. W tym poradniku zbudujesz moduł PlayerData, który wczytuje, trzyma w pamięci i zapisuje dane każdego gracza przez DataStoreService, a potem omówisz sprawdzanie, limity i to, jak zapisane dane się gubią.

Zaktualizowano 20 listopada 202616 min czytaniaAutor:

W skrócie

Używaj DataStoreService z serwerowego Script: wczytuj dane gracza przez GetAsync, gdy wchodzi, trzymaj je w tabeli, gdy gra, i zapisuj przez UpdateAsync według timera, przy wyjściu (PlayerRemoving) i przy wyłączaniu serwera (game:BindToClose). Owijaj każde wywołanie w pcall i powtarzaj nieudane kilka razy.

  • Żeby testować w Studio, opublikuj grę i włącz File > Experience Settings > Security > Enable Studio Access to API Services w osobnej grze testowej: Studio używa tych samych danych co opublikowane serwery.
  • Jeśli dane gracza się nie wczytały, nigdy nie zapisuj tego gracza. Zapis wartości domyślnych nadpisze jego prawdziwy postęp.
  • Trzymaj jedną tabelę na gracza pod jednym kluczem, na przykład User_12345, i zapisuj według timera, a nie przy każdej zmianie.
  • Przy wymianie przedmiotów albo płatnych przedmiotach dodaj blokadę sesji, żeby dwa serwery nie mogły zapisywać jednego gracza.
Na tej stronie
  1. Dostęp Studio
  2. Jak działa DataStore
  3. GetAsync i UpdateAsync
  4. 1. Moduł PlayerData
  5. Jak zbudowany jest moduł
  6. 2. Praca z danymi
  7. 3. Ostrzeżenie
  8. 4. Sprawdzenie w Studio
  9. Dlaczego dane się gubią
  10. Blokada sesji
  11. Limity
  12. Wersje i kopie
  13. Common errors
  14. With RoCode
  15. Najczęstsze pytania
  16. Źródła i dalsza lektura

Na początek: włącz dostęp Studio w kopii testowej

Gra uruchomiona w Studio nie może korzystać z magazynów danych, dopóki na to nie pozwolisz. Pozwolenie ma haczyk, przed którym ostrzega dokumentacja Roblox: Studio wtedy czyta i zapisuje te same magazyny danych co opublikowana gra, więc test, który zeruje twoje monety w Studio, zeruje je też w opublikowanej grze, a błąd w kodzie testowym może zepsuć klucze prawdziwych graczy.

  1. Zrób kopię testową. Zapisz grę do pliku, otwórz kopię, wybierz File > Publish to Roblox As i kliknij Create new game. Nie dodawaj jej jako place w opublikowanej grze: wszystkie place jednej gry dzielą te same magazyny danych.
  2. W kopii testowej otwórz File > Experience Settings i przejdź do Security.
  3. Włącz Enable Studio Access to API Services i kliknij Save.

Wywołania magazynów danych działają tylko w serwerowych Script; LocalScript, który spróbuje, dostanie błąd, więc klienci nie mogą zapisywać zapisanych danych. Gdy przycisk ma je zmieniać, klient prosi serwer przez RemoteEvent, a decyduje serwer (zobacz poradnik o RemoteEvents).

Jak magazyny danych przechowują dane graczy

IlustracjaSprawdzenie z kroku 4 poradnika w przyspieszeniu: Play, Stop zapisuje sesję w magazynie danych, ponowne Play ją wczytuje, więc Output pokazuje 200.

Magazyn danych (data store) to nazwany zestaw kluczy i wartości na serwerach Roblox, wspólny dla wszystkich serwerów i wszystkich place twojej gry. DataStoreService:GetDataStore("PlayerData") zwraca jeden taki magazyn.

Zalecenia Roblox sprowadzają się do zasady jeden magazyn na dane graczy, jeden klucz na gracza, jedna tabela w każdym kluczu. Składaj klucz z UserId gracza, na przykład User_12345, a nigdy z nazwy, którą może zmienić. Stały wzorzec User_{UserId} pozwala też automatycznej obsłudze prawa do bycia zapomnianym od Roblox znaleźć dane gracza, jeśli ją skonfigurujesz.

Co można zapisać w magazynie danych
TypZapisuje się?Uwagi
Liczby, stringi, wartości logiczne, buforyTakStringi muszą być poprawnym UTF-8. Nie przechowuj inf ani nan.
TabeleTakJeśli wszystko w środku też da się zapisać. Tabela, której klucze liczbowe nie zaczynają się od 1 (więc jej długość to 0), wraca z tymi kluczami jako stringami.
Instance, Vector3, CFrame, Color3NieZapis daje błąd albo zapisuje nil. Zapisuj nazwę przedmiotu albo pozycję jako trzy liczby.

Każde zapytanie to wywołanie sieciowe, które może się nie udać, zajmuje czas i zużywa budżet na minutę. Dlatego niezawodne systemy zapisu czytają dane raz przy wejściu gracza, trzymają je w tabeli na serwerze, gdy gra, i od czasu do czasu zapisują z powrotem.

GetAsync, SetAsync czy UpdateAsync: co wybrać

Główne metody magazynu danych
MetodaCo robiDo czego
GetAsync(key)Czyta wartość. Wynik jest cache’owany na tym serwerze przez 4 sekundy.Wczytywanie danych gracza
SetAsync(key, value)Nadpisuje wartość, nie czytając jej. Jeden zapis.Nowy klucz albo wartość, która nie zależy od starej
UpdateAsync(key, callback)Czyta najnowszą wartość, przekazuje ją twojej funkcji i zapisuje to, co ona zwróci. Jeden odczyt i jeden zapis.Zapis danych gracza i każdy klucz, który może zapisywać kilka serwerów
IncrementAsync(key, delta)Dodaje liczbę całkowitą do zapisanej liczby całkowitej.Liczniki
RemoveAsync(key)Usuwa klucz i zwraca starą wartość. Wcześniejsze wersje nadal można wylistować i przeczytać.Usuwanie danych gracza

SetAsync zapisuje na ślepo: jeśli dwa serwery zapisują jeden klucz prawie w tej samej chwili, wygrywa ostatni zapis, cokolwiek w nim jest. UpdateAsync najpierw czyta bieżącą wartość, a jeśli w międzyczasie zapisze inny serwer, Roblox ponownie uruchamia twoją funkcję z nową wartością. Roblox zaleca go zawsze, gdy zapis zależy od bieżącej wartości albo klucz może zapisywać kilka serwerów, a to właśnie dane gracza. Funkcja ma trzy zasady:

  • Nie może oddawać wykonania (yield): żadnych task.wait() ani innych wywołań magazynów w środku.
  • Może wykonać się więcej niż raz, więc ma tylko liczyć nową wartość i nigdy nie wydawać przedmiotów ani nie odpalać eventów.
  • Zwrócenie nil anuluje zapis. Moduł używa tego, żeby nie nadpisać danych zapisanych przez nowszą wersję gry.

Krok 1: utwórz moduł PlayerData

Ten ModuleScript to jedyny kod, który rozmawia z magazynem danych. Wczytuje dane gracza przy wejściu, trzyma je w pamięci, zapisuje co 180 sekund, przy wyjściu i przy wyłączaniu serwera i odmawia zapisu tych, których dane się nie wczytały.

  1. W Explorerze najedź kursorem na ServerScriptService, kliknij + i wstaw ModuleScript. Zmień jego nazwę na PlayerData i zastąp zawartość kodem poniżej.
  2. ModuleScript wykonuje się tylko wtedy, gdy podłącza go (require) jakiś skrypt. Wstaw do ServerScriptService Script o nazwie Main z taką linią: local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Inne serwerowe skrypty podłączają go tak samo.
  3. Zmień DEFAULTS i typ Data pod swoją grę, zostawiając każde pole liczbą, stringiem, wartością logiczną albo tabelą.
Explorer po krokach 1-3
ServerScriptService
    PlayerData ModuleScript new
    Main Script new
StarterPlayer
    StarterPlayerScripts
        DataWarning LocalScript new
ModuleScript w ServerScriptService o nazwie PlayerData
-- PlayerData: wczytuje dane gracza przy wejściu, trzyma je w pamięci
-- i zapisuje według timera, przy wyjściu i przy wyłączaniu serwera.
-- Inne serwerowe skrypty czytają i zmieniają je przez 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 -- podnoś, gdy zmienia się kształt danych, i dodawaj krok w migrate()
local AUTOSAVE_SECONDS = 180
-- W Studio nieudane wywołanie od razu odpuszcza, więc test bez dostępu do magazynu idzie szybko
local MAX_ATTEMPTS = if RunService:IsStudio() then 1 else 4
local FIRST_RETRY_SECONDS = 1 -- podwaja się po każdej porażce: 1, 2, 4

export type Data = {
	SchemaVersion: number,
	Coins: number,
	Level: number,
	Inventory: { string },
}

-- Z czym zaczyna zupełnie nowy gracz
local DEFAULTS: { [string]: any } = {
	Coins = 0,
	Level = 1,
	Inventory = {},
}

type Session = {
	key: string,
	userId: number,
	data: Data,
	canSave: boolean, -- false, jeśli wczytanie się nie udało: dane domyślne nie mogą zastąpić prawdziwego postępu
}

-- Wywoływane w każdym pcall niżej, więc jeszcze nieopublikowana gra
-- (bez dostępu do magazynu) i tak wczytuje graczy z danymi domyślnymi
local function store(): DataStore
	return DataStoreService:GetDataStore(STORE_NAME)
end
local sessions: { [Player]: Session } = {}
local pendingSaves: { [string]: number } = {} -- zapisy, które jeszcze trwają, według kluczy
local loadedEvent = Instance.new("BindableEvent")

local PlayerData = {}

-- Odpala się z graczem, gdy jego dane są gotowe. Tabelę bierz przez PlayerData.Get(player):
-- tabela wysłana przez BindableEvent przychodzi jako kopia i jej zmiana niczego nie zmieni.
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) -- świeża kopia, żeby gracze nigdy nie dzielili jednej tabeli Inventory
	data.SchemaVersion = SCHEMA_VERSION
	return data
end

-- Doprowadza zapisane dane do bieżącego schematu. Zwraca nil, jeśli nie da się ich bezpiecznie użyć.
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 -- zapisane przez nowszą wersję gry: tutaj nie wczytywać i nie nadpisywać
	end

	-- Po jednym kroku na zmianę schematu, od starszych do nowszych
	if version < 2 then
		-- Przykład: w wersji 1 waluta nazywała się Gold. Kopiujemy ją tylko wtedy, gdy nie ma Coins,
		-- żeby stare dane, gdzie Coins już jest, ale nie ma SchemaVersion, zachowały wartość.
		if saved.Coins == nil then
			saved.Coins = saved.Gold
		end
		saved.Gold = nil
	end

	-- Dodajemy pola, które pojawiły się po ostatnim zapisie gracza, i zastępujemy wartości złego typu
	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

-- Wykonuje wywołanie magazynu w pcall. Przy porażce czeka i próbuje znowu, za każdym razem podwajając
-- czekanie i dodając trochę losowości, żeby serwery nie ponawiały wszystkie naraz.
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 -- zwrócenie nil anuluje zapis
			end
			-- Zapisujemy całą bieżącą tabelę z oznaczeniem UserId gracza
			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()
		-- Zaczynamy w losowym momencie interwału, żeby serwery nie zapisywały wszystkie naraz
		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

	-- Jeśli gracz dopiero co wyszedł z tego serwera i wrócił, najpierw pozwalamy skończyć się ostatniemu zapisowi
	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 -- wyszedł w trakcie wczytywania: nic się nie zmieniło, nie ma czego zapisywać
	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 może to przeczytać i ostrzec gracza
	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 -- zatrzymuje pętlę autozapisu, a ponowne wywołanie nic nie robi
	save(session)
end

-- Żywa tabela danych gracza albo nil, dopóki się nie wczytała. Zmieniaj ją tylko z serwerowych skryptów.
function PlayerData.Get(player: Player): Data?
	local session = sessions[player]
	return if session then session.data else nil
end

-- True, gdy dane gracza się wczytały i będą zapisane. Sprawdzaj przed każdą sprzedażą.
function PlayerData.CanSave(player: Player): boolean
	local session = sessions[player]
	return session ~= nil and session.canSave
end

-- Zapisuje teraz, nie czekając na timer, w ważnych momentach w rodzaju zakupu.
-- Oddaje wykonanie i zwraca true, gdy zapis się udał.
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) -- gracze, którzy weszli przed pierwszym podłączeniem tego modułu
end

game:BindToClose(function()
	-- Serwer daje tym funkcjom 30 sekund, więc zapisujemy wszystkich jednocześnie
	for player in sessions do
		task.spawn(endSession, player)
	end
	-- Potem czekamy na wszystkie jeszcze trwające zapisy, łącznie z tymi zaczętymi w PlayerRemoving
	while next(pendingSaves) do
		task.wait()
	end
end)

return PlayerData

Gdy gra już wyszła, nie zmieniaj STORE_NAME ani wzorca klucza User_. Zmiana któregokolwiek skieruje moduł na puste klucze i każdy gracz zacznie od nowa od wartości domyślnych.

Jak moduł chroni dane

Wartości domyślne i wersja schematu

Nowy gracz dostaje świeżą kopię DEFAULTS. Musi to być właśnie kopia: gdyby wszyscy gracze dzielili jedną tabelę Inventory, przedmiot dodany jednemu pojawiłby się u wszystkich.

Każda zapisana tabela niesie SchemaVersion. Dodanie pola nie wymaga nowej wersji, bo migrate uzupełnia brakujące pola z wartości domyślnych. Zmiana nazwy albo przebudowa wymaga: podnieś SCHEMA_VERSION i dodaj krok, jak w przykładzie, który zmienia nazwę Gold na Coins (w nowej grze usuń go i zacznij od 1). Dane z wersją wyższą niż na serwerze pochodzą z nowszego wydania, które jeszcze się rozchodzi, więc starsze serwery ich nie ruszają.

Nieudane wczytanie nigdy się nie zapisuje

Ta zasada chroni przed całkowitym wymazaniem. Jeśli wszystkie próby wczytania się nie udały, gracz gra na danych domyślnych, ale canSave jest false, więc te wartości nigdy nie nadpiszą jego prawdziwego postępu. Moduł ustawia też atrybut DataLoaded na false, a krok 3 używa go, żeby powiadomić gracza. Wzorcowy przykład Roblox obsługuje nieudane wczytania tak samo i proponuje to zamiast wyrzucania; jeśli wolisz wyrzucać, wywołaj player:Kick() z komunikatem tam, gdzie moduł wypisuje ostrzeżenie.

Ponowienia z rosnącą przerwą

withRetries owija każde wywołanie w pcall. Po porażce czeka 1, potem 2, potem 4 sekundy, za każdym razem plus losowo do połowy tego czasu, i zatrzymuje się po czterech próbach (w Studio po jednej, żeby gra bez dostępu do magazynu startowała od razu). Losowość rozkłada ponowienia wielu serwerów po awarii, a ograniczenie trzyma czekanie w granicach około 10 sekund, w obrębie 30 sekund, które serwer dostaje na wyłączenie. Ponieważ każdy zapis zapisuje całą żywą tabelę przez UpdateAsync, ponowienie, które zakończyło się z opóźnieniem, nie może przywrócić starych danych.

Kiedy moduł zapisuje

KiedyPo co
Co 180 sekund, gdy gracz jest na serwerzeOgranicza straty przy awarii. Pierwszy zapis wypada w losowym momencie interwału, żeby serwery nie zapisywały wszystkie naraz. Wzorcowy przykład Roblox też używa 180 sekund.
Gdy gracz wychodzi (PlayerRemoving)Zwykły końcowy zapis. Sesja jest najpierw usuwana, więc autozapis się zatrzymuje.
Gdy serwer się wyłącza (game:BindToClose)Wszyscy, którzy są jeszcze na serwerze, zapisują się naraz, a funkcja czeka na każdy trwający zapis. Roblox daje jej 30 sekund.
Na żądanie, przez PlayerData.SaveNow(player)Po czymś, czego nie wolno stracić, na przykład zakupie.

Jeśli gracz znowu wchodzi na ten sam serwer, gdy jego końcowy zapis jeszcze trwa, nowe wczytanie czeka na koniec tego zapisu, więc nie może przeczytać starej wartości.

Krok 2: czytaj i zmieniaj dane z innych skryptów

Wszystkie serwerowe skrypty, które podłączają moduł, pracują z tymi samymi tabelami:

WywołanieCo robi
PlayerData.Get(player)Żywa tabela danych gracza albo nil, dopóki się nie wczytała. Zmieniaj pola bezpośrednio, na przykład data.Coins += 10, a następny zapis to złapie.
PlayerData.LoadedOdpala się z graczem, gdy jego dane są gotowe, także po nieudanym wczytaniu. Przekazuje tylko gracza, bo tabela wysłana przez BindableEvent przychodzi jako kopia.
PlayerData.CanSave(player)false, jeśli wczytanie się nie udało. Sprawdzaj przed każdą sprzedażą: zakup, którego nie da się zapisać, zniknie, gdy gracz wyjdzie.
PlayerData.SaveNow(player)Zapisuje od razu i zwraca true, jeśli się udało. Oddaje wykonanie.

Moduł to jedyne miejsce, gdzie żyją zapisane dane, a leaderstats to tylko wyświetlanie: zbuduj go jak w poradniku o leaderboardzie, wypełnij z PlayerData.Get(player) w handlerze Loaded i aktualizuj oba przy zmianie wartości. Nigdy nie czytaj zapisanych wartości z powrotem z leaderstats i nigdy nie pozwalaj drugiemu skryptowi zapisywać tego samego klucza.

Skrypt, który podłączył moduł po tym, jak gracze weszli, przegapia dla nich Loaded. Podłącz handler, a potem jeszcze przejdź pętlą po Players:GetPlayers() i obsłuż wszystkich, dla których PlayerData.Get(player) już zwraca tabelę.

Zastępujesz stary skrypt zapisu, na przykład z poradnika o leaderboardzie? Jego wartości zostają w jego własnym magazynie i kluczu, więc ten moduł zacznie wszystkich od wartości domyślnych. Przed startem albo skieruj STORE_NAME i prefiks User_ na stare (migrate traktuje dane bez SchemaVersion jako wersję 1 i uzupełnia brakujące pola), albo przenieś stare wartości, a potem usuń stary skrypt.

Klienci nigdy nie zmieniają tych danych bezpośrednio. Przycisk sklepu odpala RemoteEvent; serwer sprawdza CanSave, porównuje cenę z Coins gracza, zmienia tabelę i wywołuje SaveNow. Poradnik o GUI sklepu buduje taki zakup po stronie serwera.

Gotowy przykład dodawania pól jest w poradniku o symulatorze klikania: dodaje PowerLevel i Rebirths do DEFAULTS i typu Data, a potem zmienia je w tabeli, którą zwraca PlayerData.Get. migrate daje nowe pola graczom ze starymi zapisami.

Krok 3: powiadom gracza, że jego dane się nie wczytały

Gracz, którego dane się nie wczytały, powinien wiedzieć, że ta sesja się nie zapisze, żeby wszedł ponownie, a nie grał na marne. Ten LocalScript obserwuje atrybut DataLoaded i pokazuje baner, gdy jest równy false.

LocalScript w StarterPlayerScripts o nazwie 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

-- Serwer ustawia DataLoaded raz, po próbie wczytania danych tego gracza
player:GetAttributeChangedSignal("DataLoaded"):Connect(showWarning)
showWarning()

Krok 4: sprawdź zapis w Studio

Rób to w kopii testowej z włączonym dostępem Studio.

  1. Daj sobie coś do zapisania. Pod linią require w Main dodaj: PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end)
  2. Kliknij Play. Okno Output (w menu Window albo na karcie Script) pokaże twoją nazwę i 100 (przy pierwszym uruchomieniu), bez ostrzeżenia Could not load.
  3. Kliknij Stop. Zakończenie testu zamyka serwer, a moduł zapisuje cię przed zamknięciem.
  4. Znowu kliknij Play. Output powinien pokazać 200, o 100 więcej niż poprzednio. Jeśli znowu pokazuje tę samą liczbę, zapis się nie udał: przeczytaj ostrzeżenia nad nią.
  5. Sprawdź ścieżkę z błędem. Wyłącz dostęp Studio i kliknij Play. Po kilku sekundach ponowień Output pokaże Could not load User_... i 100, a pojawi się baner z kroku 3. Zatrzymaj test, znowu włącz dostęp i kliknij Play: Output pokaże 300, twoje zapisane 200 plus 100, bo nieudana sesja nigdy nie nadpisała twoich danych.
  6. Usuń linię testową z Main.

Dlaczego dane graczy się gubią

Oto zwykłe sposoby, w jakie system zapisu gubi postęp. Moduł zamyka w kodzie pierwsze cztery wiersze i wiersz o schemacie; pozostałe zależą od tego, co i jak przechowujesz, a ostatni wymaga blokady sesji.

Co się dziejeWynikJak zapobiec
Wczytanie się nie udało, a skrypt i tak zapisujeWartości domyślne nadpisują prawdziwy postęp: całkowite wymazanieNigdy nie zapisywać gracza, którego wczytanie się nie udało
Zapis tylko w PlayerRemovingAwaria albo wyłączenie serwera pomija zapisAutozapis plus BindToClose, który czeka na swoje zapisy
Brak pcall albo brak ponowieniaJedno nieudane zapytanie zatrzymuje skrypt albo gubi zapispcall z kilkoma rozłożonymi w czasie ponowieniami
Zapis przy każdej zmianieZapytania ustawiają się w kolejce; gdy jest ich 30, nowe są odrzucaneTrzymać dane w pamięci i zapisywać według timera
Zapis tego, czego magazyn nie umie przechowaćZapis daje błąd albo wartość wraca jako nilZapisywać liczby, stringi, wartości logiczne i tabele z nich
Zmiana kształtu danych bez migracjiStare zapisy wczytują się w złe polaWersja schematu i krok migracji
Dwa skrypty zapisują jeden kluczKażdy zapis nadpisuje pola drugiegoKluczem zarządza jeden moduł
Dwa serwery trzymają jednego graczaSerwer ze starymi danymi zapisuje ostatni i nadpisuje nowy postępBlokada sesji

Blokada sesji, „lock lost” i ProfileStore

Gracz jest podłączony do jednego serwera naraz, ale końcowy zapis starego serwera może jeszcze trwać, gdy wchodzi na nowy: powolne ponowienie, teleport albo szybkie ponowne wejście. Jeśli nowy serwer wczyta dane pierwszy, będzie miał stare dane, a wygra ten serwer, który zapisze ostatni. Dokumentacja Roblox zaznacza, że w grach z wymianą ta luka to częsta przyczyna duplikowania przedmiotów.

Blokada sesji zamyka tę lukę. Gdy serwer wczytuje klucz gracza, w tym samym wywołaniu UpdateAsync zapisuje swój ID blokady w metadanych klucza. Każdy inny serwer, który znalazł niewygasłą blokadę, której nie stawiał on, nie będzie wczytywał ani zapisywał tego klucza. Właściciel odnawia blokadę przy każdym autozapisie i zdejmuje ją w końcowym zapisie; jeśli przestaje ją odnawiać, blokada wygasa i może ją przejąć inny serwer.

Co znaczy „lock lost”

W systemie z blokadą sesji serwer stracił blokadę, gdy kluczem gracza zarządza teraz inny serwer, bo blokada wygasła albo została przejęta. Jego kopia może być nieaktualna, więc musi przestać zapisywać tego gracza; zwykła reakcja to wyrzucić go z komunikatem, żeby połączył się ponownie. Jeśli widzisz „lock lost” jako gracz, to komunikat własnego systemu zapisu tej gry i wyjaśnić go mogą tylko jej twórcy.

Czy jej potrzebujesz?

Moduł z tego poradnika nie blokuje sesji. Bez blokady realny najgorszy przypadek jest taki: w rzadkim wyścigu gracz traci to, co zarobił na starym serwerze po jego ostatnim udanym zapisie. Dodawaj blokadę, gdy duplikowanie albo utrata kosztuje graczy coś prawdziwego: wymiana, developer products, rzadkie przedmioty albo częste teleporty.

OpcjaCo to jestCo warto wiedzieć
Moduł z tego poradnikaWczytywanie, cache w pamięci, ponowienia, autozapis, zapis przy wyłączeniu i wersje schematu, bez blokadyWystarczająco krótki, żeby przeczytać go w całości i zmienić
Przykład Roblox dla danych graczy i zakupówWzorcowy kod od Roblox z blokadą sesji, ponowieniami po kolei dla każdego klucza i obsługą paragonów zakupówRoblox mówi, że nie jest sprawdzony w boju w popularnej grze i nie powinien być używany bez zmian bez obszernych testów
ProfileStoreDarmowy moduł społeczności z otwartym kodem, następca ProfileService, zbudowany wokół blokady sesji i autozapisuNie od Roblox. Przeniesienie na niego istniejącej gry wymaga migracji już zapisanych danych

Przy każdym zewnętrznym module Roblox radzi sprawdzić, kto nim zarządza, czy jest utrzymywany i jak dostaniesz się do swoich danych bez niego. Ta sama dokumentacja nazywa DataStore2 przestarzałą biblioteką, której nowe gry nie powinny używać.

Limity magazynów danych

To limity z dokumentacji Roblox na 30 września 2026 roku. Roblox je zmienia, więc sprawdź stronę kodów błędów i limitów (po angielsku), zanim oprzesz się na dokładnej liczbie.

Domyślne limity zapytań dla każdego serwera, na minutę
Typ zapytaniaZwykłe magazynyUporządkowane magazyny
Odczyt: GetAsync, odczyt w UpdateAsync60 + 40 × graczy60 + 40 × graczy
Zapis: SetAsync, IncrementAsync, zapis w UpdateAsync60 + 40 × graczy30 + 5 × graczy
Lista: ListKeysAsync albo GetSortedAsync dla uporządkowanych magazynów5 + 2 × graczy5 + 2 × graczy
Usuwanie: RemoveAsync60 + 40 × graczy30 + 5 × graczy

Przy 20 graczach serwer może robić 860 zwykłych zapisów na minutę; autozapis tego modułu zużywa około 7 z nich, plus jeden na każdego gracza, który wyszedł. Budżet wyczerpuje zapis przy każdej podniesionej monecie. Drugi budżet obowiązuje dla całej gry i jest dzielony z Open Cloud: 300 odczytów na minutę plus 40 na każdego gracza online i 300 zapisów plus 20 na gracza.

Limity rozmiaru i przepustowości
LimitWartość
Nazwa magazynu, nazwa klucza, scopePo 50 znaków
Wartość w jednym kluczu4 194 304 znaki w postaci JSON
Odczyt jednego klucza ze wszystkich serwerów25 MB na minutę
Zapis do jednego klucza ze wszystkich serwerów4 MB na minutę, każde zapytanie jest zaokrąglane w górę do następnego KB
Oczekujące zapytania30 na kolejkę; ponad to zapytania wywalają się z błędami 301-306
Miejsce na całą grę500 MB plus 1 MB na każdego użytkownika od początku

Rozmiar danych gracza mierz przez #HttpService:JSONEncode(data), a pozostały budżet działającego serwera sprawdzaj przez DataStoreService:GetRequestBudgetForRequestType(Enum.DataStoreRequestType.StandardWrite). Wywołania GetAsync, na które odpowiedział 4-sekundowy cache, się nie liczą. Tryb Run w Studio ma własne, być może niższe limity, więc do sprawdzania limitów zapytań Roblox radzi Team Create.

Wersje i kopie zapasowe

Zwykłe magazyny danych przechowują historię za ciebie. Pierwszy zapis do klucza w każdej godzinie UTC jest zachowywany jako wersja, a kolejne zapisy w tej godzinie nadpisują się nawzajem. Stara wersja wygasa 30 dni po tym, jak zastąpił ją nowszy zapis; najnowsza nie wygasa nigdy. Uporządkowane magazyny nie przechowują wersji.

Żeby cofnąć jednego gracza, otwórz Data Stores Manager (Creations, twoja gra, Configure > Data Stores Manager), wybierz jego klucz, wybierz wcześniejszą wersję i kliknij Revert; potrzebne jest do tego uprawnienie Edit. Rób to, gdy gracz jest offline, inaczej serwer z jego sesją zapisze swoją kopię na cofnięcie. Z serwerowego skryptu ListVersionsAsync i GetVersionAsync znajdują i czytają starą wersję, którą potem zapisujesz z powrotem jako bieżącą wartość.

Przed opublikowaniem aktualizacji, która zmienia sposób zapisu danych, Roblox radzi zrobić migawkę przez Open Cloud Snapshot Data Stores API (jedna dziennie na grę). Bez niej błędny zapis o 3:30 UTC nadpisze wszystko, co zostało zapisane w tym kluczu od 3:00, bo trafia do tej samej godzinowej wersji.

Częste błędy i rozwiązania

Błędy magazynów danych pojawiają się w oknie Output Studio, a moduł wypisuje ostrzeżenie z tekstem błędu Roblox przy każdej nieudanej próbie. Poradnik o błędach skryptów wyjaśnia, jak w ogóle czytać Output.

StudioAccessToApisNotAllowed (błąd 403)

„Can't write to DataStore from Studio because API access is not enabled.” Opublikuj grę, potem włącz Enable Studio Access to API Services w File > Experience Settings > Security, w kopii testowej.

DataStore request was added to queue

Serwer wysyła zapytania szybciej, niż pozwala budżet, albo za często zapisuje jeden klucz, zwykle przez zapis przy każdej zmianie albo w pętli. Gdy w kolejce jest 30 zapytań, nowe wywalają się z błędami 301-306. Trzymaj dane w pamięci i zapisuj według timera.

CantStoreValue (błąd 104) albo pole wraca jako nil

W tabeli jest coś, czego magazyn nie umie zapisać, na przykład Instance, Vector3 albo Color3. Zapisuj zamiast tego nazwę, ID albo proste liczby i odtwarzaj obiekt przy wczytywaniu.

ValueTooLarge (błąd 105)

Jeden klucz przechowuje więcej niż 4 194 304 znaki JSON. Zmierz przez #HttpService:JSONEncode(data), usuń to, co da się odtworzyć, albo podziel dane na kilka stałych kluczy.

Nie ma błędów, ale dane się nie zapisują

Poszukaj ostrzeżenia modułu Could not load: po nieudanym wczytaniu celowo odmawia zapisu. W przeciwnym razie wartość najpewniej zmieniano w LocalScript, a to nigdy nie dociera do serwera, albo ten sam klucz zapisuje inny skrypt.

Dane resetują się przy każdym ponownym wejściu

Klucz zmienia się między sesjami (złożony z player.Name albo zmieniłeś STORE_NAME), wczytanie się nie udaje i widzisz wartości domyślne, albo nikt nie podłącza modułu i w ogóle nie działa. Sprawdź Output i czy Main podłącza PlayerData.

Zbuduj to z RoCode

Jeśli nie chce ci się składać tego ręcznie, RoCode może to zrobić prosto w grze, którą masz otwartą. To niezależny agent AI, nie od Roblox, który działa przez plugin do Roblox Studio: pisze Luau, który używa DataStoreService jak każdy skrypt, i tworzy skrypty w twoim Explorerze. Sam nigdy nie korzysta z twoich magazynów danych, ale z pluginem 3.9 lub nowszym może kliknąć Play na krótki playtest, w którym twoje skrypty działają jak w każdym teście.

Ty piszesz

Dodaj zapis do mojej gry: trzymaj Coins, Level i Inventory w module PlayerData z autozapisem i zapisem przy wyłączaniu serwera i pokazuj Coins w leaderstats, które już mam.

RoCode robi
  • Może poszukać istniejących leaderstats i kodu DataStore przez Search Scripts i Read Script, żeby rozbudować to, co masz, zamiast dodawać drugi skrypt zapisu. W dużej grze podaj nazwę skryptu albo folderu w wiadomości.
  • Tworzy ModuleScript i podłączający go Script przez Create Script albo zmienia istniejące przez Edit Script
  • Uruchamia Check Script dla każdego napisanego skryptu: sprawdzenie kompilacji w Studio z krótką listą ostrzeżeń, a nie sprawdzanie typów ani testowe uruchomienie
  • Wysyła zmiany paczkami, a każda paczka to punkt cofania (undo) w Studio

Włączyć Studio Access to API Services w kopii testowej i tak musisz sam: RoCode nie może zmieniać tego ustawienia. Z pluginem 3.9 lub nowszym jego krótki playtest czyta błędy, a z pluginem 3.9.11 lub nowszym może sterować testową postacią, żeby sprawdzić, czy gra działa, ale sprawdza tylko to, co sam postanowił sprawdzić, więc zagraj sam i upewnij się, że Coins, Level i Inventory się zapisują i wczytują. Jeśli zapis nie przeszedł w twoim teście, Check Output może przeczytać linie Server z uruchomionego przez ciebie playtestu. Zapis zwykle dodaje się, gdy główna pętla gry już działa; tworzenie gry Roblox z AI po jednym systemie naraz pokazuje tę kolejność. Jak RoCode łączy się ze Studio.

Najczęstsze pytania

Jak włączyć DataStore w Roblox Studio?

Opublikuj grę, otwórz File > Experience Settings > Security, włącz Enable Studio Access to API Services i kliknij Save. Rób to w osobnej grze testowej, bo Studio używa wtedy tych samych magazynów danych co opublikowane serwery tej gry.

Czy Roblox zapisuje dane gracza automatycznie?

Nie. Nic o graczu nie zostaje zapisane po sesji, jeśli serwerowy skrypt nie zapisze tego przez DataStoreService, leaderstats też nie.

Co wybrać: ProfileStore czy DataStoreService bezpośrednio?

ProfileStore też jest zbudowany na magazynach danych, więc pytanie brzmi, czy chcesz, żeby blokadę sesji ktoś napisał i utrzymywał za ciebie. Przy wymianie, płatnych przedmiotach albo częstych teleportach blokada jest tego warta, z biblioteki albo wzorcowego przykładu Roblox. Dla mniejszej gry moduł taki jak ten łatwiej czytać i zmieniać.

Jak zresetować albo usunąć dane gracza?

W Data Stores Manager znajdź klucz i wybierz Mark for Deletion, co można cofnąć w okresie oczekiwania, albo wywołaj RemoveAsync dla klucza z serwerowego skryptu. Rób to, gdy gracz jest offline, inaczej następny zapis jego serwera zapisze dane z powrotem. W kopii testowej zmiana STORE_NAME zaczyna wszystkich od zera; nigdy nie rób tego w opublikowanej grze.

Źródła i dalsza lektura

Jak sprawdziliśmy kod: każdy skrypt na tej stronie przechodzi ścisłe sprawdzanie typów Luau z definicjami API Robloxa (luau-lsp, 20 listopada 2026). Sprawdzanie typów wyłapuje źle wpisane API i błędne typy, ale nie logikę gry, więc przetestuj go w Studio przed publikacją.

Wypróbuj RoCode we własnej grze.

Darmowe kredyty codziennie, bez karty. Zainstaluj plugin, opisz funkcję i sprawdź, co pojawi się w Studio.