Magazzini di dati

Il DataStoreService ti consente di memorizzare i dati che devono persistere tra le sessioni, come oggetti nell'inventario di un Giocatoreo punti abilità. I magazzini di dati sono coerenti per esperienza, quindi qualsiasi luogo in un'esperienza può accedere e modificare gli stessi dati, tra cui i luoghi su diversi server.

Se vuoi aggiungere il controllo granulare delle autorizzazioni ai tuoi dati e accedervi al di fuori dei server di Studio o Roblox, puoi usare Open Cloud API per i dati .

For temporary data that you need to update or access frequently, use archivi di memoria .

Abilitare l'accesso a Studio

Per impostazione predefinita, le esperienze testate in Studio non possono accedere ai negozi di dati, quindi devi prima abilitarli. L'accesso ai negozi di dati in Studio può essere pericoloso per le esperienze dal vivo, poiché Studio accede agli stessi negozi di dati come l'applicazione client. Per evitare di sovrascrivere i dati di produzione, non abilitare questa impostazione per le esperienze dal vivo. Invece, abilitalo per una versione di test separata dell'esperienza.

Per abilitare l'accesso a Studio in un'esperienza pubblicata :

1. Vai a Home > Impostazioni di gioco > Sicurezza .
2. Abilita il attivare/disattivare Abilita Studio Access to API Services .
3. Click Salva .

Accedere ai negozi di dati

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

1. Aggiungi DataStoreService a uno script lato server Script .
2. Usa la funzione GetDataStore()GetDataStore() e specifica il nome del data store che vuoi utilizzare. Se il data store non esiste, Studio crea uno quando salvi i dati di esperienza per la prima volta.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

Creazione di dati

Un archivio di dati è essenzialmente un dizionario, simile a una tabella Lua. Un unico chiave indice ogni valore nell'Negoziodei dati, come un unico Player.UserId o una stringa nome per una promo di esperienza.

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

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

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

Aggiornamento dei dati

Per cambiare qualsiasi valore memorizzato in un data Negozio, chiama UpdateAsync() con il nome della chiave dell'entrata e una funzione di chiamata che definisce come vuoi aggiornare l'entrata. Questa funzione di chiamata prende il valore corrente e restituisce un nuovo valore in base alla logica che definisci. Se la funzione di chiamata restituisce nil , l

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("Uppercase Name:", updatedName)
end

Imposta vs Aggiorna

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

• Può causare una non coerenza dei dati se due server tentano di impostare la stessa chiave allo stesso tempo
• Conteggia solo il limite di write

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

• Legge il valore della chiave corrente dal server che l'ha aggiornata per l'ultima volta prima di apportare qualsiasi cambiamento
• È più lento perché legge prima di scrivere
• Conta contro sia i limiti di lettura che di scrittura

Leggere i dati

Per leggere il valore di un'entrata del magazzino dei dati, chiama GetAsync() con il nome della chiave dell'entrata.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

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

Aumentare i dati

Per incrementare un numero in un Negoziodi dati, chiama IncrementAsync() con il nome della chiave e un numero per quanto cambiare il valore. IncrementAsync() è una funzione di convenienza che ti consente di evitare di chiamare Class.GlobalDataStore:UpdateAsync()|UpdateAsync

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

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

Rimozione dei dati

Per rimuovere un'entry 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:

• Servizio definito : Metadati di lettura predefiniti, come il più recente tempo di aggiornamento e creazione. Ogni oggetto ha un metadato di servizio.
• User-defined : Metadati personalizzati per la marcatura e la categorizzazione. Definiti utilizzando l'oggetto DataStoreSetOptions e la funzione SetMetadata().

Per gestire i metadati, espandi le funzioni SetAsync() , UpdateAsync() , GetAsync() e 1> Class.GlobalDataStore:RemoveAsync()|RemoveAsync()1> .

• SetAsync() accetta gli argomenti opzionali terzo e quarto:

  • Una tabella di UserIds . Questo può aiutare con il copyright del contenuto e la tracciabilità della proprietà intellettuale.

  • Un oggetto DataStoreSetOptions in cui puoi definire i metadati personalizzati utilizzando la funzione SetMetadata().

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

• GetAsync() , IncrementAsync() e RemoveAsync() restituiscono un secondo valore nell'oggetto 0> Class.DataStoreKeyInfo0> . Questo secondo valore contiene sia proprietà e funzioni definite dal servizio che metodi e fun

  • La funzione GetUserIds() recupera la tabella di UserIds che hai passato a SetAsync() .
  • La funzione GetMetadata() recupera i metadati utente che hai passato a SetAsync() attraverso SetMetadata() .
  • La proprietà Version recupera la versione della chiave.
  • La proprietà CreatedTime recupera il tempo in cui la chiave è stata creata, formattata come il numero di millisecondi dal momento dell'epoca.
  • La proprietà UpdatedTime ottiene l'ultimo volta che la chiave è stata aggiornata, formattata come il numero di millisecondi dal epoca.

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

• La funzione callback di UpdateAsync() prende un parametro aggiuntivo nell'oggetto DataStoreKeyInfo che descrive lo stato della chiave corrente. Ritorna il valore modificato, le chiavi associati con 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

For limiti quando si definisce il metadato, vedi Limiti del metadato .

Negozi di dati ordinati

Per impostazione predefinita, i magazzini di dati non classificano i loro contenuti. Se è necessario ottenere i dati in un modo ordinato, come nelle statistiche leaderboard persistenti, chiama GetOrderedDataStore() invece di GetDataStore() .

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

I negozi di dati ordinati supportano le stesse funzioni di base come i negozi di dati predefiniti, più la funzione unica GetSortedAsync() . Questo recupera più chiavi sortite in base a un ordine di sorting specifico, dimensione della pagina e valori minimi/massimi.

L'esempio seguente sortisce i dati dei personaggi in pagine con tre righe, ciascuna in ordine crescente, poi passa attraverso le pagine e gli script di ciascun personaggio e la sua età.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- Popola il magazzino di dati Negozio
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

-- Raggruppa i dati in ordine crescente in pagine da tre righe ciascuna
local success, pages = pcall(function()
	return characterAgeStore:GetSortedAsync(false, 3)
end)
if success then
	while true do
		-- Ottiene la pagina attuale (prima)
		local entries = pages:GetCurrentPage()
		-- itera attraverso tutti i paesi chiave-valore sulla pagina
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Controlla se la ultima pagina è stata raggiunta
		if pages.IsFinished then
			break
		else
			print("------")
			-- Avanzamenti alla prossima pagina
			pages:AdvanceToNextPageAsync()
		end
	end
end