Tutorial · Dati dei giocatori

Come salvare i dati dei giocatori in Roblox Studio con DataStore

Roblox non ricorda nulla di un giocatore tra una sessione e l'altra, a meno che uno script del server non l'abbia salvato. In questa guida costruisci un modulo PlayerData che carica, tiene in memoria e salva i dati di ogni giocatore con DataStoreService, poi vedi come testarlo, i limiti e i modi in cui i dati salvati vanno persi.

Aggiornato il 20 novembre 202619 min di letturaScritto da

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
  1. Accesso di Studio
  2. Come funziona DataStore
  3. GetAsync e UpdateAsync
  4. 1. Il modulo PlayerData
  5. Come è fatto il modulo
  6. 2. Usare i dati
  7. 3. Avviso
  8. 4. Test in Studio
  9. Perché i dati vanno persi
  10. Blocco di sessione
  11. Limiti
  12. Versioni e backup
  13. Common errors
  14. With RoCode
  15. Domande frequenti
  16. Fonti e letture

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.

  1. 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.
  2. Nella copia di prova apri File > Experience Settings e vai su Security.
  3. 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

IllustrazioneIl test del passo 4 della guida, accelerato: Play, Stop salva la sessione nel data store, un nuovo Play la carica, quindi l'Output mostra 200.

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.

Cosa si può salvare in un data store
TipoSi salva?Note
Numeri, stringhe, booleani, bufferSìLe stringhe devono essere UTF-8 valido. Non salvare inf o nan.
TabelleSì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, Color3NoIl 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

I metodi principali di un data store
MetodoCosa faA 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 nil annulla 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.

  1. Nell'Explorer passa il mouse su ServerScriptService, clicca + e inserisci un ModuleScript. Rinominalo PlayerData e sostituisci il contenuto con il codice qui sotto.
  2. Un ModuleScript si esegue solo quando uno script lo carica con require. Inserisci in ServerScriptService uno Script chiamato Main con questa riga: local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Gli altri script del server lo caricano allo stesso modo.
  3. Modifica DEFAULTS e il tipo Data per il tuo gioco, lasciando ogni campo come numero, stringa, booleano o tabella.
L'Explorer dopo i passi 1-3
ServerScriptService
    PlayerData ModuleScript new
    Main Script new
StarterPlayer
    StarterPlayerScripts
        DataWarning LocalScript new
ModuleScript in ServerScriptService chiamato PlayerData
-- 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

QuandoPerché
Ogni 180 secondi, mentre il giocatore è sul serverLimita 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:

ChiamataCosa 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.LoadedScatta 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.

LocalScript in StarterPlayerScripts chiamato 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

-- 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.

  1. Datti qualcosa da salvare. Sotto la riga require in Main aggiungi: PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end)
  2. 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.
  3. Premi Stop. Terminare il test chiude il server, e il modulo ti salva prima della chiusura.
  4. 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.
  5. 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.
  6. 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 succedeRisultatoCome evitarlo
Il caricamento fallisce e lo script salva comunqueI valori predefiniti cancellano i veri progressi: cancellazione totaleNon salvare mai un giocatore il cui caricamento è fallito
Salvare solo in PlayerRemovingUn crash o lo spegnimento del server salta il salvataggioSalvataggio automatico più un BindToClose che aspetta i suoi salvataggi
Nessun pcall o nessun nuovo tentativoUna sola richiesta fallita blocca lo script o perde il salvataggiopcall con alcuni tentativi distanziati nel tempo
Salvare a ogni modificaLe richieste finiscono in coda; quando la coda arriva a 30, le nuove vengono scartateTenere i dati in memoria e salvare a intervalli regolari
Salvare ciò che il data store non sa conservareIl salvataggio dà errore, o il valore torna nilSalvare numeri, stringhe, booleani e tabelle di questi
Cambiare la forma dei dati senza migrazioneI vecchi salvataggi si caricano nei campi sbagliatiVersione dello schema e un passo di migrazione
Due script salvano la stessa chiaveOgni salvataggio cancella i campi dell'altroUn solo modulo possiede la chiave
Due server tengono lo stesso giocatoreIl server con i dati vecchi salva per ultimo e cancella i progressi nuoviBlocco 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.

OpzioneCos'èCosa sapere
Il modulo di questa guidaCaricamento, cache in memoria, tentativi ripetuti, salvataggio automatico, salvataggio allo spegnimento e versioni dello schema, senza bloccoAbbastanza corto da leggerlo tutto e modificarlo
L'esempio di Roblox per dati dei giocatori e acquistiCodice di riferimento di Roblox con blocco di sessione, tentativi in ordine per ogni chiave e gestione delle ricevute di acquistoRoblox dice che non è stato messo alla prova in un gioco popolare e non va usato così com'è senza test approfonditi
ProfileStoreModulo gratuito open source della community, successore di ProfileService, costruito attorno al blocco di sessione e al salvataggio automaticoNon è 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.

Limiti di richieste predefiniti per ogni server, al minuto
Tipo di richiestaData store normaliData store ordinati
Lettura: GetAsync, la lettura in UpdateAsync60 + 40 × giocatori60 + 40 × giocatori
Scrittura: SetAsync, IncrementAsync, la scrittura in UpdateAsync60 + 40 × giocatori30 + 5 × giocatori
Elenco: ListKeysAsync o GetSortedAsync per i data store ordinati5 + 2 × giocatori5 + 2 × giocatori
Eliminazione: RemoveAsync60 + 40 × giocatori30 + 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.

Limiti di dimensione e di velocità
LimiteValore
Nome del data store, nome della chiave, scope50 caratteri ciascuno
Valore in una chiave4 194 304 caratteri come JSON
Lettura di una chiave da tutti i server25 MB al minuto
Scrittura in una chiave da tutti i server4 MB al minuto, ogni richiesta arrotondata per eccesso al KB successivo
Richieste in attesa30 per coda; oltre, le richieste falliscono con gli errori 301-306
Spazio per l'intero gioco500 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.

Tu scrivi

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à.

RoCode fa
  • 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

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.

Prova RoCode nel tuo gioco.

Crediti gratis ogni giorno, senza carta. Installa il plugin, descrivi la funzione e controlla cosa compare in Studio.