Tutorial · Datele jucătorului

Cum salvezi datele jucătorului în Roblox Studio prin DataStore

Roblox nu ține minte nimic despre un jucător între sesiuni dacă un script de server nu a salvat asta. În acest ghid construiești un modul PlayerData care încarcă, ține în memorie și salvează datele fiecărui jucător prin DataStoreService, apoi treci prin verificare, limite și felul în care se pierd datele salvate.

Actualizat 20 noiembrie 202618 min de cititAutor:

Pe scurt

Folosește DataStoreService dintr-un Script de server: încarcă datele jucătorului prin GetAsync când intră, ține-le într-un tabel cât joacă și salvează-le prin UpdateAsync după un cronometru, la ieșire (PlayerRemoving) și la oprirea serverului (game:BindToClose). Învelește fiecare apel în pcall și reîncearcă de câteva ori apelurile eșuate.

  • Ca să testezi în Studio, publică place-ul și activează File > Experience Settings > Security > Enable Studio Access to API Services într-un joc de test separat: Studio folosește aceleași date ca serverele live.
  • Dacă datele unui jucător nu s-au încărcat, nu salva niciodată acel jucător. Salvarea valorilor implicite îi șterge progresul real.
  • Ține un singur tabel pe jucător sub o singură cheie, de exemplu User_12345, și salvează după un cronometru, nu la fiecare schimbare.
  • Pentru schimburi de obiecte sau obiecte plătite adaugă blocarea sesiunii, ca două servere să nu poată salva același jucător.
Pe această pagină
  1. Accesul Studio
  2. Cum funcționează DataStore
  3. GetAsync și UpdateAsync
  4. 1. Modulul PlayerData
  5. Cum e construit modulul
  6. 2. Lucrul cu datele
  7. 3. Avertisment
  8. 4. Verificare în Studio
  9. De ce se pierd datele
  10. Blocarea sesiunii
  11. Limite
  12. Versiuni și copii
  13. Common errors
  14. With RoCode
  15. Întrebări frecvente
  16. Surse și lecturi suplimentare

Înainte să începi: activează accesul Studio într-o copie de test

Un joc pornit în Studio nu poate accesa depozitele de date până nu îi permiți. Permisiunea are o capcană despre care avertizează documentația Roblox: Studio citește și scrie atunci aceleași depozite de date ca jocul live, așa că un test care îți resetează monedele în Studio le resetează și în jocul live, iar o greșeală în codul de test poate strica cheile jucătorilor reali.

  1. Fă o copie de test. Salvează place-ul într-un fișier, deschide copia, alege File > Publish to Roblox As și apasă Create new game. Nu o adăuga ca place în jocul live: toate place-urile unui joc împart aceleași depozite de date.
  2. În copia de test deschide File > Experience Settings și mergi la Security.
  3. Activează Enable Studio Access to API Services și apasă Save.

Apelurile către depozitele de date funcționează doar în Script-uri de server; un LocalScript care încearcă primește o eroare, așa că clienții nu pot scrie datele salvate. Când un buton trebuie să le schimbe, clientul îi cere serverului printr-un RemoteEvent, iar serverul decide (vezi ghidul despre RemoteEvents, în engleză).

Cum păstrează depozitele de date datele jucătorilor

IlustrațieVerificarea de la pasul 4 al ghidului, accelerată: Play, Stop salvează sesiunea în depozitul de date, un nou Play o încarcă, așa că Output arată 200.

Un depozit de date (data store) e un set numit de chei și valori pe serverele Roblox, comun tuturor serverelor și tuturor place-urilor jocului tău. DataStoreService:GetDataStore("PlayerData") returnează un astfel de depozit.

Recomandările Roblox se reduc la regula un depozit pentru datele jucătorilor, o cheie pe jucător, un tabel în fiecare cheie. Formează cheia din UserId-ul jucătorului, de exemplu User_12345, și niciodată din numele pe care și-l poate schimba. Un tipar constant User_{UserId} îi permite și procesării automate Roblox pentru dreptul de a fi uitat să găsească datele jucătorului, dacă o configurezi.

Ce poți salva într-un depozit de date
TipSe salvează?Observații
Numere, șiruri, valori booleene, buffereDaȘirurile trebuie să fie UTF-8 corect. Nu păstra inf sau nan.
TabeleDaDacă tot ce e înăuntru se poate salva și el. Un tabel ale cărui chei numerice nu încep de la 1 (deci lungimea lui e 0) revine cu acele chei ca șiruri.
Instance, Vector3, CFrame, Color3NuSalvarea dă eroare sau scrie nil. Salvează numele obiectului sau poziția ca trei numere.

Fiecare cerere e un apel web care poate eșua, durează și consumă dintr-un buget pe minut. De aceea sistemele de salvare sigure citesc datele o dată la intrarea jucătorului, le țin într-un tabel pe server cât joacă și le scriu înapoi din când în când.

GetAsync, SetAsync sau UpdateAsync: ce să alegi

Metodele principale ale unui depozit de date
MetodăCe facePentru ce
GetAsync(key)Citește valoarea. Rezultatul se păstrează în cache pe acest server 4 secunde.Încărcarea datelor jucătorului
SetAsync(key, value)Suprascrie valoarea fără s-o citească. O singură scriere.O cheie nouă sau o valoare care nu depinde de cea veche
UpdateAsync(key, callback)Citește ultima valoare, o transmite funcției tale și scrie ce returnează ea. O citire și o scriere.Salvarea datelor jucătorului și orice cheie pe care o pot scrie mai multe servere
IncrementAsync(key, delta)Adaugă un număr întreg la un întreg salvat.Contoare
RemoveAsync(key)Șterge cheia și returnează valoarea veche. Versiunile anterioare pot fi în continuare listate și citite.Ștergerea datelor jucătorului

SetAsync scrie orbește: dacă două servere salvează aceeași cheie aproape simultan, câștigă ultima scriere, orice ar conține. UpdateAsync citește întâi valoarea curentă, iar dacă între timp scrie alt server, Roblox rulează din nou funcția ta cu valoarea nouă. Roblox îl recomandă de fiecare dată când scrierea depinde de valoarea curentă sau cheia poate fi scrisă de mai multe servere, iar exact așa stau lucrurile cu datele jucătorului. Funcția are trei reguli:

  • Nu are voie să cedeze execuția (yield): fără task.wait() și fără alte apeluri de depozit în interior.
  • Poate rula de mai multe ori, așa că trebuie doar să calculeze noua valoare și să nu dea niciodată obiecte și să nu declanșeze evenimente.
  • Returnarea lui nil anulează scrierea. Modulul folosește asta ca să nu suprascrie date salvate de o versiune mai nouă a jocului.

Pasul 1: creează modulul PlayerData

Acest ModuleScript e singurul cod care comunică cu depozitul de date. Încarcă datele jucătorului la intrare, le ține în memorie, le salvează la fiecare 180 de secunde, la ieșire și la oprirea serverului și refuză să-i salveze pe cei ale căror date nu s-au încărcat.

  1. În Explorer treci cu mouse-ul peste ServerScriptService, apasă + și inserează un ModuleScript. Redenumește-l în PlayerData și înlocuiește-i conținutul cu codul de mai jos.
  2. Un ModuleScript rulează doar când îl include (require) un script. Inserează în ServerScriptService un Script numit Main cu acest rând: local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Alte scripturi de server îl includ la fel.
  3. Schimbă DEFAULTS și tipul Data pentru jocul tău, păstrând fiecare câmp ca număr, șir, valoare booleană sau tabel.
Explorer-ul după pașii 1-3
ServerScriptService
    PlayerData ModuleScript new
    Main Script new
StarterPlayer
    StarterPlayerScripts
        DataWarning LocalScript new
ModuleScript în ServerScriptService cu numele PlayerData
-- PlayerData: încarcă datele jucătorului la intrare, le ține în memorie
-- și le salvează după un cronometru, la ieșire și la oprirea serverului.
-- Alte scripturi de server le citesc și le schimbă prin 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 -- crește-l când se schimbă forma datelor și adaugă un pas în migrate()
local AUTOSAVE_SECONDS = 180
-- În Studio un apel eșuat renunță imediat, așa că un test fără acces la depozit merge repede
local MAX_ATTEMPTS = if RunService:IsStudio() then 1 else 4
local FIRST_RETRY_SECONDS = 1 -- se dublează după fiecare eșec: 1, 2, 4

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

-- Cu ce începe un jucător complet nou
local DEFAULTS: { [string]: any } = {
	Coins = 0,
	Level = 1,
	Inventory = {},
}

type Session = {
	key: string,
	userId: number,
	data: Data,
	canSave: boolean, -- false dacă încărcarea a eșuat: datele implicite nu trebuie să înlocuiască progresul real
}

-- Se apelează în fiecare pcall de mai jos, așa că un place încă nepublicat
-- (fără acces la depozit) tot încarcă jucătorii cu datele implicite
local function store(): DataStore
	return DataStoreService:GetDataStore(STORE_NAME)
end
local sessions: { [Player]: Session } = {}
local pendingSaves: { [string]: number } = {} -- salvări care încă rulează, după chei
local loadedEvent = Instance.new("BindableEvent")

local PlayerData = {}

-- Se declanșează cu jucătorul când datele lui sunt gata. Tabelul îl iei prin PlayerData.Get(player):
-- un tabel trimis printr-un BindableEvent ajunge ca o copie, iar schimbarea lui nu schimbă nimic.
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) -- o copie nouă, ca jucătorii să nu împartă niciodată același tabel Inventory
	data.SchemaVersion = SCHEMA_VERSION
	return data
end

-- Aduce datele salvate la schema curentă. Returnează nil dacă nu pot fi folosite în siguranță.
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 -- salvate de o versiune mai nouă a jocului: nu le încărca și nu le suprascrie aici
	end

	-- Câte un pas pentru fiecare schimbare de schemă, de la cele vechi la cele noi
	if version < 2 then
		-- Exemplu: în versiunea 1 moneda se numea Gold. O copiem doar dacă Coins lipsește,
		-- ca datele vechi care au deja Coins, dar nu au SchemaVersion, să-și păstreze valoarea.
		if saved.Coins == nil then
			saved.Coins = saved.Gold
		end
		saved.Gold = nil
	end

	-- Adăugăm câmpurile apărute după ultima salvare a jucătorului și înlocuim valorile de tip greșit
	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

-- Rulează un apel de depozit în pcall. La eșec așteaptă și încearcă din nou, dublând de fiecare dată
-- așteptarea și adăugând puțină întâmplare, ca serverele să nu reîncerce toate deodată.
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 -- returnarea lui nil anulează scrierea
			end
			-- Scriem tot tabelul curent, marcat cu UserId-ul jucătorului
			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()
		-- Începem într-un moment aleatoriu al intervalului, ca serverele să nu salveze toate deodată
		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

	-- Dacă jucătorul tocmai a ieșit de pe acest server și s-a întors, lăsăm întâi ultima salvare să se termine
	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 -- a ieșit în timpul încărcării: nu s-a schimbat nimic, nu e nimic de salvat
	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) -- un GUI poate citi asta și îl poate avertiza pe jucător
	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 -- oprește bucla de autosalvare, iar un al doilea apel nu face nimic
	save(session)
end

-- Tabelul live de date al jucătorului sau nil până se încarcă. Schimbă-l doar din scripturi de server.
function PlayerData.Get(player: Player): Data?
	local session = sessions[player]
	return if session then session.data else nil
end

-- True când datele jucătorului s-au încărcat și vor fi salvate. Verifică înainte de orice vânzare.
function PlayerData.CanSave(player: Player): boolean
	local session = sessions[player]
	return session ~= nil and session.canSave
end

-- Salvează acum, fără să aștepte cronometrul, pentru momente importante precum o cumpărare.
-- Cedează execuția și returnează true când salvarea a reușit.
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) -- jucătorii intrați înainte de primul require al acestui modul
end

game:BindToClose(function()
	-- Serverul le dă acestor funcții 30 de secunde, așa că îi salvăm pe toți simultan
	for player in sessions do
		task.spawn(endSession, player)
	end
	-- Apoi așteptăm toate salvările încă în curs, inclusiv cele pornite în PlayerRemoving
	while next(pendingSaves) do
		task.wait()
	end
end)

return PlayerData

După ce jocul a fost lansat, nu schimba STORE_NAME și tiparul de cheie User_. Schimbarea oricăruia dintre ele îndreaptă modulul spre chei goale, iar fiecare jucător o ia de la capăt cu valorile implicite.

Cum îți protejează modulul datele

Valori implicite și versiunea schemei

Un jucător nou primește o copie proaspătă a DEFAULTS. Trebuie să fie chiar o copie: dacă toți jucătorii ar împărți un singur tabel Inventory, un obiect adăugat unuia ar apărea la toți.

Fiecare tabel salvat poartă un SchemaVersion. Adăugarea unui câmp nu cere o versiune nouă, pentru că migrate completează câmpurile lipsă din valorile implicite. O redenumire sau o restructurare cere: crește SCHEMA_VERSION și adaugă un pas, ca în exemplul care redenumește Gold în Coins (într-un joc nou șterge-l și începe de la 1). Datele cu o versiune mai mare decât a serverului vin de la o versiune mai nouă care încă se lansează, așa că serverele vechi nu le ating.

O încărcare eșuată nu se salvează niciodată

Regula asta te apără de ștergerea completă. Dacă toate încercările de încărcare au eșuat, jucătorul joacă pe datele implicite, dar canSave e false, așa că aceste valori nu îi vor suprascrie niciodată progresul real. Modulul setează și atributul DataLoaded la false, iar pasul 3 îl folosește ca să-l anunțe pe jucător. Exemplul de referință al Roblox tratează încărcările eșuate la fel și propune asta în loc de kick; dacă preferi kick-ul, apelează player:Kick() cu un mesaj acolo unde modulul afișează avertismentul.

Reîncercări cu pauză crescătoare

withRetries învelește fiecare apel în pcall. După un eșec așteaptă 1, apoi 2, apoi 4 secunde, de fiecare dată plus până la jumătate din acest timp, la întâmplare, și se oprește după patru încercări (în Studio după una, ca un place fără acces la depozit să pornească imediat). Întâmplarea împrăștie reîncercările multor servere după o pană, iar limita ține așteptarea în jur de 10 secunde, în cele 30 de secunde pe care serverul le primește la oprire. Pentru că fiecare salvare scrie tot tabelul live prin UpdateAsync, o reîncercare care se termină cu întârziere nu poate readuce date vechi.

Când salvează modulul

CândDe ce
La fiecare 180 de secunde, cât jucătorul e pe serverLimitează pierderile la o cădere. Prima salvare cade într-un moment aleatoriu al intervalului, ca serverele să nu salveze toate deodată. Exemplul de referință al Roblox folosește tot 180 de secunde.
Când jucătorul iese (PlayerRemoving)Salvarea finală obișnuită. Sesiunea se șterge întâi, așa că autosalvarea se oprește.
Când serverul se oprește (game:BindToClose)Toți cei rămași pe server sunt salvați deodată, iar funcția așteaptă fiecare salvare în curs. Roblox îi dă 30 de secunde.
La cerere, prin PlayerData.SaveNow(player)După ceva ce nu poate fi pierdut, de exemplu o cumpărare.

Dacă jucătorul intră din nou pe același server cât salvarea lui finală încă rulează, noua încărcare așteaptă sfârșitul acelei salvări, așa că nu poate citi valoarea veche.

Pasul 2: citește și schimbă datele din alte scripturi

Toate scripturile de server care includ modulul lucrează cu aceleași tabele:

ApelCe face
PlayerData.Get(player)Tabelul live de date al jucătorului sau nil până se încarcă. Schimbă câmpurile direct, de exemplu data.Coins += 10, iar următoarea salvare le preia.
PlayerData.LoadedSe declanșează cu jucătorul când datele lui sunt gata, inclusiv după o încărcare eșuată. Transmite doar jucătorul, pentru că un tabel trimis printr-un BindableEvent ajunge ca o copie.
PlayerData.CanSave(player)false dacă încărcarea a eșuat. Verifică înainte de orice vânzare: o cumpărare care nu poate fi salvată se pierde când jucătorul iese.
PlayerData.SaveNow(player)Salvează imediat și returnează true dacă a reușit. Cedează execuția.

Modulul e singurul loc în care trăiesc datele salvate, iar leaderstats e doar o afișare: construiește-l ca în ghidul despre clasament, completează-l din PlayerData.Get(player) în handler-ul Loaded și actualizează-le pe amândouă când se schimbă o valoare. Nu citi niciodată valorile salvate înapoi din leaderstats și nu lăsa niciodată un al doilea script să salveze aceeași cheie.

Un script care a inclus modulul după ce jucătorii au intrat ratează pentru ei Loaded. Conectează handler-ul, apoi parcurge și o buclă prin Players:GetPlayers() și tratează-i pe toți cei pentru care PlayerData.Get(player) returnează deja un tabel.

Înlocuiești un script de salvare vechi, de exemplu cel din ghidul despre clasament? Valorile lui rămân în propriul depozit și propria cheie, așa că acest modul îi va porni pe toți de la valorile implicite. Înainte de lansare fie îndreaptă STORE_NAME și prefixul User_ spre cele vechi (migrate consideră datele fără SchemaVersion ca versiunea 1 și completează câmpurile lipsă), fie mută valorile vechi, apoi șterge scriptul vechi.

Clienții nu schimbă niciodată aceste date direct. Un buton de magazin declanșează un RemoteEvent; serverul verifică CanSave, compară prețul cu Coins-ul jucătorului, schimbă tabelul și apelează SaveNow. Ghidul despre GUI-ul de magazin construiește o astfel de cumpărare pe partea de server.

Un exemplu gata făcut de adăugare a câmpurilor e în ghidul despre clicker simulator: adaugă PowerLevel și Rebirths în DEFAULTS și în tipul Data, apoi le schimbă în tabelul returnat de PlayerData.Get. migrate le dă câmpurile noi jucătorilor cu salvări vechi.

Pasul 3: anunță jucătorul că datele lui nu s-au încărcat

Un jucător ale cărui date nu s-au încărcat trebuie să știe că această sesiune nu se va salva, ca să reintre în loc să joace degeaba. Acest LocalScript urmărește atributul DataLoaded și arată un banner când e false.

LocalScript în StarterPlayerScripts cu numele DataWarning
local Players = game:GetService("Players")

local player = Players.LocalPlayer
local shown = false

local function showWarning()
	if shown or player:GetAttribute("DataLoaded") ~= false then
		return
	end
	shown = true

	local gui = Instance.new("ScreenGui")
	gui.Name = "DataWarning"
	gui.ResetOnSpawn = false

	local label = Instance.new("TextLabel")
	label.AnchorPoint = Vector2.new(0.5, 0)
	label.Position = UDim2.new(0.5, 0, 0, 12)
	label.Size = UDim2.new(0.8, 0, 0, 48)
	label.BackgroundColor3 = Color3.fromRGB(110, 28, 28)
	label.TextColor3 = Color3.new(1, 1, 1)
	label.TextScaled = true
	label.Text = "Your saved progress could not be loaded. Nothing you do in this server will be saved, so rejoin later."
	label.Parent = gui

	gui.Parent = player:WaitForChild("PlayerGui")
end

-- Serverul setează DataLoaded o dată, după încercarea de a încărca datele acestui jucător
player:GetAttributeChangedSignal("DataLoaded"):Connect(showWarning)
showWarning()

Pasul 4: verifică salvarea în Studio

Fă asta în copia de test, cu accesul Studio activat.

  1. Dă-ți ceva de salvat. Sub rândul cu require din Main adaugă: PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end)
  2. Apasă Play. Fereastra Output (din meniul Window sau din fila Script) îți arată numele și 100 (la prima pornire), fără avertismentul Could not load.
  3. Apasă Stop. Terminarea testului închide serverul, iar modulul te salvează înainte de închidere.
  4. Apasă din nou Play. Output trebuie să arate 200, cu 100 mai mult decât data trecută. Dacă arată din nou același număr, salvarea nu a reușit: citește avertismentele de deasupra.
  5. Verifică drumul cu eroare. Dezactivează accesul Studio și apasă Play. După câteva secunde de reîncercări, Output arată Could not load User_... și 100, iar bannerul de la pasul 3 apare. Oprește testul, reactivează accesul și apasă Play: Output arată 300, cele 200 salvate plus 100, pentru că sesiunea eșuată nu ți-a suprascris niciodată datele.
  6. Șterge rândul de test din Main.

De ce se pierd datele jucătorilor

Iată felurile obișnuite în care un sistem de salvare pierde progresul. Modulul acoperă în cod primele patru rânduri și rândul despre schemă; celelalte depind de ce și cum păstrezi, iar pentru ultimul e nevoie de blocarea sesiunii.

Ce se întâmplăRezultatCum previi
Încărcarea a eșuat, dar scriptul salvează oricumValorile implicite șterg progresul real: ștergere completăNu salva niciodată un jucător a cărui încărcare a eșuat
Salvare doar în PlayerRemovingO cădere sau oprire a serverului ratează salvareaAutosalvare plus BindToClose, care își așteaptă salvările
Fără pcall sau fără reîncercareO singură cerere eșuată oprește scriptul sau pierde salvareapcall cu câteva reîncercări distanțate în timp
Salvare la fiecare schimbareCererile intră la coadă; când sunt 30 la coadă, cele noi sunt aruncateȚine datele în memorie și salvează după un cronometru
Salvarea a ceva ce depozitul nu poate păstraSalvarea dă eroare sau valoarea revine nilSalvează numere, șiruri, valori booleene și tabele din ele
Schimbarea formei datelor fără migrareSalvările vechi se încarcă în câmpurile greșiteVersiune de schemă și un pas de migrare
Două scripturi salvează aceeași cheieFiecare salvare șterge câmpurile celuilaltCheia e deținută de un singur modul
Două servere țin același jucătorServerul cu date vechi salvează ultimul și șterge progresul nouBlocarea sesiunii

Blocarea sesiunii, „lock lost” și ProfileStore

Un jucător e conectat la un singur server odată, dar salvarea finală a serverului vechi poate încă rula când intră pe unul nou: o reîncercare lentă, un teleport sau o reintrare rapidă. Dacă noul server încarcă datele primul, va avea date vechi, iar câștigă serverul care salvează ultimul. Documentația Roblox notează că, în jocurile cu schimburi, acest interval e o cauză frecventă de duplicare a obiectelor.

Blocarea sesiunii închide acest interval. Când un server încarcă cheia unui jucător, scrie în același apel UpdateAsync ID-ul lui de blocare în metadatele cheii. Orice alt server care găsește o blocare neexpirată, pusă de altcineva, nu va încărca și nu va salva acea cheie. Proprietarul reînnoiește blocarea la fiecare autosalvare și o scoate la salvarea finală; dacă nu o mai reînnoiește, blocarea expiră și o poate prelua alt server.

Ce înseamnă „lock lost”

Într-un sistem cu blocarea sesiunii, un server a pierdut blocarea când cheia jucătorului e acum deținută de alt server, pentru că blocarea a expirat sau a fost preluată. Copia lui poate fi învechită, așa că trebuie să nu mai salveze acel jucător; reacția obișnuită: îi dai kick cu un mesaj, ca să se reconecteze. Dacă ai văzut „lock lost” ca jucător, e un mesaj al sistemului de salvare propriu acelui joc și doar dezvoltatorii lui îl pot explica.

Ai nevoie de ea?

Modulul din acest ghid nu blochează sesiuni. Fără blocare, cel mai rău caz real e acesta: într-o cursă rară, jucătorul pierde ce a câștigat pe serverul vechi după ultima lui salvare reușită. Adaugă blocarea când duplicarea sau pierderea îi costă pe jucători ceva real: schimburi, developer products, obiecte rare sau teleporturi dese.

VariantăCe esteCe e bine de știut
Modulul din acest ghidÎncărcare, cache în memorie, reîncercări, autosalvare, salvare la oprire și versiuni de schemă, fără blocareDestul de scurt cât să-l citești în întregime și să-l schimbi
Exemplul Roblox pentru datele jucătorilor și cumpărăturiCod de referință de la Roblox cu blocarea sesiunii, reîncercări în ordine pentru fiecare cheie și tratarea chitanțelor de cumpărareRoblox spune că nu e testat în timp într-un joc popular și nu trebuie folosit așa cum e fără testare extinsă
ProfileStoreUn modul gratuit al comunității, cu cod deschis, succesorul ProfileService, construit în jurul blocării sesiunii și autosalvăriiNu e de la Roblox. Mutarea unui joc existent pe el cere migrarea datelor deja salvate

Pentru orice modul terț, Roblox recomandă să verifici cine îl deține, dacă e întreținut și cum ajungi la datele tale fără el. Aceeași documentație numește DataStore2 o bibliotecă învechită pe care jocurile noi nu ar trebui s-o folosească.

Limitele depozitelor de date

Acestea sunt limitele din documentația Roblox la 30 septembrie 2026. Roblox le revizuiește, așa că verifică pagina cu coduri de eroare și limite (în engleză) înainte să te bazezi pe un număr exact.

Limitele implicite de cereri pentru fiecare server, pe minut
Tip de cerereDepozite obișnuiteDepozite ordonate
Citire: GetAsync, citirea din UpdateAsync60 + 40 × jucători60 + 40 × jucători
Scriere: SetAsync, IncrementAsync, scrierea din UpdateAsync60 + 40 × jucători30 + 5 × jucători
Listare: ListKeysAsync sau GetSortedAsync pentru depozitele ordonate5 + 2 × jucători5 + 2 × jucători
Ștergere: RemoveAsync60 + 40 × jucători30 + 5 × jucători

La 20 de jucători un server poate face 860 de scrieri obișnuite pe minut; autosalvarea acestui modul consumă cam 7 dintre ele, plus una pentru fiecare jucător care iese. Bugetul îl epuizează salvarea la fiecare monedă ridicată. Un al doilea buget se aplică întregului joc și e împărțit cu Open Cloud: 300 de citiri pe minut plus 40 pentru fiecare jucător online și 300 de scrieri plus 20 pe jucător.

Limite de mărime și de debit
LimităValoare
Numele depozitului, numele cheii, scopeCâte 50 de caractere
Valoarea dintr-o cheie4 194 304 caractere ca JSON
Citirea unei chei de pe toate serverele25 MB pe minut
Scrierea într-o cheie de pe toate serverele4 MB pe minut, fiecare cerere se rotunjește în sus la următorul KB
Cereri în așteptare30 pe coadă; peste asta cererile eșuează cu erorile 301-306
Stocarea pentru tot jocul500 MB plus 1 MB pentru fiecare utilizator din toate timpurile

Mărimea datelor jucătorului o măsori prin #HttpService:JSONEncode(data), iar bugetul rămas al unui server live îl vezi prin DataStoreService:GetRequestBudgetForRequestType(Enum.DataStoreRequestType.StandardWrite). Apelurile GetAsync la care a răspuns cache-ul de 4 secunde nu se numără. Modul Run din Studio are limite proprii, posibil mai mici, așa că pentru verificarea limitelor de cereri Roblox recomandă Team Create.

Versiuni și copii de rezervă

Depozitele de date obișnuite păstrează istoria pentru tine. Prima scriere într-o cheie în fiecare oră UTC se salvează ca versiune, iar scrierile următoare din acea oră se suprascriu una pe alta. O versiune veche expiră la 30 de zile după ce a fost înlocuită de o scriere mai nouă; ultima nu expiră niciodată. Depozitele ordonate nu păstrează versiuni.

Ca să readuci un singur jucător la o stare anterioară, deschide Data Stores Manager (Creations, jocul tău, Configure > Data Stores Manager), alege cheia lui, alege o versiune mai veche și apasă Revert; pentru asta îți trebuie dreptul Edit. Fă asta cât jucătorul nu e online, altfel serverul cu sesiunea lui își salvează copia peste revenire. Dintr-un script de server, ListVersionsAsync și GetVersionAsync găsesc și citesc o versiune veche, pe care apoi o scrii înapoi ca valoare curentă.

Înainte să publici un update care schimbă felul în care se salvează datele, Roblox recomandă să faci un snapshot prin Open Cloud Snapshot Data Stores API (unul pe zi pe joc). Fără el, o salvare greșită la 3:30 UTC șterge tot ce s-a scris în acea cheie de la 3:00, pentru că ajunge în aceeași versiune orară.

Erori frecvente și soluții

Erorile depozitelor de date apar în fereastra Output din Studio, iar modulul afișează un avertisment cu textul erorii Roblox la fiecare încercare eșuată. Ghidul despre erorile din scripturi explică cum citești Output în general.

StudioAccessToApisNotAllowed (eroarea 403)

„Can't write to DataStore from Studio because API access is not enabled.” Publică place-ul, apoi activează Enable Studio Access to API Services în File > Experience Settings > Security, în copia de test.

DataStore request was added to queue

Serverul trimite cereri mai repede decât permite bugetul sau scrie prea des aceeași cheie, de obicei din cauza salvării la fiecare schimbare sau într-o buclă. Când sunt 30 de cereri la coadă, cele noi eșuează cu erorile 301-306. Ține datele în memorie și salvează după un cronometru.

CantStoreValue (eroarea 104) sau un câmp revine nil

Tabelul conține ceva ce depozitul nu poate salva, de exemplu un Instance, Vector3 sau Color3. Salvează în schimb un nume, un ID sau numere simple și refă obiectul la încărcare.

ValueTooLarge (eroarea 105)

O cheie păstrează peste 4 194 304 caractere JSON. Măsoară prin #HttpService:JSONEncode(data), scoate ce se poate reface sau împarte datele în mai multe chei constante.

Nu sunt erori, dar datele nu se salvează

Caută avertismentul modulului Could not load: după o încărcare eșuată refuză intenționat să salveze. Altfel, valoarea s-a schimbat cel mai probabil într-un LocalScript, iar asta nu ajunge niciodată la server, sau aceeași cheie e salvată de alt script.

Datele se resetează la fiecare reintrare

Cheia se schimbă între sesiuni (e formată din player.Name sau ai schimbat STORE_NAME), încărcarea eșuează și vezi valorile implicite sau nimeni nu include modulul și nu rulează deloc. Verifică Output și faptul că Main include PlayerData.

Construiește asta cu RoCode

Dacă nu ai chef să construiești asta manual, RoCode o poate face direct în place-ul pe care îl ai deschis. E un agent AI independent, nu de la Roblox, care lucrează printr-un plugin pentru Roblox Studio: scrie Luau care folosește DataStoreService ca orice script și creează scripturile în Explorer-ul tău. Nu accesează niciodată singur depozitele tale de date, dar cu pluginul 3.9 sau mai nou poate apăsa Play pentru un playtest scurt, în care scripturile tale rulează ca în orice test.

Tu scrii

Adaugă salvarea în jocul meu: păstrează Coins, Level și Inventory într-un modul PlayerData cu autosalvare și salvare la oprirea serverului și arată Coins în leaderstats-ul pe care îl am deja.

RoCode face
  • Poate căuta leaderstats-ul existent și codul DataStore prin Search Scripts și Read Script, ca să extindă ce ai deja în loc să adauge un al doilea script de salvare. Într-un place mare numește scriptul sau folderul în mesaj.
  • Creează ModuleScript-ul și Script-ul care îl include prin Create Script sau le modifică pe cele existente prin Edit Script
  • Rulează Check Script pentru fiecare script scris: o verificare de compilare în Studio cu o listă scurtă de avertismente, nu o verificare de tipuri și nici o rulare de test
  • Trimite modificările în loturi, iar fiecare lot e un punct de anulare (undo) în Studio

Activarea Studio Access to API Services în copia de test tot tu trebuie s-o faci: RoCode nu poate schimba această setare. Cu pluginul 3.9 sau mai nou, playtestul lui scurt citește erorile, iar cu pluginul 3.9.11 sau mai nou poate controla un personaj de test ca să verifice că jocul funcționează, dar verifică doar ce a hotărât el să verifice, așa că joacă singur și asigură-te că Coins, Level și Inventory se salvează și se încarcă. Dacă salvarea nu a reușit în testul tău, Check Output poate citi rândurile Server din playtestul pornit de tine. Salvarea se adaugă de obicei când bucla principală de joc merge deja; crearea unui joc Roblox cu AI, câte un sistem odată arată această ordine. Cum se conectează RoCode la Studio.

Întrebări frecvente

Cum activezi DataStore în Roblox Studio?

Publică place-ul, deschide File > Experience Settings > Security, activează Enable Studio Access to API Services și apasă Save. Fă asta într-un joc de test separat, pentru că Studio folosește atunci aceleași depozite de date ca serverele live ale acelui joc.

Salvează Roblox automat datele jucătorului?

Nu. Nimic despre un jucător nu se păstrează după sesiune dacă un script de server nu salvează asta prin DataStoreService, nici leaderstats-ul.

Ce să aleg: ProfileStore sau DataStoreService direct?

Și ProfileStore e construit pe depozitele de date, așa că întrebarea e dacă vrei ca blocarea sesiunii să fie scrisă și întreținută de altcineva. Pentru schimburi, obiecte plătite sau teleporturi dese, blocarea merită, dintr-o bibliotecă sau din exemplul de referință al Roblox. Pentru un joc mai mic, un modul ca acesta e mai ușor de citit și de schimbat.

Cum resetez sau șterg datele unui jucător?

În Data Stores Manager găsește cheia și alege Mark for Deletion, care se poate anula în perioada de așteptare, sau apelează RemoveAsync pentru cheie dintr-un script de server. Fă asta cât jucătorul nu e online, altfel următoarea salvare a serverului lui scrie datele înapoi. În copia de test, schimbarea STORE_NAME îi pornește pe toți de la zero; nu face niciodată asta în jocul live.

Surse și lecturi suplimentare

Cum a fost verificat codul: fiecare script de pe această pagină trece printr-o verificare strictă a tipurilor Luau cu definițiile API Roblox (luau-lsp, 20 noiembrie 2026). Verificarea tipurilor prinde nume greșite de API și tipuri greșite, dar nu și greșelile de logică a jocului, așa că testează totul în Studio înainte să publici.

Încearcă RoCode în jocul tău.

Credite gratuite în fiecare zi, fără card. Instalează pluginul, descrie o funcție și verifică ce a apărut în Studio.