Archivi di dati

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

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

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

Per i 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 di dati, quindi devi prima abilitarli. Accedere agli archivi di dati in Studio può essere pericoloso per i giochi in produzione poiché Studio accede agli stessi archivi di dati dell'applicazione client. Per evitare di sovrascrivere dati di produzione, non abilitare questa impostazione per i giochi in produzione. Invece, attivala per una versione di test separata del gioco.

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

1. Apri la finestra File ⟩ Impostazioni dell'esperienza di Studio.
2. Vai su Sicurezza.
3. Abilita l'interruttore Abilita accesso a Studio per API Services.
4. Fai clic su Salva.

Accedere agli archivi di dati

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

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

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

Creare dati

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

Per creare una nuova voce, richiama 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 cambiare qualsiasi valore memorizzato in un archivio di dati, chiama UpdateAsync() con il nome della chiave di ingresso e una funzione di callback che definisce come vuoi aggiornare l'entrata. Questa callback prende il valore attuale e restituisce un nuovo valore basato sulla 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 Maiuscole:", updatedName)
end

Set vs update

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 attuale della chiave dal server che l'ha aggiornata per ultimo prima di apportare modifiche
• È più lenta perché legge prima di scrivere
• Conta sia contro i limiti di lettura che di scrittura

Leggere i dati

Per leggere il valore di un'entrata di un archivio di dati, chiama GetAsync() con il nome della chiave di ingresso.

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 di dati, chiama IncrementAsync() con il nome della chiave di ingresso e un numero che indica quanto cambiare il valore. IncrementAsync() è una funzione di convenienza che ti consente di evitare di chiamare UpdateAsync() e di 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 un'entrata e restituire il valore associato con la 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 nel tracciamento e nella rimozione della proprietà intellettuale e dei diritti d'autore dei contenuti.

  • 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 proprietà definite dal servizio sia 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 la chiave è stata creata, formattata come numero di millisecondi dall'epoch.
  • La proprietà UpdatedTime recupera l'ultima volta in cui la chiave è stata aggiornata, formattata come numero di millisecondi dall'epoch.

  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 quando si definiscono metadati, vedere i limiti dei metadati.

Archivi di dati ordinati

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

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

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

Il seguente esempio ordina i dati sui personaggi in pagine con tre voci, ciascuna in ordine decrescente, quindi scorre attraverso 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 dati ordinato
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