Mappa hash del deposito di memoria

Mappe di hash , simili alle mappe ordinate, ti consentono di archiviare dati in memoria come coppie chiave-valore.A differenza delle mappe ordinate, non mantengono garanzie di ordinamento.Questa struttura di dati è utile per casi che richiedono una semplice memorizzazione dei dati e un rapido Accesso, come inventari condivisi, case d'asta fisiche e altro ancora.Le mappe hash gestiscono automaticamente la partizione dei dati e sono molto utili se hai più di 1.000 chiavi.Per gli spazi di chiave più piccoli, raccomandiamo mappe ordinate .

Limitazioni

Le mappe hash hanno un limite di dimensione della chiave di 128 caratteri e un limite di dimensione del valore di 32 KB.

Altrimenti, le mappe di hash utilizzano gli stessi richiesta API e limiti di memoria come le altre strutture di dati del deposito di memoria.

Ottieni una mappa di hash

Per ottenere una mappa di hash, chiama MemoryStoreService:GetHashMap() con un nome per la mappa di hash.Il nome è globale all'interno dell'esperienza, quindi puoi accedere alla stessa mappa di hash su qualsiasi script utilizzando questo nome.

Ottenere una mappa hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

Dopo aver ottenuto una mappa di hash, chiama una qualsiasi delle seguenti funzioni per leggere o scrivere dati in essa:

Per una documentazione approfondita su ciascuna funzione, vedi MemoryStoreHashMap.

Aggiungi o sovrascrivi i dati

Per aggiungere una nuova chiave o sovrascrivere il valore di una chiave nella mappa hash, chiama MemoryStoreHashMap:SetAsync() con la chiave nome , il suo valore e un tempo di scadenza in secondi.La memoria si pulisce automaticamente una volta che la chiave scade.Il tempo massimo di scadenza è 3,888,000 secondi (45 giorni).

Aggiungere dati a una mappa hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

local setSuccess, _ = pcall(function()
	return hashMap:SetAsync("User_1234", 1000, 30)
end)
if setSuccess then
	print("Set succeeded.")
end

Ottieni dati

Puoi ottenere un valore associato a una chiave specifica o ottenere più coppie chiave-valore nella mappa hash.

Ottieni dati con una chiave

Per ottenere un valore associato a una chiave dalla mappa hash, chiama MemoryStoreHashMap:GetAsync() con il nome chiave .

Ottenere una chiave particolare da una mappa hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

local setSuccess, _ = pcall(function()
	return hashMap:SetAsync("User_1234", 1000, 30)
end)
if setSuccess then
	print("Set succeeded.")
end

local item
local getSuccess, getError = pcall(function()
	item = hashMap:GetAsync("User_1234")
end)
if getSuccess then
	print(item)
else
	warn(getError)
end

Ottieni dati con più coppie chiave-valore

Per ottenere tutti i coppie chiave-valore dalla mappa hash come un'unica operazione, chiama MemoryStoreHashMap:ListItemsAsync() con la dimensione della pagina desiderata.Questa funzione elenca tutte le chiavi esistenti in modo paginato.Ad esempio, il seguente esempio di codice recupera fino a 32 elementi dalla mappa hash.

Elencare gli elementi in una mappa Hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Ottieni l'elenco degli elementi, 32 elementi alla volta
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Ottieni la pagina attuale
		local entries = pages:GetCurrentPage()
		-- Iterare attraverso tutti i coppie chiave-valore sulla pagina
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Verifica se l'ultima pagina è stata raggiunta
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Passa alla pagina successiva
			pages:AdvanceToNextPageAsync()
		end
	end
end

Aggiorna dati

Per recuperare il valore di una chiave da una mappa hash e aggiornarlo, chiama con il nome della chiave , una funzione di richiamo per aggiornare la chiave e un tempo di scadenza in secondi.

Per la maggior parte delle esperienze, più server possono aggiornare la stessa chiave contemporaneamente e cambiare il valore.Poiché UpdateAsync() modifica sempre l'ultimo valore prima di aggiornare, dovresti usarlo per leggere l'ultimo valore come input per la tua funzione di richiamo.

Ad esempio, il seguente esempio di codice aggiorna il conteggio delle risorse di una risorsa in un Inventario, reportoriocondiviso.UpdateAsync() garantisce che tutte le contribuzioni del giocatore faranno parte di questo Inventario, reportoriocondiviso, anche se queste contribuzioni vengono effettuate simultaneamente.In questa funzione, imposta anche un conteggio massimo di risorse di 500.

Aggiornamento del conteggio delle risorse per una risorsa in un inventario condiviso
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("ResourceInventory")

local function contributeResources(itemResource, addedCount)
	local success, newResourceCount = pcall(function()
		return hashMap:UpdateAsync(itemResource, function(resource)
			resource = resource or {count = 0}
			resource.count = resource.count + addedCount

			-- assicurati di non superare il conteggio massimo delle risorse
			if resource.count > 500 then
				resource.count = 500
			end
			return resource
		end, 1200)
	end)
	if success then
		print(newResourceCount)
	end
end

Il ritardo per UpdateAsync() è simile a GetAsync() e SetAsync() a meno che non ci sia una concorrenza.

Quando si verifica una concorrenza, il sistema riprova automaticamente l'operazione fino a quando uno di questi tre eventi non accade: l'operazione ha successo, la funzione di richiamo restituisce nil , o si raggiunge il numero massimo di riprobi.Se il sistema raggiunge il numero massimo di riprobi, restituisce un conflitto.

Rimuovi i dati

Puoi usare MemoryStoreHashMap:RemoveAsync() per entrambi rimuovere una chiave dalla mappa hash e eliminare tutti i dati in una mappa hash del deposito di memoria.

Rimuovi una chiave

Per rimuovere una chiave dalla mappa hash, chiama MemoryStoreHashMap:RemoveAsync() con un nome chiave . .

Rimuovi una chiave da una mappa hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

local setSuccess, _ = pcall(function()
	return hashMap:SetAsync("User_1234", 1000, 30)
end)
if setSuccess then
	print("Set succeeded.")
end

local removeSuccess, removeError = pcall(function()
	hashMap:RemoveAsync("User_1234")
end)
if not removeSuccess then
	warn(removeError)
end

Elimina tutti i dati

Per eliminare tutti i dati in una mappa hash, elenca tutti i tuoi oggetti con MemoryStoreHashMap:ListItemsAsync() , quindi rimuovili con MemoryStoreHashMap:RemoveAsync() .

Elimina tutti i dati in una mappa Hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Ottieni l'elenco degli elementi, 32 elementi alla volta
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Ottieni la pagina attuale
		local entries = pages:GetCurrentPage()
		local removeSuccess = true
		local removeError = nil
		-- Iterare attraverso tutti i coppie chiave-valore sulla pagina
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
			removeSuccess, removeError = pcall(function()
				hashMap:RemoveAsync(entry.key)
			end)

			if not removeSuccess then
				warn(removeError)
			end
		end
		-- Verifica se l'ultima pagina è stata raggiunta
		if pages.IsFinished then
			print("Finished deleting all data.")
			break
		else
			print("----------")
			-- Passa alla pagina successiva
			pages:AdvanceToNextPageAsync()
		end
	end
end