Mappa hash del negozio di memoria | Documentazione

Le mappe hash, simili alle mappe ordinate, ti permettono di memorizzare dati in memoria come coppie chiave-valore. A differenza delle mappe ordinate, non mantengono garanzie di ordinamento. Questa struttura dati è utile per casi che richiedono una semplice memorizzazione dei dati e accesso rapido, come inventari condivisi, case d'asta fisiche e altro ancora. Le mappe hash gestiscono automaticamente il partizionamento dei tuoi dati e sono molto utili se hai più di 1.000 chiavi. Per spazi chiave più piccoli, ti consigliamo le mappe ordinate.

Limiti

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

Diversamente, le mappe hash utilizzano gli stessi limiti di richiesta API e quota di memoria delle altre strutture dati del negozio di memoria.

Ottieni una mappa hash

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

Ottenere una Mappa Hash

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

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

Funzione	Azioni
MemoryStoreHashMap:SetAsync()	Aggiungi una nuova chiave o sovrascrivi il valore se la chiave esiste già.
MemoryStoreHashMap:GetAsync()	Leggi una particolare chiave.
MemoryStoreHashMap:ListItemsAsync()	Elenca gli elementi in una mappa hash.
MemoryStoreHashMap:UpdateAsync()	Aggiorna il valore di una chiave dopo averla recuperata da una mappa hash.
MemoryStoreHashMap:RemoveAsync()	Rimuovi una chiave dalla mappa hash.

Per documentazione approfondita su ciascuna funzione, consulta MemoryStoreHashMap.

Tutte le funzioni che accedono a strutture dati nei negozi di memoria sono chiamate di rete asincrone che potrebbero occasionalmente fallire. Dovresti racchiudere queste chiamate in pcall() per catturare e gestire errori, come mostrato nei campioni di codice.

Aggiungi o sovrascrivi dati

Per aggiungere una nuova chiave o sovrascrivere il valore di una chiave nella mappa hash, chiama MemoryStoreHashMap:SetAsync() con il nome della chiave, il suo valore, e un tempo di scadenza in secondi. La memoria pulisce automaticamente una volta che la chiave scade. Il tempo di scadenza massimo è di 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("Impostazione riuscita.")
end

Ottieni dati

Puoi ottenere sia un valore associato a una chiave specifica, sia 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 della 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("Impostazione riuscita.")
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 tutte le 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 campione 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 elenco di elementi, 32 elementi alla volta
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Ottieni la pagina corrente
		local entries = pages:GetCurrentPage()
		-- Itera attraverso tutte le coppie chiave-valore nella pagina
		for _, entry in ipairs(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

Aggiorna dati

Per recuperare il valore di una chiave da una mappa hash e aggiornarlo, chiama MemoryStoreHashMap:UpdateAsync() con il nome della chiave, una funzione di callback per aggiornare la chiave e un tempo di scadenza in secondi.

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

Ad esempio, il seguente campione di codice aggiorna il conteggio delle risorse di una risorsa in un inventario condiviso. UpdateAsync() garantisce che tutti i contributi dei giocatori si riflettano in questo inventario condiviso, anche se questi contributi vengono effettuati simultaneamente. In questa funzione, impone anche un conteggio massimo delle risorse di 500.

Aggiornare il Conteggio 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

La latenza per UpdateAsync() è simile a GetAsync() e SetAsync() a meno che non ci sia contesa.

Quando si verifica contesa, il sistema ripete automaticamente l'operazione fino a quando una di queste tre cose accade: l'operazione riesce, la funzione di callback restituisce nil, o il numero massimo di tentativi è raggiunto. Se il sistema raggiunge il numero massimo di tentativi, restituisce un conflitto.

Rimuovi dati

Puoi usare MemoryStoreHashMap:RemoveAsync() sia per rimuovere una chiave dalla mappa hash che per eliminare tutti i dati in una mappa hash del negozio di memoria.

Rimuovi una chiave

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

Rimuovere 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("Impostazione riuscita.")
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 elementi 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 elenco di elementi, 32 elementi alla volta
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Ottieni la pagina corrente
		local entries = pages:GetCurrentPage()
		local removeSuccess = true
		local removeError = nil
		-- Itera attraverso tutte le coppie chiave-valore nella 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
		-- Controlla se è stata raggiunta l'ultima pagina
		if pages.IsFinished then
			print("Eliminazione di tutti i dati completata.")
			break
		else
			print("----------")
			-- Avanza alla pagina successiva
			pages:AdvanceToNextPageAsync()
		end
	end
end