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ă
Î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.
- 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.
- În copia de test deschide File > Experience Settings și mergi la Security.
- 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
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.
| Tip | Se salvează? | Observații |
|---|---|---|
| Numere, șiruri, valori booleene, buffere | Da | Șirurile trebuie să fie UTF-8 corect. Nu păstra inf sau nan. |
| Tabele | Da | Dacă 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, Color3 | Nu | Salvarea 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
| Metodă | Ce face | Pentru 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
nilanulează 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.
- Î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. - Un ModuleScript rulează doar când îl include (require) un script. Inserează în ServerScriptService un Script numit
Maincu acest rând:local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Alte scripturi de server îl includ la fel. - Schimbă
DEFAULTSși tipulDatapentru jocul tău, păstrând fiecare câmp ca număr, șir, valoare booleană sau tabel.
ServerScriptService
PlayerData ModuleScript new
Main Script new
StarterPlayer
StarterPlayerScripts
DataWarning LocalScript new
-- 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ând | De ce |
|---|---|
| La fiecare 180 de secunde, cât jucătorul e pe server | Limitează 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:
| Apel | Ce 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.Loaded | Se 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.
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.
- Dă-ți ceva de salvat. Sub rândul cu require din
Mainadaugă:PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end) - 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. - Apasă Stop. Terminarea testului închide serverul, iar modulul te salvează înainte de închidere.
- 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.
- 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. - Ș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ă | Rezultat | Cum previi |
|---|---|---|
| Încărcarea a eșuat, dar scriptul salvează oricum | Valorile implicite șterg progresul real: ștergere completă | Nu salva niciodată un jucător a cărui încărcare a eșuat |
Salvare doar în PlayerRemoving | O cădere sau oprire a serverului ratează salvarea | Autosalvare plus BindToClose, care își așteaptă salvările |
Fără pcall sau fără reîncercare | O singură cerere eșuată oprește scriptul sau pierde salvarea | pcall cu câteva reîncercări distanțate în timp |
| Salvare la fiecare schimbare | Cererile 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ăstra | Salvarea dă eroare sau valoarea revine nil | Salvează numere, șiruri, valori booleene și tabele din ele |
| Schimbarea formei datelor fără migrare | Salvările vechi se încarcă în câmpurile greșite | Versiune de schemă și un pas de migrare |
| Două scripturi salvează aceeași cheie | Fiecare salvare șterge câmpurile celuilalt | Cheia e deținută de un singur modul |
| Două servere țin același jucător | Serverul cu date vechi salvează ultimul și șterge progresul nou | Blocarea 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 este | Ce 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ă blocare | Destul de scurt cât să-l citești în întregime și să-l schimbi |
| Exemplul Roblox pentru datele jucătorilor și cumpărături | Cod de referință de la Roblox cu blocarea sesiunii, reîncercări în ordine pentru fiecare cheie și tratarea chitanțelor de cumpărare | Roblox spune că nu e testat în timp într-un joc popular și nu trebuie folosit așa cum e fără testare extinsă |
| ProfileStore | Un modul gratuit al comunității, cu cod deschis, succesorul ProfileService, construit în jurul blocării sesiunii și autosalvării | Nu 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.
| Tip de cerere | Depozite obișnuite | Depozite ordonate |
|---|---|---|
Citire: GetAsync, citirea din UpdateAsync | 60 + 40 × jucători | 60 + 40 × jucători |
Scriere: SetAsync, IncrementAsync, scrierea din UpdateAsync | 60 + 40 × jucători | 30 + 5 × jucători |
Listare: ListKeysAsync sau GetSortedAsync pentru depozitele ordonate | 5 + 2 × jucători | 5 + 2 × jucători |
Ștergere: RemoveAsync | 60 + 40 × jucători | 30 + 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.
| Limită | Valoare |
|---|---|
| Numele depozitului, numele cheii, scope | Câte 50 de caractere |
| Valoarea dintr-o cheie | 4 194 304 caractere ca JSON |
| Citirea unei chei de pe toate serverele | 25 MB pe minut |
| Scrierea într-o cheie de pe toate serverele | 4 MB pe minut, fiecare cerere se rotunjește în sus la următorul KB |
| Cereri în așteptare | 30 pe coadă; peste asta cererile eșuează cu erorile 301-306 |
| Stocarea pentru tot jocul | 500 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.
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.
- 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
- Roblox Creator Docs: Data stores (în engleză). accesul Studio, GetAsync, SetAsync, UpdateAsync, set și update
- Roblox Creator Docs: Best practices for data stores (în engleză). o cheie pe jucător, date în memorie, reîncercări cu pauză crescătoare, module terțe
- Roblox Creator Docs: Data store error codes and limits (în engleză). coduri de eroare, limite de cereri pe server și pe joc, limite de mărime, debit și stocare
- Roblox Creator Docs: Versioning, listing and caching (în engleză). versiuni orare, snapshot-uri, cache de 4 secunde, ce se poate salva
- Roblox Creator Docs: Implement player data and purchasing systems (în engleză). exemplul de referință, blocarea sesiunii, încărcări eșuate, autosalvare la 180 de secunde
- Roblox Creator Docs: Data Stores Manager (în engleză). vizualizarea cheilor, revenirea la versiuni, ștergerea datelor
- Roblox Engine API: DataModel:BindToClose (în engleză). 30 de secunde la oprire
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.