V skratke
Používajte DataStoreService zo serverového Scriptu: dáta hráča načítajte cez GetAsync, keď príde, držte ich v tabuľke, kým hrá, a ukladajte cez UpdateAsync podľa časovača, pri odchode (PlayerRemoving) a pri vypnutí servera (game:BindToClose). Každé volanie obaľte do pcall a neúspešné niekoľkokrát zopakujte.
- Ak chcete testovať v Studiu, publikujte place a zapnite File > Experience Settings > Security > Enable Studio Access to API Services v samostatnej testovacej hre: Studio používa rovnaké dáta ako živé servery.
- Ak sa dáta hráča nenačítali, tohto hráča nikdy neukladajte. Uloženie predvolených hodnôt prepíše jeho skutočný postup.
- Majte jednu tabuľku na hráča pod jedným kľúčom, napríklad
User_12345, a ukladajte podľa časovača, nie pri každej zmene. - Pre výmenu predmetov alebo platené predmety pridajte zámok relácie, aby dva servery nemohli ukladať toho istého hráča.
Na tejto stránke
Skôr než začnete: zapnite prístup Studia v testovacej kópii
Hra spustená v Studiu nemôže pristupovať k úložiskám dát, kým to nepovolíte. Povolenie má háčik, pred ktorým dokumentácia Robloxu varuje: Studio potom číta a zapisuje rovnaké úložiská dát ako živá hra, takže test, ktorý v Studiu vynuluje vaše mince, ich vynuluje aj v živej hre, a chyba v testovacom kóde môže poškodiť kľúče skutočných hráčov.
- Urobte testovaciu kópiu. Uložte place do súboru, otvorte kópiu, vyberte File > Publish to Roblox As a kliknite na Create new game. Nepridávajte ju ako place vnútri živej hry: všetky place jednej hry zdieľajú rovnaké úložiská dát.
- V testovacej kópii otvorte File > Experience Settings a prejdite do Security.
- Zapnite Enable Studio Access to API Services a kliknite na Save.
Volania úložísk dát fungujú len v serverových Script; LocalScript, ktorý to skúsi, dostane chybu, takže klienti nemôžu uložené dáta zapisovať. Keď ich má meniť tlačidlo, klient požiada server cez RemoteEvent a rozhodne server (pozrite návod na RemoteEvents, po anglicky).
Ako úložiská dát uchovávajú dáta hráčov
Úložisko dát (data store) je pomenovaná sada kľúčov a hodnôt na serveroch Robloxu, spoločná pre všetky servery a všetky place vašej hry. DataStoreService:GetDataStore("PlayerData") vráti jedno také úložisko.
Odporúčania Robloxu sa dajú zhrnúť pravidlom jedno úložisko pre dáta hráčov, jeden kľúč na hráča, jedna tabuľka v každom kľúči. Kľúč skladajte z UserId hráča, napríklad User_12345, a nikdy z mena, ktoré si môže zmeniť. Stály vzor User_{UserId} tiež umožní automatickému spracovaniu práva na zabudnutie od Robloxu nájsť dáta hráča, ak ho nastavíte.
| Typ | Uloží sa? | Poznámky |
|---|---|---|
| Čísla, reťazce, booleovské hodnoty, buffery | Áno | Reťazce musia byť platné UTF-8. Neukladajte inf ani nan. |
| Tabuľky | Áno | Ak sa dá uložiť aj všetko vnútri. Tabuľka, ktorej číselné kľúče nezačínajú od 1 (takže má dĺžku 0), sa vráti s týmito kľúčmi ako reťazcami. |
Instance, Vector3, CFrame, Color3 | Nie | Uloženie hodí chybu alebo zapíše nil. Ukladajte názov predmetu alebo pozíciu ako tri čísla. |
Každá požiadavka je webové volanie, ktoré môže zlyhať, trvá nejaký čas a čerpá minútový rozpočet. Preto spoľahlivé systémy ukladania čítajú dáta raz pri vstupe hráča, držia ich v serverovej tabuľke, kým hrá, a z času na čas ich zapíšu späť.
GetAsync, SetAsync alebo UpdateAsync: čo vybrať
| Metóda | Čo robí | Na čo |
|---|---|---|
GetAsync(key) | Prečíta hodnotu. Výsledok sa na tomto serveri uloží do medzipamäte na 4 sekundy. | Načítanie dát hráča |
SetAsync(key, value) | Prepíše hodnotu bez toho, aby ju čítal. Jeden zápis. | Nový kľúč alebo hodnota, ktorá nezávisí od starej |
UpdateAsync(key, callback) | Prečíta poslednú hodnotu, odovzdá ju vašej funkcii a zapíše to, čo vráti. Jedno čítanie a jeden zápis. | Ukladanie dát hráča a akýkoľvek kľúč, do ktorého môže písať viac serverov |
IncrementAsync(key, delta) | Pripočíta celé číslo k uloženému celému číslu. | Počítadlá |
RemoveAsync(key) | Zmaže kľúč a vráti starú hodnotu. Skoršie verzie možno ďalej vypísať a prečítať. | Zmazanie dát hráča |
SetAsync píše naslepo: ak dva servery ukladajú ten istý kľúč takmer súčasne, vyhrá posledný zápis, nech je v ňom čokoľvek. UpdateAsync najprv prečíta súčasnú hodnotu, a ak medzitým zapíše iný server, Roblox vašu funkciu spustí znova s novou hodnotou. Roblox ho odporúča vždy, keď zápis závisí od súčasnej hodnoty alebo keď kľúč môže zapisovať viac serverov, a to sú presne dáta hráča. Funkcia má tri pravidlá:
- Nesmie pozastavovať beh (yield): žiadne
task.wait()ani iné volania úložísk vnútri. - Môže prebehnúť viac ako raz, takže má len vypočítať novú hodnotu a nikdy nevydávať predmety ani spúšťať udalosti.
- Návrat
nilzápis zruší. Modul to používa, aby neprepísal dáta uložené novšou verziou hry.
Krok 1: vytvorte modul PlayerData
Tento ModuleScript je jediný kód, ktorý s úložiskom dát komunikuje. Načíta dáta hráča pri vstupe, drží ich v pamäti, ukladá ich každých 180 sekúnd, pri odchode a pri vypnutí servera a odmieta ukladať tých, ktorých dáta sa nenačítali.
- V Exploreri prejdite myšou na ServerScriptService, kliknite na + a vložte ModuleScript. Premenujte ho na
PlayerDataa nahraďte obsah kódom nižšie. - ModuleScript sa spustí len vtedy, keď ho nejaký skript pripojí (require). Vložte do ServerScriptService Script s názvom
Maina týmto riadkom:local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Ostatné serverové skripty ho pripájajú rovnako. - Upravte
DEFAULTSa typDatapodľa svojej hry, každé pole nechajte číslom, reťazcom, booleovskou hodnotou alebo tabuľkou.
ServerScriptService
PlayerData ModuleScript new
Main Script new
StarterPlayer
StarterPlayerScripts
DataWarning LocalScript new
-- PlayerData: načíta dáta hráča pri vstupe, drží ich v pamäti
-- a ukladá ich podľa časovača, pri odchode a pri vypnutí servera.
-- Ostatné serverové skripty ich čítajú a menia cez 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 -- zvýšte, keď sa zmení podoba dát, a pridajte krok do migrate()
local AUTOSAVE_SECONDS = 180
-- V Studiu to neúspešné volanie hneď vzdá, takže test bez prístupu k úložisku beží rýchlo
local MAX_ATTEMPTS = if RunService:IsStudio() then 1 else 4
local FIRST_RETRY_SECONDS = 1 -- zdvojnásobuje sa po každom neúspechu: 1, 2, 4
export type Data = {
SchemaVersion: number,
Coins: number,
Level: number,
Inventory: { string },
}
-- S čím začína úplne nový hráč
local DEFAULTS: { [string]: any } = {
Coins = 0,
Level = 1,
Inventory = {},
}
type Session = {
key: string,
userId: number,
data: Data,
canSave: boolean, -- false, ak sa načítanie nepodarilo: predvolené dáta nesmú nahradiť skutočný postup
}
-- Volá sa vnútri každého pcall nižšie, takže ešte nepublikovaný place
-- (bez prístupu k úložisku) aj tak načíta hráča s predvolenými dátami
local function store(): DataStore
return DataStoreService:GetDataStore(STORE_NAME)
end
local sessions: { [Player]: Session } = {}
local pendingSaves: { [string]: number } = {} -- ukladania, ktoré ešte prebiehajú, podľa kľúčov
local loadedEvent = Instance.new("BindableEvent")
local PlayerData = {}
-- Spustí sa s hráčom, keď sú jeho dáta pripravené. Tabuľku berte cez PlayerData.Get(player):
-- tabuľka poslaná cez BindableEvent príde ako kópia a jej zmena nič nezmení.
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) -- čerstvá kópia, aby hráči nikdy nezdieľali jednu tabuľku Inventory
data.SchemaVersion = SCHEMA_VERSION
return data
end
-- Prevedie uložené dáta na súčasnú schému. Vráti nil, ak ich nemožno bezpečne použiť.
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 -- uložené novšou verziou hry: tu nenačítavať ani neprepisovať
end
-- Jeden krok na každú zmenu schémy, od starších k novším
if version < 2 then
-- Príklad: vo verzii 1 sa mena volala Gold. Skopírujeme ju, len ak Coins chýba,
-- aby staré dáta, kde Coins už sú, ale chýba SchemaVersion, zachovali hodnotu.
if saved.Coins == nil then
saved.Coins = saved.Gold
end
saved.Gold = nil
end
-- Pridáme polia, ktoré pribudli od posledného uloženia hráča, a nahradíme hodnoty zlého 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
-- Vykoná volanie úložiska v pcall. Pri neúspechu počká a skúsi to znova, zakaždým zdvojnásobí
-- čakanie a pridá trochu náhody, aby servery neopakovali všetky 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 -- návrat nil zruší zápis
end
-- Zapíšeme celú súčasnú tabuľku so značkou UserId hráča
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()
-- Začneme v náhodnom okamihu intervalu, aby servery neukladali všetky 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
-- Ak hráč práve odišiel z tohto servera a vrátil sa, najprv necháme dobehnúť posledné uloženie
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 -- odišiel počas načítania: nič sa nezmenilo, nie je čo ukladať
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 to môže prečítať a hráča varovať
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 -- zastaví slučku automatického ukladania a opakované volanie nič nerobí
save(session)
end
-- Živá tabuľka dát hráča alebo nil, kým sa nenačítala. Meňte ju len zo serverových skriptov.
function PlayerData.Get(player: Player): Data?
local session = sessions[player]
return if session then session.data else nil
end
-- True, keď sa dáta hráča načítali a budú uložené. Kontrolujte pred každým predajom.
function PlayerData.CanSave(player: Player): boolean
local session = sessions[player]
return session ~= nil and session.canSave
end
-- Uloží hneď, bez čakania na časovač, pre dôležité okamihy ako nákup.
-- Pozastaví beh a vráti true, keď uloženie prešlo.
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) -- hráči, ktorí prišli pred prvým pripojením tohto modulu
end
game:BindToClose(function()
-- Server dáva týmto funkciám 30 sekúnd, preto ukladáme všetkých súčasne
for player in sessions do
task.spawn(endSession, player)
end
-- Potom počkáme na všetky ešte prebiehajúce ukladania, vrátane tých začatých v PlayerRemoving
while next(pendingSaves) do
task.wait()
end
end)
return PlayerData
Keď je hra vonku, nemeňte STORE_NAME ani vzor kľúča User_. Zmena ktoréhokoľvek z nich nasmeruje modul na prázdne kľúče a každý hráč začne znova s predvolenými hodnotami.
Ako modul chráni dáta
Predvolené hodnoty a verzia schémy
Nový hráč dostane čerstvú kópiu DEFAULTS. Musí to byť naozaj kópia: keby všetci hráči zdieľali jednu tabuľku Inventory, predmet pridaný jednému by sa objavil u všetkých.
Každá uložená tabuľka nesie SchemaVersion. Pridanie poľa novú verziu nevyžaduje, pretože migrate doplní chýbajúce polia z predvolených hodnôt. Premenovanie alebo prestavba ju vyžaduje: zvýšte SCHEMA_VERSION a pridajte krok, ako v príklade, ktorý premenúva Gold na Coins (v novej hre ho zmažte a začnite od 1). Dáta s vyššou verziou, než má server, pochádzajú z novšieho vydania, ktoré sa ešte zavádza, a preto sa ich staršie servery nedotknú.
Neúspešné načítanie sa nikdy neukladá
Toto pravidlo chráni pred úplným zmazaním. Ak všetky pokusy o načítanie zlyhali, hráč hrá s predvolenými dátami, ale canSave je false, takže tieto hodnoty nikdy neprepíšu jeho skutočný postup. Modul tiež nastaví atribút DataLoaded na false a krok 3 ho použije, aby to hráčovi oznámil. Referenčný príklad Robloxu spracúva neúspešné načítania rovnako a navrhuje to namiesto vyhodenia; ak dávate prednosť vyhodeniu, zavolajte player:Kick() so správou tam, kde modul vypisuje varovanie.
Opakovanie s narastajúcou pauzou
withRetries obalí každé volanie do pcall. Po neúspechu počká 1, potom 2, potom 4 sekundy, zakaždým plus náhodne až polovicu tohto času, a po štyroch pokusoch prestane (v Studiu po jednom, aby sa place bez prístupu k úložisku spustil hneď). Náhoda rozloží opakovania mnohých serverov po výpadku a obmedzenie drží čakanie zhruba do 10 sekúnd, vnútri 30 sekúnd, ktoré server dostáva na vypnutie. Keďže každé uloženie zapisuje celú živú tabuľku cez UpdateAsync, opakovanie, ktoré skončí s oneskorením, nemôže vrátiť staré dáta.
Kedy modul ukladá
| Kedy | Prečo |
|---|---|
| Každých 180 sekúnd, kým je hráč na serveri | Obmedzuje straty pri páde. Prvé uloženie pripadne na náhodný okamih intervalu, aby servery neukladali všetky naraz. Referenčný príklad Robloxu tiež používa 180 sekúnd. |
Keď hráč odíde (PlayerRemoving) | Bežné záverečné uloženie. Relácia sa najprv zmaže, takže automatické ukladanie sa zastaví. |
Keď sa server vypína (game:BindToClose) | Všetci, ktorí sú ešte na serveri, sa uložia naraz a funkcia počká na každé prebiehajúce uloženie. Roblox jej dáva 30 sekúnd. |
Na požiadanie, cez PlayerData.SaveNow(player) | Po niečom, čo sa nesmie stratiť, napríklad po nákupe. |
Ak sa hráč vráti na ten istý server, kým jeho záverečné uloženie ešte prebieha, nové načítanie počká, kým uloženie skončí, takže nemôže prečítať starú hodnotu.
Krok 2: čítajte a meňte dáta z iných skriptov
Všetky serverové skripty, ktoré modul pripoja, pracujú s rovnakými tabuľkami:
| Volanie | Čo robí |
|---|---|
PlayerData.Get(player) | Živá tabuľka dát hráča alebo nil, kým sa nenačítala. Meňte polia priamo, napríklad data.Coins += 10, a ďalšie uloženie to zachytí. |
PlayerData.Loaded | Spustí sa s hráčom, keď sú jeho dáta pripravené, aj po neúspešnom načítaní. Odovzdáva len hráča, pretože tabuľka poslaná cez BindableEvent príde ako kópia. |
PlayerData.CanSave(player) | false, ak sa načítanie nepodarilo. Kontrolujte pred každým predajom: nákup, ktorý nejde uložiť, zmizne, keď hráč odíde. |
PlayerData.SaveNow(player) | Uloží hneď a vráti true, ak sa to podarilo. Pozastaví beh. |
Modul je jediné miesto, kde uložené dáta žijú, a leaderstats sú len zobrazenie: postavte ich ako v návode na leaderboard, naplňte z PlayerData.Get(player) v handleri Loaded a pri zmene hodnoty aktualizujte oboje. Uložené hodnoty nikdy nečítajte späť z leaderstats a nikdy nedovoľte druhému skriptu ukladať ten istý kľúč.
Skript, ktorý modul pripojil až potom, čo hráči prišli, pre nich Loaded zmešká. Pripojte handler a potom ešte prejdite slučkou Players:GetPlayers() a spracujte všetkých, pre ktorých už PlayerData.Get(player) vracia tabuľku.
Nahrádzate starý skript ukladania, napríklad z návodu na leaderboard? Jeho hodnoty zostávajú v jeho vlastnom úložisku a kľúči, takže tento modul začne všetkých od predvolených hodnôt. Pred spustením buď nasmerujte STORE_NAME a predponu User_ na tie staré (migrate považuje dáta bez SchemaVersion za verziu 1 a doplní chýbajúce polia), alebo staré hodnoty preneste a starý skript potom zmažte.
Klienti tieto dáta nikdy nemenia priamo. Tlačidlo obchodu spustí RemoteEvent; server skontroluje CanSave, porovná cenu s Coins hráča, zmení tabuľku a zavolá SaveNow. Návod na GUI obchodu taký nákup na strane servera stavia.
Hotový príklad pridania polí je v návode na clicker simulátor: pridáva PowerLevel a Rebirths do DEFAULTS a typu Data a potom ich mení v tabuľke, ktorú vracia PlayerData.Get. migrate dá nové polia aj hráčom so starými uloženiami.
Krok 3: oznámte hráčovi, že sa jeho dáta nenačítali
Hráč, ktorého dáta sa nenačítali, musí vedieť, že sa táto relácia neuloží, aby sa znova pripojil namiesto toho, aby hral zbytočne. Tento LocalScript sleduje atribút DataLoaded a ukáže banner, keď je 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
-- Server nastaví DataLoaded raz, po pokuse načítať dáta tohto hráča
player:GetAttributeChangedSignal("DataLoaded"):Connect(showWarning)
showWarning()
Krok 4: otestujte ukladanie v Studiu
Robte to v testovacej kópii so zapnutým prístupom Studia.
- Dajte si niečo na uloženie. Pod riadok require v
Mainpridajte:PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end) - Kliknite na Play. Okno Output (v menu Window alebo na karte Script) ukáže vaše meno a 100 (pri prvom spustení), bez varovania
Could not load. - Kliknite na Stop. Ukončenie testu zavrie server a modul vás pred zatvorením uloží.
- Znova kliknite na Play. Output má ukázať 200, o 100 viac ako minule. Ak znova ukazuje rovnaké číslo, uloženie neprešlo: prečítajte si varovanie nad ním.
- Otestujte cestu s chybou. Vypnite prístup Studia a kliknite na Play. Po niekoľkých sekundách opakovaní Output ukáže
Could not load User_...a 100 a objaví sa banner z kroku 3. Zastavte test, prístup znova zapnite a kliknite na Play: Output ukáže 300, vašich uložených 200 plus 100, pretože neúspešná relácia vaše dáta nikdy neprepísala. - Zmažte testovací riadok z
Main.
Prečo sa dáta hráčov strácajú
Toto sú bežné spôsoby, ktorými systém ukladania stratí postup. Modul v kóde rieši prvé štyri riadky a riadok o schéme; ostatné závisia od toho, čo a ako ukladáte, a ten posledný potrebuje zámok relácie.
| Čo sa stane | Výsledok | Ako tomu predísť |
|---|---|---|
| Načítanie zlyhalo, a skript napriek tomu ukladá | Predvolené hodnoty prepíšu skutočný postup: úplné zmazanie | Nikdy neukladať hráča, ktorého načítanie zlyhalo |
Ukladanie len v PlayerRemoving | Pád alebo vypnutie servera uloženie vynechá | Automatické ukladanie plus BindToClose, ktorý na svoje uloženia počká |
Chýba pcall alebo opakovanie | Jedna neúspešná požiadavka zastaví skript alebo stratí uloženie | pcall s niekoľkými časovo rozloženými opakovaniami |
| Ukladanie pri každej zmene | Požiadavky sa radia do frontu; keď je ich vo fronte 30, nové sa zahodia | Držať dáta v pamäti a ukladať podľa časovača |
| Ukladanie toho, čo úložisko nevie uložiť | Uloženie hodí chybu alebo sa hodnota vráti ako nil | Ukladať čísla, reťazce, booleovské hodnoty a tabuľky z nich |
| Zmena podoby dát bez migrácie | Staré uloženia sa načítajú do zlých polí | Verzia schémy a krok migrácie |
| Dva skripty ukladajú ten istý kľúč | Každé uloženie prepíše polia toho druhého | Kľúč vlastní jeden modul |
| Dva servery držia toho istého hráča | Server so starými dátami uloží ako posledný a prepíše nový postup | Zámok relácie |
Zámok relácie, „lock lost“ a ProfileStore
Hráč je pripojený vždy k jednému serveru, ale záverečné uloženie starého servera môže ešte prebiehať, keď príde na nový: pomalé opakovanie, teleport alebo rýchle opätovné pripojenie. Ak nový server načíta dáta ako prvý, bude mať staré dáta a vyhrá ten server, ktorý uloží ako posledný. Dokumentácia Robloxu uvádza, že v hrách s výmenou je táto medzera častou príčinou duplikácie predmetov.
Zámok relácie túto medzeru uzavrie. Keď server načíta kľúč hráča, zapíše v tom istom volaní UpdateAsync svoje ID zámku do metadát kľúča. Každý iný server, ktorý nájde neexpirovaný zámok, ktorý sám nenastavil, tento kľúč nenačíta ani neuloží. Vlastník obnovuje zámok pri každom automatickom uložení a v záverečnom uložení ho uvoľní; ak ho prestane obnovovať, zámok vyprší a môže si ho vziať iný server.
Čo znamená „lock lost“
V systéme so zámkom relácie server stratil zámok, keď kľúč hráča teraz vlastní iný server, pretože zámok vypršal alebo bol prevzatý. Jeho kópia môže byť zastaraná, takže musí prestať tohto hráča ukladať; bežná reakcia je vyhodiť ho so správou, aby sa znova pripojil. Ak ste „lock lost“ videli ako hráč, je to správa vlastného systému ukladania tej hry a vysvetliť ju môžu len jej vývojári.
Potrebujete ho?
Modul z tohto návodu relácie nezamyká. Bez zámku je skutočný najhorší prípad takýto: v zriedkavom súbehu hráč stratí to, čo zarobil na starom serveri po jeho poslednom úspešnom uložení. Zámok pridajte, keď duplikácia alebo strata stojí hráčov niečo skutočné: výmena, developer products, vzácne predmety alebo časté teleporty.
| Možnosť | Čo to je | Čo je dobré vedieť |
|---|---|---|
| Modul z tohto návodu | Načítavanie, medzipamäť v pamäti, opakovania, automatické ukladanie, ukladanie pri vypnutí a verzia schémy, bez zámku | Dosť krátky na to, aby ste ho prečítali celý a upravili |
| Príklad Robloxu pre dáta hráčov a nákupy | Referenčný kód od Robloxu so zámkom relácie, opakovaniami v poradí pre každý kľúč a spracovaním účteniek nákupov | Roblox hovorí, že nie je overený časom v populárnej hre a nemá sa používať tak, ako je, bez rozsiahleho testovania |
| ProfileStore | Bezplatný komunitný modul s otvoreným kódom, nástupca ProfileService, postavený okolo zámku relácie a automatického ukladania | Nie je od Robloxu. Prevod existujúcej hry naň vyžaduje migráciu už uložených dát |
Pri každom module tretej strany Roblox radí overiť, kto ho vlastní, či je udržiavaný a ako sa k svojim dátam dostanete bez neho. Tá istá dokumentácia označuje DataStore2 za zastaranú knižnicu, ktorú nové hry používať nemajú.
Limity úložísk dát
Toto sú limity z dokumentácie Robloxu k 30. septembru 2026. Roblox ich reviduje, preto si overte stránku chybových kódov a limitov (po anglicky), skôr než budete počítať s presným číslom.
| Typ požiadavky | Bežné úložiská | Zoradené úložiská |
|---|---|---|
Čítanie: GetAsync, čítanie v UpdateAsync | 60 + 40 × hráčov | 60 + 40 × hráčov |
Zápis: SetAsync, IncrementAsync, zápis v UpdateAsync | 60 + 40 × hráčov | 30 + 5 × hráčov |
Výpis: ListKeysAsync alebo GetSortedAsync pri zoradených úložiskách | 5 + 2 × hráčov | 5 + 2 × hráčov |
Mazanie: RemoveAsync | 60 + 40 × hráčov | 30 + 5 × hráčov |
Pri 20 hráčoch môže server urobiť 860 bežných zápisov za minútu; automatické ukladanie tohto modulu ich spotrebuje asi 7, plus jeden za každého hráča, ktorý odišiel. Rozpočet vyčerpá ukladanie pri každej zobratej minci. Druhý rozpočet platí pre celú hru a zdieľa sa s Open Cloud: 300 čítaní za minútu plus 40 za každého hráča online a 300 zápisov plus 20 za hráča.
| Limit | Hodnota |
|---|---|
| Názov úložiska, názov kľúča, scope | Po 50 znakov |
| Hodnota v jednom kľúči | 4 194 304 znakov ako JSON |
| Čítanie jedného kľúča zo všetkých serverov | 25 MB za minútu |
| Zápis do jedného kľúča zo všetkých serverov | 4 MB za minútu, každá požiadavka sa zaokrúhli nahor na ďalší KB |
| Čakajúce požiadavky | 30 na front; nad to požiadavky zlyhajú s chybami 301-306 |
| Úložisko pre celú hru | 500 MB plus 1 MB za každého používateľa za celý čas |
Veľkosť dát hráča zmeriate cez #HttpService:JSONEncode(data) a zostávajúci rozpočet živého servera zistíte cez DataStoreService:GetRequestBudgetForRequestType(Enum.DataStoreRequestType.StandardWrite). Volania GetAsync, na ktoré odpovedala 4-sekundová medzipamäť, sa nepočítajú. Režim Run v Studiu má vlastné, možno nižšie limity, preto Roblox na testovanie limitov požiadaviek odporúča Team Create.
Verzie a zálohy
Bežné úložiská dát uchovávajú históriu za vás. Prvý zápis do kľúča v každej hodine UTC sa uloží ako verzia a ďalšie zápisy v tej hodine sa navzájom prepisujú. Stará verzia vyprší 30 dní potom, čo ju nahradil novší zápis; posledná nevyprší nikdy. Zoradené úložiská verzie neuchovávajú.
Ak chcete vrátiť jedného hráča, otvorte Data Stores Manager (Creations, vaša hra, Configure > Data Stores Manager), vyberte jeho kľúč, vyberte skoršiu verziu a kliknite na Revert; potrebujete na to právo Edit. Robte to, keď hráč nie je online, inak server s jeho reláciou uloží svoju kópiu cez vrátenú verziu. Zo serverového skriptu ListVersionsAsync a GetVersionAsync nájdu a prečítajú starú verziu, ktorú potom zapíšete späť ako súčasnú hodnotu.
Pred publikovaním aktualizácie, ktorá mení spôsob ukladania dát, Roblox odporúča urobiť snímku cez Open Cloud Snapshot Data Stores API (jednu denne na hru). Bez nej chybné uloženie o 3:30 UTC prepíše všetko, čo bolo do toho kľúča zapísané od 3:00, pretože padne do tej istej hodinovej verzie.
Časté chyby a riešenia
Chyby úložísk dát sa objavujú v okne Output v Studiu a modul vypíše varovanie s textom chyby Robloxu pri každom neúspešnom pokuse. Návod na chyby v skriptoch vysvetľuje, ako Output vôbec čítať.
StudioAccessToApisNotAllowed (chyba 403)
„Can't write to DataStore from Studio because API access is not enabled.“ Publikujte place a potom zapnite Enable Studio Access to API Services v File > Experience Settings > Security, v testovacej kópii.
DataStore request was added to queue
Server posiela požiadavky rýchlejšie, než rozpočet dovolí, alebo príliš často zapisuje jeden kľúč, zvyčajne kvôli ukladaniu pri každej zmene alebo v slučke. Keď je vo fronte 30 požiadaviek, nové zlyhajú s chybami 301-306. Držte dáta v pamäti a ukladajte podľa časovača.
CantStoreValue (chyba 104), alebo sa pole vráti ako nil
V tabuľke je niečo, čo úložisko nevie uložiť, napríklad Instance, Vector3 alebo Color3. Ukladajte namiesto toho názov, ID alebo jednoduché čísla a objekt pri načítaní obnovte.
ValueTooLarge (chyba 105)
Jeden kľúč uchováva viac ako 4 194 304 znakov JSON. Zmerajte to cez #HttpService:JSONEncode(data), odstráňte, čo sa dá obnoviť, alebo dáta rozdeľte do niekoľkých stálych kľúčov.
Chyby nie sú, ale dáta sa neukladajú
Hľadajte varovanie modulu Could not load: po neúspešnom načítaní zámerne odmieta ukladať. Inak sa hodnota najskôr menila v LocalScripte, a to sa na server nikdy nedostane, alebo ten istý kľúč ukladá iný skript.
Dáta sa pri každom opätovnom pripojení vynulujú
Kľúč sa medzi reláciami mení (je zložený z player.Name, alebo ste zmenili STORE_NAME), načítanie zlyháva a vidíte predvolené hodnoty, alebo modul nikto nepripája a vôbec nebeží. Skontrolujte Output a to, že Main pripája PlayerData.
Postavte to s RoCode
Ak sa vám to nechce stavať ručne, RoCode to môže urobiť priamo vo vašom otvorenom place. Je to nezávislý AI agent, nie od Robloxu, ktorý pracuje cez plugin pre Roblox Studio: píše Luau, ktorý používa DataStoreService ako každý iný skript, a vytvára skripty vo vašom Exploreri. Sám k vašim úložiskám dát nikdy nepristupuje, ale s pluginom 3.9 alebo novším môže kliknúť na Play kvôli krátkemu playtestu, kde vaše skripty bežia ako v každom teste.
Pridaj do mojej hry ukladanie: ukladaj Coins, Level a Inventory v module PlayerData s automatickým ukladaním a ukladaním pri vypnutí servera a zobrazuj Coins v leaderstats, ktoré už mám.
- Môže vyhľadať existujúce leaderstats a kód DataStore cez Search Scripts a Read Script, aby rozšíril to, čo máte, a nepridával druhý skript ukladania. Vo veľkom place uveďte v správe názov skriptu alebo priečinka.
- Vytvorí ModuleScript a Script, ktorý ho pripája, cez Create Script, alebo zmení existujúce cez Edit Script
- Spustí Check Script pre každý napísaný skript: kontrolu kompilácie vnútri Studia s krátkym zoznamom varovaní, nie kontrolu typov ani testovací beh
- Posiela zmeny po dávkach a každá dávka je bod na vrátenie (undo) v Studiu
Studio Access to API Services v testovacej kópii budete musieť zapnúť sami: RoCode toto nastavenie meniť nemôže. S pluginom 3.9 alebo novším jeho krátky playtest číta chyby a s pluginom 3.9.11 alebo novším môže ovládať testovaciu postavu, aby overil, že hra funguje, ale kontroluje len to, čo sa sám rozhodol kontrolovať, preto si zahrajte sami a overte, že sa Coins, Level a Inventory ukladajú a načítavajú. Ak uloženie vo vašom teste neprešlo, Check Output vie prečítať riadky Server z playtestu, ktorý ste spustili. Ukladanie sa zvyčajne pridáva, keď už hlavná herná slučka funguje; tvorba hry v Robloxe s AI po jednom systéme ukazuje toto poradie. Ako sa RoCode pripája k Studiu.
Časté otázky
Ako zapnúť DataStore v Roblox Studiu?
Publikujte place, otvorte File > Experience Settings > Security, zapnite Enable Studio Access to API Services a kliknite na Save. Robte to v samostatnej testovacej hre, pretože Studio potom používa rovnaké úložiská dát ako živé servery tejto hry.
Ukladá Roblox dáta hráča automaticky?
Nie. Nič o hráčovi sa po relácii neuloží, ak to serverový skript neuloží cez DataStoreService, a leaderstats tiež nie.
Čo vybrať: ProfileStore, alebo priamo DataStoreService?
ProfileStore je tiež postavený na úložiskách dát, takže otázka je, či chcete, aby vám zámok relácie niekto napísal a udržiaval. Pre výmenu, platené predmety alebo časté teleporty sa zámok oplatí, z knižnice alebo z referenčného príkladu Robloxu. Pri menšej hre je modul ako tento jednoduchšie čítať aj meniť.
Ako vynulovať alebo zmazať dáta hráča?
V Data Stores Manager nájdite kľúč a vyberte Mark for Deletion, čo možno počas čakacej doby vrátiť, alebo zavolajte RemoveAsync pre kľúč zo serverového skriptu. Robte to, keď hráč nie je online, inak ďalšie uloženie jeho servera dáta zapíše späť. V testovacej kópii zmena STORE_NAME začne všetkých od nuly; v živej hre to nikdy nerobte.
Zdroje a ďalšie čítanie
- Roblox Creator Docs: Data stores (po anglicky). prístup Studia, GetAsync, SetAsync, UpdateAsync, set a update
- Roblox Creator Docs: Best practices for data stores (po anglicky). jeden kľúč na hráča, dáta v pamäti, opakovania s narastajúcou pauzou, moduly tretích strán
- Roblox Creator Docs: Data store error codes and limits (po anglicky). chybové kódy, limity požiadaviek servera a hry, limity veľkosti, priepustnosti a úložiska
- Roblox Creator Docs: Versioning, listing and caching (po anglicky). hodinové verzie, snímky, 4-sekundová medzipamäť, čo možno ukladať
- Roblox Creator Docs: Implement player data and purchasing systems (po anglicky). referenčný príklad, zámok relácie, neúspešné načítania, automatické ukladanie raz za 180 sekúnd
- Roblox Creator Docs: Data Stores Manager (po anglicky). prehliadanie kľúčov, vracanie verzií, mazanie dát
- Roblox Engine API: DataModel:BindToClose (po anglicky). 30 sekúnd na vypnutie
Ako bol kód overený: každý skript na tejto stránke prechádza prísnou kontrolou typov Luau s definíciami Roblox API (luau-lsp, 20. novembra 2026). Kontrola typov zachytí chyby v názvoch API a nesprávne typy, ale nie chyby v hernej logike, preto všetko pred publikovaním otestujte v Studiu.