Archivi dei dati

Il DataStoreService ti consente di memorizzare dati che devono persistere tra le sessioni, come gli oggetti nell'inventario di un giocatore o i punti abilità. Gli archivi dei dati sono coerenti per gioco, quindi qualsiasi luogo in un gioco può accedere e modificare gli stessi dati, inclusi i luoghi su server diversi.

Se desideri aggiungere un controllo di autorizzazione granulare ai tuoi archivi dei dati e accedervi al di fuori di Studio o dei server Roblox, puoi utilizzare le API Open Cloud per gli archivi dei dati.

Per visualizzare e monitorare tutti gli archivi dei dati in un gioco tramite il Creator Hub, utilizza il Data Stores Manager.

Per dati temporanei che devi aggiornare o accedere frequentemente, utilizza memory stores.

Abilitare l'accesso a Studio

Per impostazione predefinita, i giochi testati in Studio non possono accedere agli archivi dei dati, quindi devi prima abilitarli. Accedere agli archivi dei dati in Studio può essere pericoloso per i giochi live perché Studio accede agli stessi archivi dei dati dell'applicazione client. Per evitare di sovrascrivere i dati di produzione, non abilitare questa impostazione per i giochi live. Invece, abilitalo per una versione di test separata del gioco.

Per abilitare l'accesso a Studio in un gioco pubblicato:

1. Apri la finestra File ⟩ Impostazioni esperienza di Studio.
2. Naviga su Sicurezza.
3. Abilita l'interruttore Abilita accesso a Studio ai servizi API.
4. Fai clic su Salva.

Accedere agli archivi dei dati

Per accedere a un archivio dei dati all'interno di un gioco:

1. Aggiungi DataStoreService a uno Script lato server.
2. Usa la funzione GetDataStore() e specifica il nome dell'archivio dei dati che desideri utilizzare. Se l'archivio dei dati non esiste, Studio ne crea uno quando salvi i dati del tuo gioco per la prima volta.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

Creare dati

Un archivio dei dati è essenzialmente un dizionario, simile a una tabella Luau. Una chiave unica indicizza ciascun valore nell'archivio dei dati, come l'unico Player.UserId di un utente o una stringa nominativa per una promozione di gioco.

Per creare una nuova voce, chiama SetAsync() con il nome della chiave e un valore.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local success, errorMessage = pcall(function()
	gameStore:SetAsync("User_1234", 50)
end)
if not success then
	print(errorMessage)
end

Aggiornare i dati

Per modificare qualsiasi valore memorizzato in un archivio dei dati, chiama UpdateAsync() con il nome della chiave della voce e una funzione di callback che definisce come desideri aggiornare la voce. Questa callback prende il valore corrente e restituisce un nuovo valore in base alla logica che definisci. Se la callback restituisce nil, l'operazione di scrittura viene annullata e il valore non viene aggiornato.

local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local function makeNameUpper(currentName)
	local nameUpper = string.upper(currentName)
	return nameUpper
end

local success, updatedName = pcall(function()
	return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
end)
if success then
	print("Nome maiuscolo:", updatedName)
end

Imposta vs aggiorna

Usa set per aggiornare rapidamente una chiave specifica. La funzione SetAsync():

• Può causare incoerenza dei dati se due server tentano di impostare la stessa chiave contemporaneamente
• Conta solo contro il limite di scrittura

Usa update per gestire tentativi multi-server. La funzione UpdateAsync():

• Legge il valore corrente della chiave dal server che l'ha aggiornata per ultimo prima di apportare modifiche
• È più lenta perché legge prima di scrivere
• Conta contro i limiti di lettura e scrittura

Leggere i dati

Per leggere il valore di una voce di archivio dei dati, chiama GetAsync() con il nome della chiave della voce.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local success, currentGame = pcall(function()
	return gameStore:GetAsync("User_1234")
end)
if success then
	print(currentGame)
end

Incrementare i dati

Per incrementare un intero in un archivio dei dati, chiama IncrementAsync() con il nome della chiave della voce e un numero per quanto cambiare il valore. IncrementAsync() è una funzione di convenienza che ti consente di evitare di chiamare UpdateAsync() e incrementare manualmente l'intero.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local success, newGame = pcall(function()
	return gameStore:IncrementAsync("Player_1234", 1)
end)
if success then
	print(newGame)
end

Rimuovere i dati

Per rimuovere una voce e restituire il valore associato alla chiave, chiama RemoveAsync().

local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local success, removedValue = pcall(function()
	return nicknameStore:RemoveAsync("User_1234")
end)
if success then
	print(removedValue)
end

Metadati

Ci sono due tipi di metadati associati alle chiavi:

• Definiti dal servizio: Metadati predefiniti in sola lettura, come l'ora dell'ultimo aggiornamento e l'ora di creazione. Ogni oggetto ha metadati definiti dal servizio.
• Definiti dall'utente: Metadati personalizzati per tagging e categorizzazione. Definiti utilizzando l'oggetto DataStoreSetOptions e la funzione SetMetadata().

Per gestire i metadati, espandi le funzioni SetAsync(), UpdateAsync(), GetAsync(), IncrementAsync(), e RemoveAsync().

• SetAsync() accetta i terzi e quarti argomenti opzionali:

  • Una tabella di UserIds. Questo può aiutare con il tracciamento e la rimozione dei diritti d'autore sui contenuti e della proprietà intellettuale.

  • Un oggetto DataStoreSetOptions, dove puoi definire metadati personalizzati utilizzando la funzione SetMetadata().

    local DataStoreService = game:GetService("DataStoreService")
    
    local gameStore = DataStoreService:GetDataStore("PlayerGame")
    
    local setOptions = Instance.new("DataStoreSetOptions")
    setOptions:SetMetadata({["GameElement"] = "Fire"})
    
    local success, errorMessage = pcall(function()
        gameStore:SetAsync("User_1234", 50, {1234}, setOptions)
    end)
    if not success then
        print(errorMessage)
    end

• GetAsync(), IncrementAsync(), e RemoveAsync() restituiscono un secondo valore nell'oggetto DataStoreKeyInfo. Questo secondo valore contiene sia le proprietà definite dal servizio che le funzioni per recuperare i metadati definiti dall'utente.

  • La funzione GetUserIds() recupera la tabella di UserIds che hai passato a SetAsync().
  • La funzione GetMetadata() recupera i metadati definiti dall'utente che hai passato a SetAsync() tramite SetMetadata().
  • La proprietà Version recupera la versione della chiave.
  • La proprietà CreatedTime recupera l'ora in cui è stata creata la chiave, formattata come il numero di millisecondi dall'epoca.
  • La proprietà UpdatedTime recupera l'ultima volta che la chiave è stata aggiornata, formattata come il numero di millisecondi dall'epoca.

  local DataStoreService = game:GetService("DataStoreService")
  
  local gameStore = DataStoreService:GetDataStore("PlayerGame")
  
  local success, currentGame, keyInfo = pcall(function()
      return gameStore:GetAsync("User_1234")
  end)
  if success then
      print(currentGame)
      print(keyInfo.Version)
      print(keyInfo.CreatedTime)
      print(keyInfo.UpdatedTime)
      print(keyInfo:GetUserIds())
      print(keyInfo:GetMetadata())
  end

• La funzione di callback di UpdateAsync() prende un parametro aggiuntivo nell'oggetto DataStoreKeyInfo che descrive lo stato attuale della chiave. Restituisce il valore modificato, le chiavi associate a UserIds, e i metadati della chiave.

  local DataStoreService = game:GetService("DataStoreService")
  
  local nicknameStore = DataStoreService:GetDataStore("Nicknames")
  
  local function makeNameUpper(currentName, keyInfo)
      local nameUpper = string.upper(currentName)
      local userIDs = keyInfo:GetUserIds()
      local metadata = keyInfo:GetMetadata()
      return nameUpper, userIDs, metadata
  end
  
  local success, updatedName, keyInfo = pcall(function()
      return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
  end)
  if success then
      print(updatedName)
      print(keyInfo.Version)
      print(keyInfo.CreatedTime)
      print(keyInfo.UpdatedTime)
      print(keyInfo:GetUserIds())
      print(keyInfo:GetMetadata())
  end

Per i limiti nella definizione dei metadati, vedere i limiti dei metadati.

Archivi dei dati ordinati

Per impostazione predefinita, gli archivi dei dati non ordinano i loro contenuti. Se hai bisogno di ottenere dati in modo ordinato, come nelle statistiche della classifica persistente, chiama GetOrderedDataStore() invece di GetDataStore().

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

Gli archivi dei dati ordinati supportano le stesse funzioni di base degli archivi dei dati predefiniti, oltre alla funzione unica GetSortedAsync(). Questa recupera più chiavi ordinate in base a un ordine di ordinamento specifico, dimensione della pagina e valori minimi/massimi.

Il seguente esempio ordina i dati dei personaggi in pagine con tre voci, ciascuna in ordine decrescente, quindi scorre le pagine e restituisce il nome e l'età di ciascun personaggio.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- Popola l'archivio dei dati ordinati
local characters = {
	Mars = 19,
	Janus = 20,
	Diana = 18,
	Venus = 25,
	Neptune = 62
}
for char, age in characters do
	local success, errorMessage = pcall(function()
		characterAgeStore:SetAsync(char, age)
	end)
	if not success then
		print(errorMessage)
	end
end

-- Ordina i dati in ordine decrescente in pagine di tre voci ciascuna
local success, pages = pcall(function()
	return characterAgeStore:GetSortedAsync(false, 3)
end)
if success then
	while true do
		-- Ottiene la pagina corrente (prima)
		local entries = pages:GetCurrentPage()
		-- Itera attraverso tutte le coppie chiave-valore nella pagina
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Controlla se è stata raggiunta l'ultima pagina
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Avanza alla pagina successiva
			pages:AdvanceToNextPageAsync()
		end
	end
end

Leggere più voci

Per leggere più voci di archivio dei dati ordinato in una singola richiesta, chiama BatchGetAsync() con un array di chiavi. Questo è il corrispondente batch per leggere voci una alla volta con GetAsync().

BatchGetAsync() restituisce un dizionario che mappa ciascuna chiave richiesta a una tabella con un campo value. Le chiavi che non esistono vengono omesse dal dizionario, quindi conferma che una chiave sia presente prima di leggere il suo valore.

Ogni chiave che richiedi conta come una richiesta di lettura, quindi una singola chiamata per N chiavi conta come N richieste contro il limite di lettura dell'archivio dei dati ordinato.

Il seguente esempio legge tre punteggi di giocatori in una singola richiesta, quindi scorre le chiavi e restituisce ciascun punteggio che esiste.

local DataStoreService = game:GetService("DataStoreService")

local playerScores = DataStoreService:GetOrderedDataStore("PlayerScores")
local keys = {"Player_123", "Player_456", "Player_789"}

local success, results = pcall(function()
	return playerScores:BatchGetAsync(keys)
end)
if success then
	for _, key in keys do
		local entry = results[key]
		if entry then
			print(key .. " : " .. tostring(entry.value))
		else
			print(key .. " non ha voci salvate")
		end
	end
end