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 i casi che richiedono una semplice memorizzazione dei dati e un 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 di chiavi più piccoli, ti consigliamo di utilizzare 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.
Inoltre, le mappe hash utilizzano gli stessi limiti di richiesta API e quota di memoria delle altre strutture dati degli store in memoria.
Ottenere 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
Dopo aver ottenuto una mappa hash, chiama una 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 chiave particolare. |
| 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 dettagliata su ciascuna funzione, vedi MemoryStoreHashMap.
Tutte le funzioni che accedono alle strutture dati negli store in memoria sono chiamate di rete asincrone che potrebbero occasionalmente fallire. Dovresti avvolgere queste chiamate in pcall() per catturare e gestire errori, come mostrato negli esempi di codice.
Aggiungere o sovrascrivere 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 massimo di scadenza è di 3.888.000 secondi (45 giorni).
Secondo il Regolamento generale sulla protezione dei dati (GDPR) dell'UE, se i tuoi store in memoria contengono dati utente soggetti al diritto all'oblio, devi rimuovere i dati entro 30 giorni, anche se imposti l'espirazione della chiave del tuo store in memoria fino a 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
Ottenere dati
Puoi ottenere un valore associato a una chiave specifica o ottenere più coppie chiave-valore nella mappa hash.
Ottenere 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
Ottenere dati con più coppie chiave-valore
Per ottenere tutte le coppie chiave-valore dalla mappa hash come singola 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 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
Aggiornare 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 in modo concorrente 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 callback.
Ad esempio, il seguente esempio di codice aggiorna il conteggio delle risorse di una risorsa in un inventario condiviso. UpdateAsync() assicura che tutti i contributi dei giocatori entreranno in questo inventario condiviso, anche se questi contributi vengono effettuati simultaneamente. In questa funzione, viene anche imposto un massimo di conteggio delle 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
La latenza per UpdateAsync() è simile a GetAsync() e SetAsync() a meno che non si verifichi una contesa.
Quando si verifica una contesa, il sistema prova automaticamente a ripetere l'operazione fino a quando uno di questi tre eventi si verifica: l'operazione ha successo, la funzione di callback restituisce nil o il numero massimo di tentativi è stato raggiunto. Se il sistema raggiunge il numero massimo di tentativi, restituisce un conflitto.
Rimuovere dati
Puoi usare MemoryStoreHashMap:RemoveAsync() sia per rimuovere una chiave dalla mappa hash sia per eliminare tutti i dati in una mappa hash dello store in memoria.
Rimuovere 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
Eliminare 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().
Eliminare 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