Ve zkratce
Používejte DataStoreService ze serverového Scriptu: data hráče načtěte přes GetAsync, když přijde, držte je v tabulce, zatímco hraje, a ukládejte přes UpdateAsync podle časovače, při odchodu (PlayerRemoving) a při vypnutí serveru (game:BindToClose). Každé volání obalte do pcall a neúspěšná několikrát zopakujte.
- Chcete-li testovat ve Studiu, publikujte place a zapněte File > Experience Settings > Security > Enable Studio Access to API Services v samostatné testovací hře: Studio používá stejná data jako živé servery.
- Pokud se data hráče nenačetla, tohoto hráče nikdy neukládejte. Uložení výchozích hodnot přepíše jeho skutečný postup.
- Mějte jednu tabulku na hráče pod jedním klíčem, například
User_12345, a ukládejte podle časovače, ne při každé změně. - Pro výměnu předmětů nebo placené předměty přidejte zámek relace, aby dva servery nemohly ukládat stejného hráče.
Na této stránce
Než začnete: zapněte přístup Studia v testovací kopii
Hra spuštěná ve Studiu nemůže přistupovat k úložištím dat, dokud to nepovolíte. Povolení má háček, před kterým dokumentace Robloxu varuje: Studio pak čte a zapisuje stejná úložiště dat jako živá hra, takže test, který ve Studiu vynuluje vaše mince, je vynuluje i v živé hře, a chyba v testovacím kódu může poškodit klíče skutečných hráčů.
- Udělejte testovací kopii. Uložte place do souboru, otevřete kopii, vyberte File > Publish to Roblox As a klikněte na Create new game. Nepřidávejte ji jako place uvnitř živé hry: všechny place jedné hry sdílejí stejná úložiště dat.
- V testovací kopii otevřete File > Experience Settings a přejděte do Security.
- Zapněte Enable Studio Access to API Services a klikněte na Save.
Volání úložišť dat fungují jen v serverových Script; LocalScript, který to zkusí, dostane chybu, takže klienti nemohou uložená data zapisovat. Když je má měnit tlačítko, klient požádá server přes RemoteEvent a rozhodne server (viz návod k RemoteEvents, anglicky).
Jak úložiště dat uchovávají data hráčů
Úložiště dat (data store) je pojmenovaná sada klíčů a hodnot na serverech Robloxu, společná pro všechny servery a všechny place vaší hry. DataStoreService:GetDataStore("PlayerData") vrátí jedno takové úložiště.
Doporučení Robloxu se dají shrnout pravidlem jedno úložiště pro data hráčů, jeden klíč na hráče, jedna tabulka v každém klíči. Klíč skládejte z UserId hráče, například User_12345, a nikdy ze jména, které si může změnit. Stálý vzor User_{UserId} také umožní automatickému zpracování práva být zapomenut od Robloxu najít data hráče, pokud ho nastavíte.
| Typ | Uloží se? | Poznámky |
|---|---|---|
| Čísla, řetězce, booleovské hodnoty, buffery | Ano | Řetězce musí být platné UTF-8. Neukládejte inf ani nan. |
| Tabulky | Ano | Pokud se dá uložit i všechno uvnitř. Tabulka, jejíž číselné klíče nezačínají od 1 (takže má délku 0), se vrátí s těmito klíči jako řetězci. |
Instance, Vector3, CFrame, Color3 | Ne | Uložení hodí chybu nebo zapíše nil. Ukládejte název předmětu nebo pozici jako tři čísla. |
Každý požadavek je webové volání, které může selhat, trvá nějakou dobu a čerpá minutový rozpočet. Proto spolehlivé systémy ukládání čtou data jednou při vstupu hráče, drží je v serverové tabulce, zatímco hraje, a čas od času je zapíšou zpět.
GetAsync, SetAsync, nebo UpdateAsync: co vybrat
| Metoda | Co dělá | K čemu |
|---|---|---|
GetAsync(key) | Přečte hodnotu. Výsledek se na tomto serveru uloží do mezipaměti na 4 sekundy. | Načtení dat hráče |
SetAsync(key, value) | Přepíše hodnotu, aniž by ji četl. Jeden zápis. | Nový klíč nebo hodnota, která nezávisí na staré |
UpdateAsync(key, callback) | Přečte poslední hodnotu, předá ji vaší funkci a zapíše to, co vrátí. Jedno čtení a jeden zápis. | Ukládání dat hráče a jakýkoli klíč, do kterého může psát víc serverů |
IncrementAsync(key, delta) | Přičte celé číslo k uloženému celému číslu. | Počítadla |
RemoveAsync(key) | Smaže klíč a vrátí starou hodnotu. Dřívější verze lze dál vypsat a přečíst. | Smazání dat hráče |
SetAsync píše naslepo: pokud dva servery ukládají stejný klíč skoro současně, vyhraje poslední zápis, ať je v něm cokoli. UpdateAsync nejdřív přečte současnou hodnotu, a pokud mezitím zapíše jiný server, Roblox vaši funkci spustí znovu s novou hodnotou. Roblox ho doporučuje vždy, když zápis závisí na současné hodnotě nebo když klíč může zapisovat víc serverů, a to jsou přesně data hráče. Funkce má tři pravidla:
- Nesmí pozastavovat běh (yield): žádné
task.wait()ani jiná volání úložišť uvnitř. - Může proběhnout víc než jednou, takže má jen spočítat novou hodnotu a nikdy nevydávat předměty ani spouštět události.
- Návrat
nilzápis zruší. Modul to používá, aby nepřepsal data uložená novější verzí hry.
Krok 1: vytvořte modul PlayerData
Tento ModuleScript je jediný kód, který s úložištěm dat komunikuje. Načte data hráče při vstupu, drží je v paměti, ukládá je každých 180 sekund, při odchodu a při vypnutí serveru a odmítá ukládat ty, jejichž data se nenačetla.
- V Exploreru najeďte myší na ServerScriptService, klikněte na + a vložte ModuleScript. Přejmenujte ho na
PlayerDataa nahraďte obsah kódem níže. - ModuleScript se spustí jen tehdy, když ho nějaký skript připojí (require). Vložte do ServerScriptService Script s názvem
Maina tímto řádkem:local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Ostatní serverové skripty ho připojují stejně. - Upravte
DEFAULTSa typDatapodle své hry, každé pole nechte číslem, řetězcem, booleovskou hodnotou nebo tabulkou.
ServerScriptService
PlayerData ModuleScript new
Main Script new
StarterPlayer
StarterPlayerScripts
DataWarning LocalScript new
-- PlayerData: načte data hráče při vstupu, drží je v paměti
-- a ukládá je podle časovače, při odchodu a při vypnutí serveru.
-- Ostatní serverové skripty je čtou a mění přes 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 -- zvyšte, když se změní podoba dat, a přidejte krok do migrate()
local AUTOSAVE_SECONDS = 180
-- Ve Studiu neúspěšné volání to hned vzdá, takže test bez přístupu k úložišti běží rychle
local MAX_ATTEMPTS = if RunService:IsStudio() then 1 else 4
local FIRST_RETRY_SECONDS = 1 -- zdvojnásobuje se po každém neúspěchu: 1, 2, 4
export type Data = {
SchemaVersion: number,
Coins: number,
Level: number,
Inventory: { string },
}
-- S čím začíná úplně nový hráč
local DEFAULTS: { [string]: any } = {
Coins = 0,
Level = 1,
Inventory = {},
}
type Session = {
key: string,
userId: number,
data: Data,
canSave: boolean, -- false, pokud se načtení nepovedlo: výchozí data nesmí nahradit skutečný postup
}
-- Volá se uvnitř každého pcall níže, takže ještě nepublikovaný place
-- (bez přístupu k úložišti) stejně načte hráče s výchozími daty
local function store(): DataStore
return DataStoreService:GetDataStore(STORE_NAME)
end
local sessions: { [Player]: Session } = {}
local pendingSaves: { [string]: number } = {} -- ukládání, která ještě probíhají, podle klíčů
local loadedEvent = Instance.new("BindableEvent")
local PlayerData = {}
-- Spustí se s hráčem, když jsou jeho data připravená. Tabulku berte přes PlayerData.Get(player):
-- tabulka poslaná přes BindableEvent přijde jako kopie a její změna nic nezmění.
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á kopie, aby hráči nikdy nesdíleli jednu tabulku Inventory
data.SchemaVersion = SCHEMA_VERSION
return data
end
-- Převede uložená data na současné schéma. Vrátí nil, pokud je nelze bezpečně použít.
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ženo novější verzí hry: tady nenačítat ani nepřepisovat
end
-- Jeden krok na každou změnu schématu, od starších k novějším
if version < 2 then
-- Příklad: ve verzi 1 se měna jmenovala Gold. Zkopírujeme ji, jen pokud Coins chybí,
-- aby stará data, kde Coins už jsou, ale chybí SchemaVersion, zachovala hodnotu.
if saved.Coins == nil then
saved.Coins = saved.Gold
end
saved.Gold = nil
end
-- Přidáme pole, která přibyla od posledního uložení hráče, a nahradíme hodnoty špatné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
-- Provede volání úložiště v pcall. Při neúspěchu počká a zkusí to znovu, pokaždé zdvojnásobí
-- čekání a přidá trochu náhody, aby servery neopakovaly všechny najednou.
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 celou současnou tabulku se značkou UserId hráče
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áhodném okamžiku intervalu, aby servery neukládaly všechny najednou
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
-- Pokud hráč právě odešel z tohoto serveru a vrátil se, nejdřív necháme doběhnout poslední uložení
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 -- odešel během načítání: nic se nezměnilo, není co ukládat
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 přečíst a hráče varovat
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í smyčku automatického ukládání a opakované volání nic nedělá
save(session)
end
-- Živá tabulka dat hráče nebo nil, dokud se nenačetla. Měňte ji jen ze serverových skriptů.
function PlayerData.Get(player: Player): Data?
local session = sessions[player]
return if session then session.data else nil
end
-- True, když se data hráče načetla a budou uložena. Kontrolujte před každým prodejem.
function PlayerData.CanSave(player: Player): boolean
local session = sessions[player]
return session ~= nil and session.canSave
end
-- Uloží hned, bez čekání na časovač, pro důležité okamžiky jako nákup.
-- Pozastaví běh a vrátí true, když uložení proš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, kteří přišli před prvním připojením tohoto modulu
end
game:BindToClose(function()
-- Server dává těmto funkcím 30 sekund, proto ukládáme všechny současně
for player in sessions do
task.spawn(endSession, player)
end
-- Pak počkáme na všechna ještě probíhající ukládání, včetně těch začatých v PlayerRemoving
while next(pendingSaves) do
task.wait()
end
end)
return PlayerData
Jakmile je hra venku, neměňte STORE_NAME ani vzor klíče User_. Změna kteréhokoli z nich nasměruje modul na prázdné klíče a každý hráč začne znovu s výchozími hodnotami.
Jak modul chrání data
Výchozí hodnoty a verze schématu
Nový hráč dostane čerstvou kopii DEFAULTS. Musí to být opravdu kopie: kdyby všichni hráči sdíleli jednu tabulku Inventory, předmět přidaný jednomu by se objevil u všech.
Každá uložená tabulka nese SchemaVersion. Přidání pole novou verzi nevyžaduje, protože migrate doplní chybějící pole z výchozích hodnot. Přejmenování nebo přestavba ji vyžaduje: zvyšte SCHEMA_VERSION a přidejte krok, jako v příkladu, který přejmenovává Gold na Coins (v nové hře ho smažte a začněte od 1). Data s vyšší verzí, než má server, pocházejí z novějšího vydání, které se ještě zavádí, a proto se jich starší servery nedotknou.
Neúspěšné načtení se nikdy neukládá
Toto pravidlo chrání před úplným smazáním. Pokud všechny pokusy o načtení selhaly, hráč hraje s výchozími daty, ale canSave je false, takže tyto hodnoty nikdy nepřepíšou jeho skutečný postup. Modul také nastaví atribut DataLoaded na false a krok 3 ho použije, aby to hráči oznámil. Referenční příklad Robloxu zpracovává neúspěšná načtení stejně a navrhuje to místo vyhození; pokud dáváte přednost vyhození, zavolejte player:Kick() se zprávou tam, kde modul vypisuje varování.
Opakování s narůstající pauzou
withRetries obalí každé volání do pcall. Po neúspěchu počká 1, pak 2, pak 4 sekundy, pokaždé plus náhodně až polovinu této doby, a po čtyřech pokusech přestane (ve Studiu po jednom, aby se place bez přístupu k úložišti spustil hned). Náhoda rozloží opakování mnoha serverů po výpadku a omezení drží čekání zhruba do 10 sekund, uvnitř 30 sekund, které server dostává na vypnutí. Protože každé uložení zapisuje celou živou tabulku přes UpdateAsync, opakování, které skončí se zpožděním, nemůže vrátit stará data.
Kdy modul ukládá
| Kdy | Proč |
|---|---|
| Každých 180 sekund, dokud je hráč na serveru | Omezuje ztráty při pádu. První uložení připadne na náhodný okamžik intervalu, aby servery neukládaly všechny najednou. Referenční příklad Robloxu také používá 180 sekund. |
Když hráč odejde (PlayerRemoving) | Běžné závěrečné uložení. Relace se nejdřív smaže, takže automatické ukládání se zastaví. |
Když se server vypíná (game:BindToClose) | Všichni, kdo jsou ještě na serveru, se uloží najednou a funkce počká na každé probíhající uložení. Roblox jí dává 30 sekund. |
Na požádání, přes PlayerData.SaveNow(player) | Po něčem, co se nesmí ztratit, například po nákupu. |
Pokud se hráč vrátí na stejný server, zatímco jeho závěrečné uložení ještě probíhá, nové načtení počká, až uložení skončí, takže nemůže přečíst starou hodnotu.
Krok 2: čtěte a měňte data z jiných skriptů
Všechny serverové skripty, které modul připojí, pracují se stejnými tabulkami:
| Volání | Co dělá |
|---|---|
PlayerData.Get(player) | Živá tabulka dat hráče nebo nil, dokud se nenačetla. Měňte pole přímo, například data.Coins += 10, a další uložení to zachytí. |
PlayerData.Loaded | Spustí se s hráčem, když jsou jeho data připravená, i po neúspěšném načtení. Předává jen hráče, protože tabulka poslaná přes BindableEvent přijde jako kopie. |
PlayerData.CanSave(player) | false, pokud se načtení nepovedlo. Kontrolujte před každým prodejem: nákup, který nejde uložit, zmizí, když hráč odejde. |
PlayerData.SaveNow(player) | Uloží hned a vrátí true, pokud se to povedlo. Pozastaví běh. |
Modul je jediné místo, kde uložená data žijí, a leaderstats jsou jen zobrazení: postavte je jako v návodu k leaderboardu, naplňte z PlayerData.Get(player) v handleru Loaded a při změně hodnoty aktualizujte obojí. Uložené hodnoty nikdy nečtěte zpátky z leaderstats a nikdy nedovolte druhému skriptu ukládat stejný klíč.
Skript, který modul připojil až poté, co hráči přišli, pro ně Loaded zmešká. Připojte handler a pak ještě projděte smyčkou Players:GetPlayers() a zpracujte všechny, pro které už PlayerData.Get(player) vrací tabulku.
Nahrazujete starý skript ukládání, například z návodu k leaderboardu? Jeho hodnoty zůstávají v jeho vlastním úložišti a klíči, takže tento modul začne všechny od výchozích hodnot. Před spuštěním buď nasměrujte STORE_NAME a předponu User_ na ty staré (migrate považuje data bez SchemaVersion za verzi 1 a doplní chybějící pole), nebo staré hodnoty přeneste a starý skript pak smažte.
Klienti tato data nikdy nemění přímo. Tlačítko obchodu spustí RemoteEvent; server zkontroluje CanSave, porovná cenu s Coins hráče, změní tabulku a zavolá SaveNow. Návod ke GUI obchodu takový nákup na straně serveru staví.
Hotový příklad přidání polí je v návodu ke clicker simulátoru: přidává PowerLevel a Rebirths do DEFAULTS a typu Data a pak je mění v tabulce, kterou vrací PlayerData.Get. migrate dá nová pole i hráčům se starými uloženími.
Krok 3: oznamte hráči, že se jeho data nenačetla
Hráč, jehož data se nenačetla, musí vědět, že se tato relace neuloží, aby se znovu připojil, místo aby hrál zbytečně. Tento LocalScript sleduje atribut DataLoaded a ukáže banner, když 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 jednou, po pokusu načíst data tohoto hráče
player:GetAttributeChangedSignal("DataLoaded"):Connect(showWarning)
showWarning()
Krok 4: otestujte ukládání ve Studiu
Dělejte to v testovací kopii se zapnutým přístupem Studia.
- Dejte si něco k uložení. Pod řádek require v
Mainpřidejte:PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end) - Klikněte na Play. Okno Output (v menu Window nebo na kartě Script) ukáže vaše jméno a 100 (při prvním spuštění), bez varování
Could not load. - Klikněte na Stop. Ukončení testu zavře server a modul vás před zavřením uloží.
- Znovu klikněte na Play. Output má ukázat 200, o 100 víc než minule. Pokud znovu ukazuje stejné číslo, uložení neprošlo: přečtěte si varování nad ním.
- Otestujte cestu s chybou. Vypněte přístup Studia a klikněte na Play. Po několika sekundách opakování Output ukáže
Could not load User_...a 100 a objeví se banner z kroku 3. Zastavte test, přístup znovu zapněte a klikněte na Play: Output ukáže 300, vašich uložených 200 plus 100, protože neúspěšná relace vaše data nikdy nepřepsala. - Smažte testovací řádek z
Main.
Proč se data hráčů ztrácejí
Toto jsou běžné způsoby, kterými systém ukládání ztratí postup. Modul v kódu řeší první čtyři řádky a řádek o schématu; ostatní závisí na tom, co a jak ukládáte, a ten poslední potřebuje zámek relace.
| Co se stane | Výsledek | Jak tomu předejít |
|---|---|---|
| Načtení selhalo, a skript přesto ukládá | Výchozí hodnoty přepíšou skutečný postup: úplné smazání | Nikdy neukládat hráče, jehož načtení selhalo |
Ukládání jen v PlayerRemoving | Pád nebo vypnutí serveru uložení vynechá | Automatické ukládání plus BindToClose, který na svá uložení počká |
Chybí pcall nebo opakování | Jeden neúspěšný požadavek zastaví skript nebo ztratí uložení | pcall s několika časově rozloženými opakováními |
| Ukládání při každé změně | Požadavky se řadí do fronty; když je jich ve frontě 30, nové se zahodí | Držet data v paměti a ukládat podle časovače |
| Ukládání toho, co úložiště neumí uložit | Uložení hodí chybu nebo se hodnota vrátí jako nil | Ukládat čísla, řetězce, booleovské hodnoty a tabulky z nich |
| Změna podoby dat bez migrace | Stará uložení se načtou do špatných polí | Verze schématu a krok migrace |
| Dva skripty ukládají stejný klíč | Každé uložení přepíše pole toho druhého | Klíč vlastní jeden modul |
| Dva servery drží stejného hráče | Server se starými daty uloží jako poslední a přepíše nový postup | Zámek relace |
Zámek relace, „lock lost“ a ProfileStore
Hráč je připojený vždy k jednomu serveru, ale závěrečné uložení starého serveru může ještě probíhat, když přijde na nový: pomalé opakování, teleport nebo rychlé znovupřipojení. Pokud nový server načte data jako první, bude mít stará data a vyhraje ten server, který uloží jako poslední. Dokumentace Robloxu uvádí, že ve hrách s výměnou je tato mezera častou příčinou duplikace předmětů.
Zámek relace tuto mezeru uzavře. Když server načte klíč hráče, zapíše ve stejném volání UpdateAsync své ID zámku do metadat klíče. Každý jiný server, který najde neprošlý zámek, jenž sám nenastavil, tento klíč nenačte ani neuloží. Vlastník obnovuje zámek při každém automatickém uložení a v závěrečném uložení ho uvolní; pokud ho přestane obnovovat, zámek vyprší a může si ho vzít jiný server.
Co znamená „lock lost“
V systému se zámkem relace server ztratil zámek, když klíč hráče teď vlastní jiný server, protože zámek vypršel nebo byl převzat. Jeho kopie může být zastaralá, takže musí přestat tohoto hráče ukládat; běžná reakce je vyhodit ho se zprávou, aby se znovu připojil. Pokud jste „lock lost“ viděli jako hráč, je to zpráva vlastního systému ukládání té hry a vysvětlit ji mohou jen její vývojáři.
Potřebujete ho?
Modul z tohoto návodu relace nezamyká. Bez zámku je skutečný nejhorší případ takový: v řídkém souběhu hráč ztratí to, co vydělal na starém serveru po jeho posledním úspěšném uložení. Zámek přidejte, když duplikace nebo ztráta stojí hráče něco skutečného: výměna, developer products, vzácné předměty nebo časté teleporty.
| Možnost | Co to je | Co je dobré vědět |
|---|---|---|
| Modul z tohoto návodu | Načítání, mezipaměť v paměti, opakování, automatické ukládání, ukládání při vypnutí a verze schématu, bez zámku | Dost krátký na to, abyste ho přečetli celý a upravili |
| Příklad Robloxu pro data hráčů a nákupy | Referenční kód od Robloxu se zámkem relace, opakováním v pořadí pro každý klíč a zpracováním účtenek nákupů | Roblox říká, že není prověřený časem v populární hře a nemá se používat tak, jak je, bez rozsáhlého testování |
| ProfileStore | Bezplatný komunitní modul s otevřeným kódem, nástupce ProfileService, postavený kolem zámku relace a automatického ukládání | Není od Robloxu. Převod existující hry na něj vyžaduje migraci už uložených dat |
U každého modulu třetí strany Roblox radí ověřit, kdo ho vlastní, jestli je udržovaný a jak se ke svým datům dostanete bez něj. Stejná dokumentace označuje DataStore2 za zastaralou knihovnu, kterou nové hry používat nemají.
Limity úložišť dat
Toto jsou limity z dokumentace Robloxu k 30. září 2026. Roblox je reviduje, proto si ověřte stránku chybových kódů a limitů (anglicky), než budete počítat s přesným číslem.
| Typ požadavku | Běžná úložiště | Seřazená úložiště |
|---|---|---|
Čtení: GetAsync, čtení v UpdateAsync | 60 + 40 × hráčů | 60 + 40 × hráčů |
Zápis: SetAsync, IncrementAsync, zápis v UpdateAsync | 60 + 40 × hráčů | 30 + 5 × hráčů |
Výpis: ListKeysAsync nebo GetSortedAsync u seřazených úložišť | 5 + 2 × hráčů | 5 + 2 × hráčů |
Mazání: RemoveAsync | 60 + 40 × hráčů | 30 + 5 × hráčů |
Při 20 hráčích může server udělat 860 běžných zápisů za minutu; automatické ukládání tohoto modulu jich spotřebuje asi 7, plus jeden za každého hráče, který odešel. Rozpočet vyčerpá ukládání při každé sebrané minci. Druhý rozpočet platí pro celou hru a sdílí se s Open Cloud: 300 čtení za minutu plus 40 za každého hráče online a 300 zápisů plus 20 za hráče.
| Limit | Hodnota |
|---|---|
| Název úložiště, název klíče, scope | Po 50 znacích |
| Hodnota v jednom klíči | 4 194 304 znaků jako JSON |
| Čtení jednoho klíče ze všech serverů | 25 MB za minutu |
| Zápis do jednoho klíče ze všech serverů | 4 MB za minutu, každý požadavek se zaokrouhlí nahoru na další KB |
| Čekající požadavky | 30 na frontu; nad to požadavky selžou s chybami 301-306 |
| Úložiště pro celou hru | 500 MB plus 1 MB za každého uživatele za celou dobu |
Velikost dat hráče změříte přes #HttpService:JSONEncode(data) a zbývající rozpočet živého serveru zjistíte přes DataStoreService:GetRequestBudgetForRequestType(Enum.DataStoreRequestType.StandardWrite). Volání GetAsync, na která odpověděla 4sekundová mezipaměť, se nepočítají. Režim Run ve Studiu má vlastní, možná nižší limity, proto Roblox na testování limitů požadavků doporučuje Team Create.
Verze a zálohy
Běžná úložiště dat uchovávají historii za vás. První zápis do klíče v každé hodině UTC se uloží jako verze a další zápisy v té hodině se navzájem přepisují. Stará verze vyprší 30 dní poté, co ji nahradil novější zápis; poslední nevyprší nikdy. Seřazená úložiště verze neuchovávají.
Chcete-li vrátit jednoho hráče, otevřete Data Stores Manager (Creations, vaše hra, Configure > Data Stores Manager), vyberte jeho klíč, vyberte dřívější verzi a klikněte na Revert; potřebujete k tomu právo Edit. Dělejte to, když hráč není online, jinak server s jeho relací uloží svou kopii přes vrácenou verzi. Ze serverového skriptu ListVersionsAsync a GetVersionAsync najdou a přečtou starou verzi, kterou pak zapíšete zpět jako současnou hodnotu.
Před publikováním aktualizace, která mění způsob ukládání dat, Roblox doporučuje udělat snímek přes Open Cloud Snapshot Data Stores API (jeden denně na hru). Bez něj chybné uložení ve 3:30 UTC přepíše všechno, co bylo do toho klíče zapsáno od 3:00, protože spadne do stejné hodinové verze.
Časté chyby a řešení
Chyby úložišť dat se objevují v okně Output ve Studiu a modul vypíše varování s textem chyby Robloxu při každém neúspěšném pokusu. Návod k chybám ve skriptech vysvětluje, jak Output vůbec číst.
StudioAccessToApisNotAllowed (chyba 403)
„Can't write to DataStore from Studio because API access is not enabled.“ Publikujte place a pak zapněte Enable Studio Access to API Services v File > Experience Settings > Security, v testovací kopii.
DataStore request was added to queue
Server posílá požadavky rychleji, než rozpočet dovolí, nebo příliš často zapisuje jeden klíč, obvykle kvůli ukládání při každé změně nebo ve smyčce. Když je ve frontě 30 požadavků, nové selžou s chybami 301-306. Držte data v paměti a ukládejte podle časovače.
CantStoreValue (chyba 104), nebo se pole vrátí jako nil
V tabulce je něco, co úložiště neumí uložit, například Instance, Vector3 nebo Color3. Ukládejte místo toho název, ID nebo jednoduchá čísla a objekt při načtení obnovte.
ValueTooLarge (chyba 105)
Jeden klíč uchovává víc než 4 194 304 znaků JSON. Změřte to přes #HttpService:JSONEncode(data), odstraňte, co jde obnovit, nebo data rozdělte do několika stálých klíčů.
Chyby nejsou, ale data se neukládají
Hledejte varování modulu Could not load: po neúspěšném načtení záměrně odmítá ukládat. Jinak se hodnota nejspíš měnila v LocalScriptu, a to se na server nikdy nedostane, nebo stejný klíč ukládá jiný skript.
Data se při každém znovupřipojení vynulují
Klíč se mezi relacemi mění (je složený z player.Name, nebo jste změnili STORE_NAME), načtení selhává a vidíte výchozí hodnoty, nebo modul nikdo nepřipojuje a vůbec neběží. Zkontrolujte Output a to, že Main připojuje PlayerData.
Postavte to s RoCode
Pokud se vám to nechce stavět ručně, RoCode to může udělat přímo ve vašem otevřeném place. Je to nezávislý AI agent, ne od Robloxu, který pracuje přes plugin pro Roblox Studio: píše Luau, který používá DataStoreService jako každý jiný skript, a vytváří skripty ve vašem Exploreru. Sám k vašim úložištím dat nikdy nepřistupuje, ale s pluginem 3.9 nebo novějším může kliknout na Play kvůli krátkému playtestu, kde vaše skripty běží jako v každém testu.
Přidej do mé hry ukládání: ukládej Coins, Level a Inventory v modulu PlayerData s automatickým ukládáním a ukládáním při vypnutí serveru a zobrazuj Coins v leaderstats, které už mám.
- Může vyhledat existující leaderstats a kód DataStore přes Search Scripts a Read Script, aby rozšířil to, co máte, a nepřidával druhý skript ukládání. Ve velkém place uveďte ve zprávě název skriptu nebo složky.
- Vytvoří ModuleScript a Script, který ho připojuje, přes Create Script, nebo změní existující přes Edit Script
- Spustí Check Script pro každý napsaný skript: kontrolu kompilace uvnitř Studia s krátkým seznamem varování, ne kontrolu typů ani testovací běh
- Posílá změny po dávkách a každá dávka je bod pro vrácení (undo) ve Studiu
Studio Access to API Services v testovací kopii budete muset zapnout sami: RoCode toto nastavení měnit nemůže. S pluginem 3.9 nebo novějším jeho krátký playtest čte chyby a s pluginem 3.9.11 nebo novějším může ovládat testovací postavu, aby ověřil, že hra funguje, ale kontroluje jen to, co se sám rozhodl kontrolovat, proto si zahrajte sami a ověřte, že se Coins, Level a Inventory ukládají a načítají. Pokud uložení ve vašem testu neprošlo, Check Output umí přečíst řádky Server z playtestu, který jste spustili. Ukládání se obvykle přidává, když už hlavní herní smyčka funguje; tvorba hry v Robloxu s AI po jednom systému ukazuje toto pořadí. Jak se RoCode připojuje ke Studiu.
Časté otázky
Jak zapnout DataStore v Roblox Studiu?
Publikujte place, otevřete File > Experience Settings > Security, zapněte Enable Studio Access to API Services a klikněte na Save. Dělejte to v samostatné testovací hře, protože Studio pak používá stejná úložiště dat jako živé servery této hry.
Ukládá Roblox data hráče automaticky?
Ne. Nic o hráči se po relaci neuloží, pokud to serverový skript neuloží přes DataStoreService, a leaderstats také ne.
Co vybrat: ProfileStore, nebo přímo DataStoreService?
ProfileStore je také postavený na úložištích dat, takže otázka je, jestli chcete, aby vám zámek relace někdo napsal a udržoval. Pro výměnu, placené předměty nebo časté teleporty se zámek vyplatí, z knihovny nebo z referenčního příkladu Robloxu. U menší hry je modul jako tento jednodušší číst i měnit.
Jak vynulovat nebo smazat data hráče?
V Data Stores Manager najděte klíč a vyberte Mark for Deletion, což lze během čekací doby vrátit, nebo zavolejte RemoveAsync pro klíč ze serverového skriptu. Dělejte to, když hráč není online, jinak další uložení jeho serveru data zapíše zpět. V testovací kopii změna STORE_NAME začne všechny od nuly; v živé hře to nikdy nedělejte.
Zdroje a další čtení
- Roblox Creator Docs: Data stores (anglicky). přístup Studia, GetAsync, SetAsync, UpdateAsync, set a update
- Roblox Creator Docs: Best practices for data stores (anglicky). jeden klíč na hráče, data v paměti, opakování s narůstající pauzou, moduly třetích stran
- Roblox Creator Docs: Data store error codes and limits (anglicky). chybové kódy, limity požadavků serveru a hry, limity velikosti, propustnosti a úložiště
- Roblox Creator Docs: Versioning, listing and caching (anglicky). hodinové verze, snímky, 4sekundová mezipaměť, co lze ukládat
- Roblox Creator Docs: Implement player data and purchasing systems (anglicky). referenční příklad, zámek relace, neúspěšná načtení, automatické ukládání jednou za 180 sekund
- Roblox Creator Docs: Data Stores Manager (anglicky). prohlížení klíčů, vracení verzí, mazání dat
- Roblox Engine API: DataModel:BindToClose (anglicky). 30 sekund na vypnutí
Jak byl kód ověřen: každý skript na této stránce prochází přísnou kontrolou typů Luau s definicemi Roblox API (luau-lsp, 20. listopadu 2026). Kontrola typů zachytí chyby v názvech API a špatné typy, ale ne chyby v herní logice, proto vše otestujte ve Studiu před publikováním.