In breve
Usa DataStoreService da uno Script del server: carica i dati del giocatore con GetAsync quando entra, tienili in una tabella mentre gioca e salvali con UpdateAsync a intervalli regolari, quando esce (PlayerRemoving) e quando il server si spegne (game:BindToClose). Racchiudi ogni chiamata in un pcall e ripeti alcune volte quelle fallite.
- Per testare in Studio, pubblica il place e attiva File > Experience Settings > Security > Enable Studio Access to API Services in un gioco di prova separato: Studio usa gli stessi dati dei server live.
- Se i dati di un giocatore non si sono caricati, non salvare mai quel giocatore. Salvare i valori predefiniti cancellerebbe i suoi veri progressi.
- Tieni una sola tabella per giocatore sotto una sola chiave, per esempio
User_12345, e salva a intervalli regolari, non a ogni modifica. - Per scambi tra giocatori o oggetti a pagamento aggiungi un blocco di sessione (session locking), così due server non possono salvare lo stesso giocatore.
In questa pagina
Prima di iniziare: attiva l'accesso di Studio in una copia di prova
Un gioco avviato in Studio non può accedere ai data store finché non lo permetti. Il permesso ha un tranello di cui la documentazione di Roblox avverte: da quel momento Studio legge e scrive gli stessi data store del gioco live, quindi un test che azzera le tue monete in Studio le azzera anche nel gioco live, e un errore nel codice di prova può rovinare le chiavi di giocatori veri.
- Crea una copia di prova. Salva il place in un file, apri la copia, scegli File > Publish to Roblox As e clicca Create new game. Non aggiungerla come place dentro il gioco live: tutti i place di uno stesso gioco condividono gli stessi data store.
- Nella copia di prova apri File > Experience Settings e vai su Security.
- Attiva Enable Studio Access to API Services e clicca Save.
Le chiamate ai data store funzionano solo negli Script del server; un LocalScript che ci prova riceve un errore, quindi i client non possono scrivere i dati salvati. Quando un pulsante deve modificarli, il client lo chiede al server tramite un RemoteEvent, e decide il server (vedi la guida ai RemoteEvent).
Come i data store conservano i dati dei giocatori
Un data store è un insieme con nome di chiavi e valori sui server di Roblox, condiviso da tutti i server e tutti i place del tuo gioco. DataStoreService:GetDataStore("PlayerData") restituisce uno di questi data store.
Le raccomandazioni di Roblox si riassumono nella regola un data store per i dati dei giocatori, una chiave per giocatore, una tabella in ogni chiave. Costruisci la chiave dallo UserId del giocatore, per esempio User_12345, e mai dal nome, che può cambiare. Uno schema fisso User_{UserId} permette anche alla gestione automatica di Roblox del diritto all'oblio di trovare i dati del giocatore, se la configuri.
| Tipo | Si salva? | Note |
|---|---|---|
| Numeri, stringhe, booleani, buffer | Sì | Le stringhe devono essere UTF-8 valido. Non salvare inf o nan. |
| Tabelle | Sì | Se anche tutto ciò che contengono si può salvare. Una tabella le cui chiavi numeriche non partono da 1 (quindi con lunghezza 0) torna indietro con quelle chiavi trasformate in stringhe. |
Instance, Vector3, CFrame, Color3 | No | Il salvataggio dà errore o scrive nil. Salva il nome dell'oggetto o la posizione come tre numeri. |
Ogni richiesta è una chiamata web che può fallire, richiede tempo e consuma un budget al minuto. Per questo i sistemi di salvataggio affidabili leggono i dati una volta quando il giocatore entra, li tengono in una tabella sul server mentre gioca e ogni tanto li riscrivono.
GetAsync, SetAsync o UpdateAsync: quale scegliere
| Metodo | Cosa fa | A cosa serve |
|---|---|---|
GetAsync(key) | Legge un valore. Il risultato resta in cache su quel server per 4 secondi. | Caricare i dati del giocatore |
SetAsync(key, value) | Sovrascrive il valore senza leggerlo. Una scrittura. | Una chiave nuova o un valore che non dipende da quello vecchio |
UpdateAsync(key, callback) | Legge l'ultimo valore, lo passa alla tua funzione e scrive ciò che restituisce. Una lettura e una scrittura. | Salvare i dati del giocatore e qualsiasi chiave che più server possono scrivere |
IncrementAsync(key, delta) | Aggiunge un intero a un intero salvato. | Contatori |
RemoveAsync(key) | Elimina la chiave e restituisce il valore vecchio. Le versioni precedenti si possono ancora elencare e leggere. | Eliminare i dati di un giocatore |
SetAsync scrive alla cieca: se due server salvano la stessa chiave quasi nello stesso momento, vince l'ultima scrittura, qualunque cosa contenga. UpdateAsync legge prima il valore attuale, e se nel frattempo scrive un altro server, Roblox riesegue la tua funzione con il valore nuovo. Roblox lo consiglia ogni volta che la scrittura dipende dal valore attuale o che più server possono scrivere la chiave, ed è esattamente il caso dei dati dei giocatori. La funzione ha tre regole:
- Non deve cedere l'esecuzione (yield): niente
task.wait()né altre chiamate ai data store al suo interno. - Può essere eseguita più di una volta, quindi deve solo calcolare il nuovo valore e mai consegnare oggetti o scatenare eventi.
- Restituire
nilannulla la scrittura. Il modulo lo usa per non sovrascrivere dati salvati da una versione più recente del gioco.
Passo 1: crea il modulo PlayerData
Questo ModuleScript è l'unico codice che parla con il data store. Carica i dati del giocatore quando entra, li tiene in memoria, li salva ogni 180 secondi, quando esce e quando il server si spegne, e si rifiuta di salvare chi non ha caricato i dati.
- Nell'Explorer passa il mouse su ServerScriptService, clicca + e inserisci un ModuleScript. Rinominalo
PlayerDatae sostituisci il contenuto con il codice qui sotto. - Un ModuleScript si esegue solo quando uno script lo carica con require. Inserisci in ServerScriptService uno Script chiamato
Maincon questa riga:local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Gli altri script del server lo caricano allo stesso modo. - Modifica
DEFAULTSe il tipoDataper il tuo gioco, lasciando ogni campo come numero, stringa, booleano o tabella.
ServerScriptService
PlayerData ModuleScript new
Main Script new
StarterPlayer
StarterPlayerScripts
DataWarning LocalScript new
-- PlayerData: carica i dati del giocatore quando entra, li tiene in memoria
-- e li salva a intervalli regolari, all'uscita e allo spegnimento del server.
-- Gli altri script del server li leggono e modificano tramite 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 -- aumentalo quando cambia la forma dei dati e aggiungi un passo in migrate()
local AUTOSAVE_SECONDS = 180
-- In Studio una chiamata fallita si arrende subito, così un test senza accesso al data store è veloce
local MAX_ATTEMPTS = if RunService:IsStudio() then 1 else 4
local FIRST_RETRY_SECONDS = 1 -- raddoppia dopo ogni fallimento: 1, 2, 4
export type Data = {
SchemaVersion: number,
Coins: number,
Level: number,
Inventory: { string },
}
-- Con cosa inizia un giocatore completamente nuovo
local DEFAULTS: { [string]: any } = {
Coins = 0,
Level = 1,
Inventory = {},
}
type Session = {
key: string,
userId: number,
data: Data,
canSave: boolean, -- false se il caricamento è fallito: i dati predefiniti non devono sostituire i veri progressi
}
-- Chiamata dentro ogni pcall qui sotto, così un place non ancora pubblicato
-- (senza accesso al data store) carica comunque i giocatori con i dati predefiniti
local function store(): DataStore
return DataStoreService:GetDataStore(STORE_NAME)
end
local sessions: { [Player]: Session } = {}
local pendingSaves: { [string]: number } = {} -- salvataggi ancora in corso, per chiave
local loadedEvent = Instance.new("BindableEvent")
local PlayerData = {}
-- Scatta con il giocatore quando i suoi dati sono pronti. Prendi la tabella con PlayerData.Get(player):
-- una tabella inviata tramite BindableEvent arriva come copia, e modificarla non cambia nulla.
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) -- copia nuova, così i giocatori non condividono mai una stessa tabella Inventory
data.SchemaVersion = SCHEMA_VERSION
return data
end
-- Porta i dati salvati allo schema attuale. Restituisce nil se non si possono usare in sicurezza.
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 -- salvato da una versione più recente del gioco: qui non caricare e non sovrascrivere
end
-- Un passo per ogni modifica dello schema, dal più vecchio al più nuovo
if version < 2 then
-- Esempio: nella versione 1 la valuta si chiamava Gold. La copiamo solo se Coins manca,
-- così i vecchi dati che hanno già Coins ma non SchemaVersion conservano il valore.
if saved.Coins == nil then
saved.Coins = saved.Gold
end
saved.Gold = nil
end
-- Aggiungiamo i campi comparsi dopo l'ultimo salvataggio del giocatore e sostituiamo i valori di tipo sbagliato
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
-- Esegue una chiamata al data store dentro un pcall. Se fallisce aspetta e riprova, raddoppiando ogni volta
-- l'attesa e aggiungendo un po' di casualità, così i server non riprovano tutti insieme.
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 -- restituire nil annulla la scrittura
end
-- Scriviamo l'intera tabella attuale, contrassegnata con lo UserId del giocatore
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()
-- Partiamo in un momento casuale dell'intervallo, così i server non salvano tutti insieme
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
-- Se il giocatore è appena uscito da questo server ed è tornato, lasciamo prima finire l'ultimo salvataggio
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 -- è uscito durante il caricamento: non è cambiato nulla, non c'è niente da salvare
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) -- una GUI può leggerlo e avvisare il giocatore
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 -- ferma il ciclo di salvataggio automatico, e una seconda chiamata non fa nulla
save(session)
end
-- La tabella viva dei dati del giocatore, o nil finché non si è caricata. Modificala solo dagli script del server.
function PlayerData.Get(player: Player): Data?
local session = sessions[player]
return if session then session.data else nil
end
-- True quando i dati del giocatore si sono caricati e verranno salvati. Controllalo prima di ogni vendita.
function PlayerData.CanSave(player: Player): boolean
local session = sessions[player]
return session ~= nil and session.canSave
end
-- Salva adesso, senza aspettare il timer, per i momenti importanti come un acquisto.
-- Cede l'esecuzione e restituisce true quando il salvataggio è riuscito.
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) -- giocatori entrati prima che questo modulo fosse caricato per la prima volta
end
game:BindToClose(function()
-- Il server dà a queste funzioni 30 secondi, quindi salviamo tutti contemporaneamente
for player in sessions do
task.spawn(endSession, player)
end
-- Poi aspettiamo tutti i salvataggi ancora in corso, compresi quelli avviati in PlayerRemoving
while next(pendingSaves) do
task.wait()
end
end)
return PlayerData
Quando il gioco è uscito, non cambiare STORE_NAME né lo schema di chiave User_. Cambiare uno dei due porta il modulo su chiavi vuote, e ogni giocatore ricomincia dai valori predefiniti.
Come il modulo protegge i dati
Valori predefiniti e versione dello schema
Un giocatore nuovo riceve una copia nuova di DEFAULTS. Deve essere proprio una copia: se tutti i giocatori condividessero una sola tabella Inventory, un oggetto aggiunto a uno comparirebbe a tutti.
Ogni tabella salvata porta un SchemaVersion. Aggiungere un campo non richiede una nuova versione, perché migrate riempie i campi mancanti con i valori predefiniti. Rinominare o ristrutturare invece sì: aumenta SCHEMA_VERSION e aggiungi un passo, come nell'esempio che rinomina Gold in Coins (in un gioco nuovo eliminalo e parti da 1). I dati con una versione più alta di quella del server vengono da una release più recente che è ancora in distribuzione, quindi i server vecchi non li toccano.
Un caricamento fallito non si salva mai
Questa regola protegge dalla cancellazione totale. Se tutti i tentativi di caricamento falliscono, il giocatore gioca con i dati predefiniti, ma canSave è false, quindi quei valori non sovrascriveranno mai i suoi veri progressi. Il modulo imposta anche l'attributo DataLoaded a false, e il passo 3 lo usa per avvisare il giocatore. L'esempio di riferimento di Roblox gestisce i caricamenti falliti allo stesso modo e lo propone invece del kick; se preferisci espellere il giocatore, chiama player:Kick() con un messaggio nel punto in cui il modulo stampa l'avviso.
Tentativi ripetuti con pausa crescente
withRetries racchiude ogni chiamata in un pcall. Dopo un fallimento aspetta 1, poi 2, poi 4 secondi, ogni volta più un tempo casuale fino a metà di quello, e si ferma dopo quattro tentativi (in Studio dopo uno, così un place senza accesso al data store parte subito). La casualità distribuisce i tentativi di tanti server dopo un guasto, e il limite tiene l'attesa entro circa 10 secondi, dentro i 30 secondi che il server ha per spegnersi. Poiché ogni salvataggio scrive l'intera tabella viva con UpdateAsync, un tentativo che finisce in ritardo non può riportare indietro dati vecchi.
Quando salva il modulo
| Quando | Perché |
|---|---|
| Ogni 180 secondi, mentre il giocatore è sul server | Limita le perdite in caso di crash. Il primo salvataggio cade in un momento casuale dell'intervallo, così i server non salvano tutti insieme. Anche l'esempio di riferimento di Roblox usa 180 secondi. |
Quando il giocatore esce (PlayerRemoving) | Il normale salvataggio finale. La sessione viene rimossa per prima, quindi il salvataggio automatico si ferma. |
Quando il server si spegne (game:BindToClose) | Tutti quelli ancora sul server vengono salvati insieme, e la funzione aspetta ogni salvataggio in corso. Roblox le concede 30 secondi. |
Su richiesta, con PlayerData.SaveNow(player) | Dopo qualcosa che non si può perdere, per esempio un acquisto. |
Se un giocatore rientra nello stesso server mentre il suo salvataggio finale è ancora in corso, il nuovo caricamento aspetta la fine di quel salvataggio, quindi non può leggere il valore vecchio.
Passo 2: leggi e modifica i dati da altri script
Tutti gli script del server che caricano il modulo lavorano sulle stesse tabelle:
| Chiamata | Cosa fa |
|---|---|
PlayerData.Get(player) | La tabella viva dei dati del giocatore, o nil finché non si è caricata. Modifica i campi direttamente, per esempio data.Coins += 10, e il salvataggio successivo lo prende. |
PlayerData.Loaded | Scatta con il giocatore quando i suoi dati sono pronti, anche dopo un caricamento fallito. Passa solo il giocatore, perché una tabella inviata tramite BindableEvent arriva come copia. |
PlayerData.CanSave(player) | false se il caricamento è fallito. Controllalo prima di ogni vendita: un acquisto che non si può salvare sparisce quando il giocatore esce. |
PlayerData.SaveNow(player) | Salva subito e restituisce true se è riuscito. Cede l'esecuzione. |
Il modulo è l'unico posto dove vivono i dati salvati, e le leaderstats sono solo una visualizzazione: costruiscile come nella guida alla classifica, riempile da PlayerData.Get(player) nel gestore di Loaded e aggiorna entrambi quando un valore cambia. Non rileggere mai i valori salvati dalle leaderstats e non lasciare mai che un secondo script salvi la stessa chiave.
Uno script che carica il modulo dopo che i giocatori sono entrati perde Loaded per loro. Collega il gestore, poi scorri anche Players:GetPlayers() e gestisci tutti quelli per cui PlayerData.Get(player) restituisce già una tabella.
Stai sostituendo un vecchio script di salvataggio, per esempio quello della guida alla classifica? I suoi valori restano nel suo data store e nella sua chiave, quindi questo modulo farà partire tutti dai valori predefiniti. Prima del lancio, o punta STORE_NAME e il prefisso User_ su quelli vecchi (migrate considera i dati senza SchemaVersion come versione 1 e riempie i campi mancanti), o trasferisci i vecchi valori, poi elimina il vecchio script.
I client non modificano mai questi dati direttamente. Un pulsante del negozio attiva un RemoteEvent; il server controlla CanSave, confronta il prezzo con le Coins del giocatore, modifica la tabella e chiama SaveNow. La guida alla GUI del negozio costruisce un acquisto di questo tipo lato server.
Un esempio pronto di aggiunta di campi c'è nella guida al simulatore clicker: aggiunge PowerLevel e Rebirths a DEFAULTS e al tipo Data, poi li modifica nella tabella restituita da PlayerData.Get. migrate dà i campi nuovi ai giocatori con salvataggi vecchi.
Passo 3: avvisa il giocatore che i suoi dati non si sono caricati
Un giocatore i cui dati non si sono caricati deve sapere che questa sessione non verrà salvata, così rientra invece di giocare a vuoto. Questo LocalScript osserva l'attributo DataLoaded e mostra un banner quando vale 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
-- Il server imposta DataLoaded una sola volta, dopo aver provato a caricare i dati di questo giocatore
player:GetAttributeChangedSignal("DataLoaded"):Connect(showWarning)
showWarning()
Passo 4: testa il salvataggio in Studio
Fallo nella copia di prova con l'accesso di Studio attivato.
- Datti qualcosa da salvare. Sotto la riga require in
Mainaggiungi:PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end) - Premi Play. La finestra Output (nel menu Window o nella scheda Script) mostra il tuo nome e 100 (al primo avvio), senza l'avviso
Could not load. - Premi Stop. Terminare il test chiude il server, e il modulo ti salva prima della chiusura.
- Premi di nuovo Play. L'Output dovrebbe mostrare 200, 100 in più della volta prima. Se mostra di nuovo lo stesso numero, il salvataggio non è riuscito: leggi gli avvisi sopra.
- Prova il caso di errore. Disattiva l'accesso di Studio e premi Play. Dopo qualche secondo di tentativi l'Output mostra
Could not load User_...e 100, e compare il banner del passo 3. Ferma il test, riattiva l'accesso e premi Play: l'Output mostra 300, i tuoi 200 salvati più 100, perché la sessione fallita non ha mai sovrascritto i tuoi dati. - Elimina la riga di prova da
Main.
Perché i dati dei giocatori vanno persi
Ecco i modi più comuni in cui un sistema di salvataggio perde i progressi. Il modulo copre nel codice le prime quattro righe e quella sullo schema; le altre dipendono da cosa salvi e come, e per l'ultima serve un blocco di sessione.
| Cosa succede | Risultato | Come evitarlo |
|---|---|---|
| Il caricamento fallisce e lo script salva comunque | I valori predefiniti cancellano i veri progressi: cancellazione totale | Non salvare mai un giocatore il cui caricamento è fallito |
Salvare solo in PlayerRemoving | Un crash o lo spegnimento del server salta il salvataggio | Salvataggio automatico più un BindToClose che aspetta i suoi salvataggi |
Nessun pcall o nessun nuovo tentativo | Una sola richiesta fallita blocca lo script o perde il salvataggio | pcall con alcuni tentativi distanziati nel tempo |
| Salvare a ogni modifica | Le richieste finiscono in coda; quando la coda arriva a 30, le nuove vengono scartate | Tenere i dati in memoria e salvare a intervalli regolari |
| Salvare ciò che il data store non sa conservare | Il salvataggio dà errore, o il valore torna nil | Salvare numeri, stringhe, booleani e tabelle di questi |
| Cambiare la forma dei dati senza migrazione | I vecchi salvataggi si caricano nei campi sbagliati | Versione dello schema e un passo di migrazione |
| Due script salvano la stessa chiave | Ogni salvataggio cancella i campi dell'altro | Un solo modulo possiede la chiave |
| Due server tengono lo stesso giocatore | Il server con i dati vecchi salva per ultimo e cancella i progressi nuovi | Blocco di sessione |
Blocco di sessione, «lock lost» e ProfileStore
Un giocatore è connesso a un server alla volta, ma il salvataggio finale del vecchio server può essere ancora in corso quando entra in uno nuovo: un tentativo lento, un teletrasporto o un rientro veloce. Se il nuovo server carica i dati per primo, avrà dati vecchi, e vince il server che salva per ultimo. La documentazione di Roblox nota che nei giochi con scambi questo intervallo è una causa frequente di duplicazione degli oggetti.
Il blocco di sessione (session locking) chiude questo intervallo. Quando un server carica la chiave di un giocatore, nella stessa chiamata UpdateAsync scrive il proprio ID di blocco nei metadati della chiave. Qualsiasi altro server che trova un blocco non scaduto che non ha messo lui non carica e non salva quella chiave. Il proprietario rinnova il blocco a ogni salvataggio automatico e lo rilascia nel salvataggio finale; se smette di rinnovarlo, il blocco scade e un altro server può prenderlo.
Cosa significa «lock lost»
In un sistema con blocco di sessione, un server ha perso il blocco quando la chiave del giocatore ora appartiene a un altro server, perché il blocco è scaduto o è stato preso. La sua copia potrebbe essere vecchia, quindi deve smettere di salvare quel giocatore; la reazione abituale è espellerlo con un messaggio perché si riconnetta. Se hai visto «lock lost» come giocatore, è un messaggio del sistema di salvataggio di quel gioco, e possono spiegarlo solo i suoi sviluppatori.
Ti serve?
Il modulo di questa guida non blocca le sessioni. Senza blocco, il caso peggiore reale è questo: in una rara corsa il giocatore perde ciò che ha guadagnato sul vecchio server dopo il suo ultimo salvataggio riuscito. Aggiungi il blocco quando la duplicazione o la perdita costano ai giocatori qualcosa di vero: scambi, developer products, oggetti rari o teletrasporti frequenti.
| Opzione | Cos'è | Cosa sapere |
|---|---|---|
| Il modulo di questa guida | Caricamento, cache in memoria, tentativi ripetuti, salvataggio automatico, salvataggio allo spegnimento e versioni dello schema, senza blocco | Abbastanza corto da leggerlo tutto e modificarlo |
| L'esempio di Roblox per dati dei giocatori e acquisti | Codice di riferimento di Roblox con blocco di sessione, tentativi in ordine per ogni chiave e gestione delle ricevute di acquisto | Roblox dice che non è stato messo alla prova in un gioco popolare e non va usato così com'è senza test approfonditi |
| ProfileStore | Modulo gratuito open source della community, successore di ProfileService, costruito attorno al blocco di sessione e al salvataggio automatico | Non è di Roblox. Passarci con un gioco esistente richiede di migrare i dati già salvati |
Per qualsiasi modulo di terze parti Roblox consiglia di controllare chi lo possiede, se è mantenuto e come arriveresti ai tuoi dati senza di esso. La stessa documentazione indica DataStore2 come una libreria superata che i giochi nuovi non dovrebbero usare.
Limiti dei data store
Questi sono i limiti della documentazione di Roblox al 30 settembre 2026. Roblox li rivede, quindi controlla la pagina dei codici di errore e dei limiti (in inglese) prima di contare su un numero esatto.
| Tipo di richiesta | Data store normali | Data store ordinati |
|---|---|---|
Lettura: GetAsync, la lettura in UpdateAsync | 60 + 40 × giocatori | 60 + 40 × giocatori |
Scrittura: SetAsync, IncrementAsync, la scrittura in UpdateAsync | 60 + 40 × giocatori | 30 + 5 × giocatori |
Elenco: ListKeysAsync o GetSortedAsync per i data store ordinati | 5 + 2 × giocatori | 5 + 2 × giocatori |
Eliminazione: RemoveAsync | 60 + 40 × giocatori | 30 + 5 × giocatori |
Con 20 giocatori un server può fare 860 scritture normali al minuto; il salvataggio automatico di questo modulo ne usa circa 7, più una per ogni giocatore che esce. Il budget lo esaurisce salvare a ogni moneta raccolta. Un secondo budget vale per tutto il gioco ed è condiviso con Open Cloud: 300 letture al minuto più 40 per ogni giocatore online e 300 scritture più 20 per giocatore.
| Limite | Valore |
|---|---|
| Nome del data store, nome della chiave, scope | 50 caratteri ciascuno |
| Valore in una chiave | 4 194 304 caratteri come JSON |
| Lettura di una chiave da tutti i server | 25 MB al minuto |
| Scrittura in una chiave da tutti i server | 4 MB al minuto, ogni richiesta arrotondata per eccesso al KB successivo |
| Richieste in attesa | 30 per coda; oltre, le richieste falliscono con gli errori 301-306 |
| Spazio per l'intero gioco | 500 MB più 1 MB per ogni utente di sempre |
Misura la dimensione dei dati del giocatore con #HttpService:JSONEncode(data), e controlla il budget rimanente di un server live con DataStoreService:GetRequestBudgetForRequestType(Enum.DataStoreRequestType.StandardWrite). Le chiamate GetAsync a cui risponde la cache di 4 secondi non contano. La modalità Run di Studio ha limiti propri, forse più bassi, quindi per testare i limiti di richieste Roblox consiglia Team Create.
Versioni e backup
I data store normali conservano la cronologia per te. La prima scrittura in una chiave in ogni ora UTC viene conservata come versione, e le scritture successive in quell'ora si sovrascrivono a vicenda. Una versione vecchia scade 30 giorni dopo essere stata sostituita da una scrittura più recente; l'ultima non scade mai. I data store ordinati non conservano versioni.
Per riportare indietro un giocatore apri il Data Stores Manager (Creations, il tuo gioco, Configure > Data Stores Manager), scegli la sua chiave, seleziona una versione precedente e clicca Revert; serve il permesso Edit. Fallo mentre il giocatore è offline, altrimenti il server con la sua sessione salverà la propria copia sopra il ripristino. Da uno script del server, ListVersionsAsync e GetVersionAsync trovano e leggono una versione vecchia, che poi riscrivi come valore attuale.
Prima di pubblicare un aggiornamento che cambia il modo in cui si salvano i dati, Roblox consiglia di fare uno snapshot con la Open Cloud Snapshot Data Stores API (uno al giorno per gioco). Senza, un salvataggio sbagliato alle 3:30 UTC cancella tutto ciò che è stato scritto in quella chiave dalle 3:00, perché finisce nella stessa versione oraria.
Errori comuni e soluzioni
Gli errori dei data store compaiono nella finestra Output di Studio, e il modulo stampa un avviso con il testo dell'errore di Roblox a ogni tentativo fallito. La guida agli errori degli script spiega come leggere l'Output in generale.
StudioAccessToApisNotAllowed (errore 403)
«Can't write to DataStore from Studio because API access is not enabled.» Pubblica il place, poi attiva Enable Studio Access to API Services in File > Experience Settings > Security, nella copia di prova.
DataStore request was added to queue
Il server invia richieste più velocemente di quanto il budget consenta, o scrive troppo spesso la stessa chiave, di solito perché salva a ogni modifica o in un ciclo. Quando la coda arriva a 30 richieste, le nuove falliscono con gli errori 301-306. Tieni i dati in memoria e salva a intervalli regolari.
CantStoreValue (errore 104), o un campo torna nil
Nella tabella c'è qualcosa che il data store non sa salvare, per esempio una Instance, un Vector3 o un Color3. Salva invece il nome, l'ID o numeri semplici e ricostruisci l'oggetto al caricamento.
ValueTooLarge (errore 105)
Una chiave contiene più di 4 194 304 caratteri di JSON. Misura con #HttpService:JSONEncode(data), togli ciò che si può ricostruire o dividi i dati su più chiavi fisse.
Nessun errore, ma i dati non si salvano
Cerca l'avviso del modulo Could not load: dopo un caricamento fallito si rifiuta di salvare apposta. Altrimenti il valore è stato probabilmente modificato in un LocalScript, cosa che non arriva mai al server, oppure la stessa chiave la salva un altro script.
I dati si azzerano a ogni rientro
La chiave cambia tra una sessione e l'altra (costruita da player.Name, o hai cambiato STORE_NAME), il caricamento fallisce e vedi i valori predefiniti, oppure nessuno carica il modulo e quindi non gira affatto. Controlla l'Output e che Main carichi PlayerData.
Costruiscilo con RoCode
Se non hai voglia di costruirlo a mano, RoCode può farlo direttamente nel place che hai aperto. È un agente IA indipendente, non di Roblox, che lavora tramite un plugin per Roblox Studio: scrive Luau che usa DataStoreService come qualsiasi script e crea gli script nel tuo Explorer. Non accede mai da solo ai tuoi data store, ma con il plugin 3.9 o successivo può premere Play per un breve playtest, in cui i tuoi script girano come in qualsiasi test.
Aggiungi il salvataggio al mio gioco: conserva Coins, Level e Inventory in un modulo PlayerData con salvataggio automatico e salvataggio allo spegnimento del server, e mostra Coins nelle leaderstats che ho già.
- Può cercare le leaderstats e il codice DataStore esistenti con Search Scripts e Read Script, per estendere ciò che hai invece di aggiungere un secondo script di salvataggio. In un place grande indica lo script o la cartella nel messaggio.
- Crea il ModuleScript e lo Script che lo carica con Create Script, o modifica quelli esistenti con Edit Script
- Esegue Check Script su ogni script scritto: un controllo di compilazione dentro Studio con un breve elenco di avvisi, non un controllo dei tipi né un avvio di prova
- Invia le modifiche a blocchi, e ogni blocco è un punto di annullamento (undo) in Studio
Attivare Studio Access to API Services nella copia di prova dovrai comunque farlo tu: RoCode non può cambiare questa impostazione. Con il plugin 3.9 o successivo il suo breve playtest legge gli errori, e con il plugin 3.9.11 o successivo può controllare un personaggio di prova per verificare che il gioco funzioni, ma controlla solo ciò che ha deciso di controllare, quindi gioca tu stesso e assicurati che Coins, Level e Inventory si salvino e si carichino. Se il salvataggio non è riuscito nel tuo test, Check Output può leggere le righe Server del playtest che hai avviato. Di solito il salvataggio si aggiunge quando il ciclo di gioco principale funziona già; creare un gioco Roblox con l'IA un sistema alla volta mostra questo ordine. Come RoCode si collega a Studio.
Domande frequenti
Come si attiva DataStore in Roblox Studio?
Pubblica il place, apri File > Experience Settings > Security, attiva Enable Studio Access to API Services e clicca Save. Fallo in un gioco di prova separato, perché da quel momento Studio usa gli stessi data store dei server live di quel gioco.
Roblox salva automaticamente i dati dei giocatori?
No. Nulla di un giocatore viene conservato dopo la sessione se uno script del server non lo salva con DataStoreService, e questo vale anche per le leaderstats.
Cosa scegliere: ProfileStore o DataStoreService direttamente?
Anche ProfileStore è costruito sui data store, quindi la domanda è se vuoi che il blocco di sessione lo scriva e lo mantenga qualcun altro per te. Per scambi, oggetti a pagamento o teletrasporti frequenti il blocco vale la pena, da una libreria o dall'esempio di riferimento di Roblox. Per un gioco più piccolo un modulo come questo è più facile da leggere e modificare.
Come si azzerano o eliminano i dati di un giocatore?
Nel Data Stores Manager trova la chiave e scegli Mark for Deletion, che si può annullare durante il periodo di attesa, oppure chiama RemoveAsync sulla chiave da uno script del server. Fallo mentre il giocatore è offline, altrimenti il prossimo salvataggio del suo server riscriverà i dati. Nella copia di prova cambiare STORE_NAME fa ripartire tutti da zero; non farlo mai nel gioco live.
Fonti e letture
- Roblox Creator Docs: Data stores (in inglese). accesso di Studio, GetAsync, SetAsync, UpdateAsync, set e update
- Roblox Creator Docs: Best practices for data stores (in inglese). una chiave per giocatore, dati in memoria, tentativi con pausa crescente, moduli di terze parti
- Roblox Creator Docs: Data store error codes and limits (in inglese). codici di errore, limiti di richieste del server e del gioco, limiti di dimensione, velocità e spazio
- Roblox Creator Docs: Versioning, listing and caching (in inglese). versioni orarie, snapshot, cache di 4 secondi, cosa si può salvare
- Roblox Creator Docs: Implement player data and purchasing systems (in inglese). esempio di riferimento, blocco di sessione, caricamenti falliti, salvataggio automatico ogni 180 secondi
- Roblox Creator Docs: Data Stores Manager (in inglese). visualizzare le chiavi, ripristinare versioni, eliminare dati
- Roblox Engine API: DataModel:BindToClose (in inglese). 30 secondi per lo spegnimento
Come è stato controllato il codice: ogni script di questa pagina supera il controllo dei tipi rigoroso di Luau con le definizioni dell'API di Roblox (luau-lsp, 20 novembre 2026). Il controllo dei tipi trova API scritte male e tipi sbagliati, non la logica del gioco, quindi provalo in Studio prima di pubblicare.