Magazzini di dati

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

Se vuoi aggiungere il controllo del permesso granulare ai tuoi archivi dati e accedervi al di fuori dei server Studio o Roblox, puoi usare Apri API cloud per gli archivi dati.

Per visualizzare e monitorare tutti i depositi di dati in un'esperienza attraverso il Hub Creatore, usa il Gestore depositi di dati.

Per i dati temporanei che devi aggiornare o accedere frequentemente, usa magazzini di memoria.

Abilita l'Accessoa Studio

Per impostazione predefinita, le esperienze testate in Studio non possono accedere ai depositi di dati, quindi devi prima abilitarle.Accedere ai depositi di dati in Studio può essere pericoloso per le esperienze dal vivo perché Studio accede agli stessi depositi di dati dell'applicazione client.Per evitare di sovrascrivere i dati di produzione, non abilitare questa impostazione per le esperienze dal vivo.Invece, abilitalo per una versione separata del test dell'esperienza.

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

1. Apri Impostazioni di gioco.
2. Navigate to Sicurezza .
3. Abilita il pulsante Abilita l'accesso Studio ai servizi API attivare/disattivare.
4. Fai clic su Salva .

Magazzini di dati di accesso

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

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

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

Crea dati

Un deposito di dati è essenzialmente un dizionario, simile a una tabella Luau.Un unico indice chiave indexa ogni valore nel data Negozio, come l'unico Player.UserId di un utente o una stringa nominata per una promozione dell'esperienza.

Per creare una nuova entry, 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

Aggiorna dati

Per modificare qualsiasi valore memorizzato in un Negoziodi dati, chiama UpdateAsync() con il nome della chiave dell'entrata e una funzione di richiamo che definisce come vuoi aggiornare l'entrata.Questo callback prende il valore attuale e restituisce un nuovo valore in base alla logica che definisci.Se il richiamo 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("Uppercase Name:", updatedName)
end

Set vs Aggiornarmento

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

• Può causare insincronia dei dati se due server tentano di impostare la stessa chiave allo stesso tempo
• Conta solo contro il limite di scrittura

Usa l'aggiornamento per gestire i tentativi multi-server. La funzione UpdateAsync() :

• Legge il valore attuale della chiave dal server che l'ha aggiornata per l'ultima volta prima di apportare qualsiasi modifica
• È più lento perché legge prima di scrivere
• Si conta contro entrambi i limiti di lettura e scrittura

Leggi dati

Per leggere il valore di un'entrata nel data store, 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

Aumenta i dati

Per incrementare un intero in un Negoziodati, chiama IncrementAsync() con il nome della chiave dell'elemento e un numero per quanto cambiare il valore.IncrementAsync() è una funzione conveniente che ti consente di evitare di chiamare UpdateAsync() e di aumentare manualmente l'Integro.

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

Rimuovi i dati

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

Esistono due tipi di metadati associati alle chiavi:

• Servizio definito : Metadati di lettura predefiniti, come l'ultimo tempo di aggiornamento e il tempo di creazione. Ogni oggetto ha metadati di lettura predefiniti dal servizio.
• Definito dall'utente : Metadati personalizzati per la marcatura e la categorizzazione. Definito utilizzando l'oggetto DataStoreSetOptions e la funzione SetMetadata().

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

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

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

  • Un oggetto DataStoreSetOptions dove puoi definire 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 DataStoreKeyInfo.Questo secondo valore contiene sia le proprietà e le funzioni definite dal servizio 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() 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 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 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 di richiamo di UpdateAsync() prende un parametro aggiuntivo nell'oggetto DataStoreKeyInfo che descrive lo stato della chiave attuale.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 i metadati, vedi i limiti dei metadati.

Magazzini di dati ordinati

Per impostazione predefinita, i depositi di dati non ordinano il loro contenuto.Se devi 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 dati ordinati supportano le stesse funzioni di base degli archivi dati predefiniti, più la funzione unica GetSortedAsync() .Questo recupera chiavi ordinate multiple in base a un ordine di classificazione specifico, alla dimensione della pagina e ai valori minimi/massimi.

L'esempio seguente ordina i dati del personaggio nelle pagine con tre voci, ciascuna in ordine decrescente, quindi passa attraverso le pagine e produce il nome e l'età di ciascun personaggio.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- Popola il deposito 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

-- Ordina i dati per ordine discendente in pagine di tre entrate 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 coppie chiave-valore sulla pagina
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Verifica se l'ultima pagina è stata raggiunta
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Avanzamenti alla pagina successiva
			pages:AdvanceToNextPageAsync()
		end
	end
end