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
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.
- 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.
- W kopii testowej otwórz File > Experience Settings i przejdź do Security.
- 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
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.
| Typ | Zapisuje się? | Uwagi |
|---|---|---|
| Liczby, stringi, wartości logiczne, bufory | Tak | Stringi muszą być poprawnym UTF-8. Nie przechowuj inf ani nan. |
| Tabele | Tak | Jeś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, Color3 | Nie | Zapis 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ć
| Metoda | Co robi | Do 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
nilanuluje 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.
- W Explorerze najedź kursorem na ServerScriptService, kliknij + i wstaw ModuleScript. Zmień jego nazwę na
PlayerDatai zastąp zawartość kodem poniżej. - ModuleScript wykonuje się tylko wtedy, gdy podłącza go (require) jakiś skrypt. Wstaw do ServerScriptService Script o nazwie
Mainz taką linią:local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Inne serwerowe skrypty podłączają go tak samo. - Zmień
DEFAULTSi typDatapod swoją grę, zostawiając każde pole liczbą, stringiem, wartością logiczną albo tabelą.
ServerScriptService
PlayerData ModuleScript new
Main Script new
StarterPlayer
StarterPlayerScripts
DataWarning LocalScript new
-- 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
| Kiedy | Po co |
|---|---|
| Co 180 sekund, gdy gracz jest na serwerze | Ogranicza 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łanie | Co 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.Loaded | Odpala 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.
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.
- Daj sobie coś do zapisania. Pod linią require w
Maindodaj:PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end) - 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. - Kliknij Stop. Zakończenie testu zamyka serwer, a moduł zapisuje cię przed zamknięciem.
- 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ą.
- 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. - 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ę dzieje | Wynik | Jak zapobiec |
|---|---|---|
| Wczytanie się nie udało, a skrypt i tak zapisuje | Wartości domyślne nadpisują prawdziwy postęp: całkowite wymazanie | Nigdy nie zapisywać gracza, którego wczytanie się nie udało |
Zapis tylko w PlayerRemoving | Awaria albo wyłączenie serwera pomija zapis | Autozapis plus BindToClose, który czeka na swoje zapisy |
Brak pcall albo brak ponowienia | Jedno nieudane zapytanie zatrzymuje skrypt albo gubi zapis | pcall z kilkoma rozłożonymi w czasie ponowieniami |
| Zapis przy każdej zmianie | Zapytania ustawiają się w kolejce; gdy jest ich 30, nowe są odrzucane | Trzymać dane w pamięci i zapisywać według timera |
| Zapis tego, czego magazyn nie umie przechować | Zapis daje błąd albo wartość wraca jako nil | Zapisywać liczby, stringi, wartości logiczne i tabele z nich |
| Zmiana kształtu danych bez migracji | Stare zapisy wczytują się w złe pola | Wersja schematu i krok migracji |
| Dwa skrypty zapisują jeden klucz | Każdy zapis nadpisuje pola drugiego | Kluczem zarządza jeden moduł |
| Dwa serwery trzymają jednego gracza | Serwer ze starymi danymi zapisuje ostatni i nadpisuje nowy postęp | Blokada 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.
| Opcja | Co to jest | Co warto wiedzieć |
|---|---|---|
| Moduł z tego poradnika | Wczytywanie, cache w pamięci, ponowienia, autozapis, zapis przy wyłączeniu i wersje schematu, bez blokady | Wystarczająco krótki, żeby przeczytać go w całości i zmienić |
| Przykład Roblox dla danych graczy i zakupów | Wzorcowy kod od Roblox z blokadą sesji, ponowieniami po kolei dla każdego klucza i obsługą paragonów zakupów | Roblox mówi, że nie jest sprawdzony w boju w popularnej grze i nie powinien być używany bez zmian bez obszernych testów |
| ProfileStore | Darmowy moduł społeczności z otwartym kodem, następca ProfileService, zbudowany wokół blokady sesji i autozapisu | Nie 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.
| Typ zapytania | Zwykłe magazyny | Uporządkowane magazyny |
|---|---|---|
Odczyt: GetAsync, odczyt w UpdateAsync | 60 + 40 × graczy | 60 + 40 × graczy |
Zapis: SetAsync, IncrementAsync, zapis w UpdateAsync | 60 + 40 × graczy | 30 + 5 × graczy |
Lista: ListKeysAsync albo GetSortedAsync dla uporządkowanych magazynów | 5 + 2 × graczy | 5 + 2 × graczy |
Usuwanie: RemoveAsync | 60 + 40 × graczy | 30 + 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.
| Limit | Wartość |
|---|---|
| Nazwa magazynu, nazwa klucza, scope | Po 50 znaków |
| Wartość w jednym kluczu | 4 194 304 znaki w postaci JSON |
| Odczyt jednego klucza ze wszystkich serwerów | 25 MB na minutę |
| Zapis do jednego klucza ze wszystkich serwerów | 4 MB na minutę, każde zapytanie jest zaokrąglane w górę do następnego KB |
| Oczekujące zapytania | 30 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.
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.
- 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
- Roblox Creator Docs: Data stores (po angielsku). dostęp Studio, GetAsync, SetAsync, UpdateAsync, set i update
- Roblox Creator Docs: Best practices for data stores (po angielsku). jeden klucz na gracza, dane w pamięci, ponowienia z rosnącą przerwą, zewnętrzne moduły
- Roblox Creator Docs: Data store error codes and limits (po angielsku). kody błędów, limity zapytań serwera i gry, limity rozmiaru, przepustowości i miejsca
- Roblox Creator Docs: Versioning, listing and caching (po angielsku). wersje godzinowe, migawki, 4-sekundowy cache, co można zapisywać
- Roblox Creator Docs: Implement player data and purchasing systems (po angielsku). wzorcowy przykład, blokada sesji, nieudane wczytania, autozapis co 180 sekund
- Roblox Creator Docs: Data Stores Manager (po angielsku). przeglądanie kluczy, cofanie wersji, usuwanie danych
- Roblox Engine API: DataModel:BindToClose (po angielsku). 30 sekund na wyłączenie
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ą.