Hash-Maps, ähnlich wie sortierte Maps, ermöglichen es Ihnen, Daten im Speicher als Schlüssel-Wert-Paare zu speichern. Im Gegensatz zu sortierten Maps erhalten sie keine Ordnungsgarantien. Diese Datenstruktur ist nützlich für Fälle, die einfaches Daten-Caching und schnellen Zugriff erfordern, wie z. B. bei gemeinsamen Inventaren, physischen Auktionshäusern und mehr. Hash-Maps verwalten automatisch die Partitionierung Ihrer Daten und sind sehr nützlich, wenn Sie mehr als 1.000 Schlüssel haben. Für kleinere Schlüsselbereiche empfehlen wir sortierte Maps.
Einschränkungen
Hash-Maps haben eine Schlüsselgrößenbeschränkung von 128 Zeichen und eine Wertgrößenbeschränkung von 32 KB.
Ansonsten verwenden Hash-Maps die gleichen API-Anfragen und Speicherkontingent Beschränkungen wie die anderen Datenspeicherstrukturen.
Hash-Map abrufen
Um eine Hash-Map abzurufen, rufen Sie MemoryStoreService:GetHashMap() mit einem Namen für die Hash-Map auf. Der Name ist global innerhalb des Spiels, sodass Sie die gleiche Hash-Map in jedem Skript mit diesem Namen zugreifen können.
Abrufen einer Hash-Map
Nachdem Sie eine Hash-Map abgerufen haben, rufen Sie eine der folgenden Funktionen auf, um Daten darin zu lesen oder zu schreiben:
| Funktion | Aktion |
|---|---|
| MemoryStoreHashMap:SetAsync() | Fügen Sie hinzu einen neuen Schlüssel hinzu oder überschreiben Sie den Wert, wenn der Schlüssel bereits existiert. |
| MemoryStoreHashMap:GetAsync() | Lesen Sie einen bestimmten Schlüssel. |
| MemoryStoreHashMap:ListItemsAsync() | Listen Sie die Elemente in einer Hash-Map auf. |
| MemoryStoreHashMap:UpdateAsync() | Aktualisieren Sie den Wert eines Schlüssels, nachdem Sie ihn aus einer Hash-Map abgerufen haben. |
| MemoryStoreHashMap:RemoveAsync() | Entfernen Sie einen Schlüssel aus der Hash-Map. |
Für ausführliche Dokumentation zu jeder Funktion siehe MemoryStoreHashMap.
Alle Funktionen, die auf Datenstrukturen in Speichern zugreifen, sind asynchrone Netzwerkaufrufe, die gelegentlich fehlschlagen können. Sie sollten diese Aufrufe in pcall() einwickeln, um Fehler zu erfassen und zu behandeln, wie in den Beispielcodes gezeigt.
Daten hinzufügen oder überschreiben
Um einen neuen Schlüssel hinzuzufügen oder den Wert eines Schlüssels in der Hash-Map zu überschreiben, rufen Sie MemoryStoreHashMap:SetAsync() mit dem Schlüssel Namen, seinem Wert und einer Ablauffrist in Sekunden auf. Der Speicher räumt automatisch auf, sobald der Schlüssel abgelaufen ist. Die maximale Ablauffrist beträgt 3.888.000 Sekunden (45 Tage).
Gemäß der Datenschutz-Grundverordnung (DSGVO) der EU müssen Sie, wenn Ihre Speicherdaten Nutzerdaten unterliegen, die dem Recht auf Vergessenwerden unterliegen, die Daten innerhalb von 30 Tagen entfernen, selbst wenn Sie die Ablauffrist Ihres Schlüssels im Speicher auf bis zu 45 Tage gesetzt haben.
Daten zu einer Hash-Map hinzufügen
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 erfolgreich.")
end
Daten abrufen
Sie können entweder einen Wert abrufen, der mit einem bestimmten Schlüssel verknüpft ist, oder mehrere Schlüssel-Wert-Paare in der Hash-Map abrufen.
Daten mit einem Schlüssel abrufen
Um einen Wert abzurufen, der mit einem Schlüssel in der Hash-Map verknüpft ist, rufen Sie MemoryStoreHashMap:GetAsync() mit dem Schlüssel Namen auf.
Abrufen eines bestimmten Schlüssels aus einer Hash-Map
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 erfolgreich.")
end
local item
local getSuccess, getError = pcall(function()
item = hashMap:GetAsync("User_1234")
end)
if getSuccess then
print(item)
else
warn(getError)
end
Daten mit mehreren Schlüssel-Wert-Paaren abrufen
Um alle Schlüssel-Wert-Paare aus der Hash-Map in einem einzigen Vorgang zu erhalten, rufen Sie MemoryStoreHashMap:ListItemsAsync() mit der gewünschten Seitengröße auf. Diese Funktion listet alle vorhandenen Schlüssel paginiert auf. Zum Beispiel ruft der folgende Code bis zu 32 Elemente aus der Hash-Map ab.
Auflisten von Elementen in einer Hash-Map
local MemoryStoreService = game:GetService("MemoryStoreService")
local hashMap = MemoryStoreService:GetHashMap("HashMap1")
-- Liste von Elementen abrufen, 32 Elemente auf einmal
local success, pages = pcall(function()
return hashMap:ListItemsAsync(32)
end)
if success then
while true do
-- Aktuelle Seite abrufen
local entries = pages:GetCurrentPage()
-- Alle Schlüssel-Wert-Paare auf der Seite durchlaufen
for _, entry in ipairs(entries) do
print(entry.key .. " : " .. tostring(entry.value))
end
-- Überprüfen, ob die letzte Seite erreicht wurde
if pages.IsFinished then
break
else
print("----------")
-- Gehe zur nächsten Seite
pages:AdvanceToNextPageAsync()
end
end
end
Daten aktualisieren
Um den Wert eines Schlüssels aus einer Hash-Map abzurufen und diesen zu aktualisieren, rufen Sie MemoryStoreHashMap:UpdateAsync() mit dem Schlüssel Namen, einer Callback-Funktion, um den Schlüssel zu aktualisieren, und einer Ablauffrist in Sekunden auf.
Für die meisten Spiele können mehrere Server den gleichen Schlüssel gleichzeitig aktualisieren und den Wert ändern. Da UpdateAsync() immer den neuesten Wert vor der Aktualisierung ändert, sollten Sie es verwenden, um den neuesten Wert als Eingabe für Ihre Callback-Funktion zu lesen.
Zum Beispiel aktualisiert der folgende Code-Schnipsel die Ressourcenzahl einer Ressource in einem gemeinsamen Inventar. UpdateAsync() sorgt dafür, dass alle Spielerbeiträge in dieses gemeinsame Inventar gelangen, selbst wenn diese Beiträge gleichzeitig gemacht werden. In dieser Funktion wird auch eine maximale Ressourcenzahl von 500 durchgesetzt.
Aktualisierung der Ressourcenzahl für eine Ressource in einem gemeinsamen Inventar
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
-- Stellen Sie sicher, dass wir die maximale Ressourcenzahl nicht überschreiten
if resource.count > 500 then
resource.count = 500
end
return resource
end, 1200)
end)
if success then
print(newResourceCount)
end
end
Die Latenz für UpdateAsync() ist ähnlich wie die von GetAsync() und SetAsync() es sei denn, es gibt Konkurrenz.
Wenn Konkurrenz auftritt, versucht das System die Operation automatisch, bis eine dieser drei Bedingungen erfüllt ist: die Operation ist erfolgreich, die Callback-Funktion gibt nil zurück, oder die maximale Anzahl an Wiederholungen ist erreicht. Wenn das System die maximale Anzahl an Wiederholungen erreicht, gibt es einen Konflikt zurück.
Daten entfernen
Sie können MemoryStoreHashMap:RemoveAsync() sowohl für das Entfernen eines Schlüssels aus der Hash-Map als auch für das Löschen aller Daten in einer Speicher-Hash-Map verwenden.
Einen Schlüssel entfernen
Um einen Schlüssel aus der Hash-Map zu entfernen, rufen Sie MemoryStoreHashMap:RemoveAsync() mit einem Schlüssel namen auf.
Einen Schlüssel aus einer Hash-Map entfernen
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 erfolgreich.")
end
local removeSuccess, removeError = pcall(function()
hashMap:RemoveAsync("User_1234")
end)
if not removeSuccess then
warn(removeError)
end
Alle Daten löschen
Um alle Daten in einer Hash-Map zu löschen, listen Sie alle Ihre Elemente mit MemoryStoreHashMap:ListItemsAsync() auf und entfernen Sie sie dann mit MemoryStoreHashMap:RemoveAsync().
Alle Daten in einer Hash-Map löschen
local MemoryStoreService = game:GetService("MemoryStoreService")
local hashMap = MemoryStoreService:GetHashMap("HashMap1")
-- Liste von Elementen abrufen, 32 Elemente auf einmal
local success, pages = pcall(function()
return hashMap:ListItemsAsync(32)
end)
if success then
while true do
-- Aktuelle Seite abrufen
local entries = pages:GetCurrentPage()
local removeSuccess = true
local removeError = nil
-- Alle Schlüssel-Wert-Paare auf der Seite durchlaufen
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
-- Überprüfen, ob die letzte Seite erreicht wurde
if pages.IsFinished then
print("Fertig mit dem Löschen aller Daten.")
break
else
print("----------")
-- Gehe zur nächsten Seite
pages:AdvanceToNextPageAsync()
end
end
end