Speicher-Store-Hashmap

Hashmaps, ähnlich wie sortierte Maps, ermöglichen es Ihnen, Daten im Speicher als Schlüssel-Wert-Paare zu speichern. Im Gegensatz zu sortierten Maps bieten sie keine Sortierungsgarantien. Diese Datenstruktur ist nützlich für Fälle, die einfaches Daten-Caching und schnellen Zugriff erfordern, wie z. B. gemeinsame Inventare, physische Auktionshäuser und mehr. Hashmaps verwalten automatisch die Partitionierung Ihrer Daten und sind sehr nützlich, wenn Sie mehr als 1.000 Schlüssel haben. Für kleinere Schlüsselräume empfehlen wir sortierte Maps.

Grenzen

Hashmaps haben eine Schlüsselgrößengrenze von 128 Zeichen und eine Wertgrößengrenze von 32 KB.

Ansonsten verwenden Hashmaps die gleichen API-Anforderungs und Speicherquoten wie die anderen Datenstrukturen im Speicher-Store.

Eine Hashmap abrufen

Um eine Hashmap abzurufen, rufen Sie MemoryStoreService:GetHashMap() mit einem Namen für die Hashmap auf. Der Name ist global im Spiel, sodass Sie auf dieselbe Hashmap in jedem Skript mit diesem Namen zugreifen können.

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

Nachdem Sie eine Hashmap erhalten haben, rufen Sie eine der folgenden Funktionen auf, um Daten darin zu lesen oder zu schreiben:

Für ausführliche Dokumentationen zu jeder Funktion siehe MemoryStoreHashMap.

Daten hinzufügen oder überschreiben

Um einen neuen Schlüssel hinzuzufügen oder den Wert eines Schlüssels in der Hashmap zu überschreiben, rufen Sie MemoryStoreHashMap:SetAsync() mit dem Schlüsselnamen, seinem Wert und einer Ablaufzeit in Sekunden auf. Der Speicher wird automatisch aufgeräumt, sobald der Schlüssel abläuft. Die maximale Ablaufzeit beträgt 3.888.000 Sekunden (45 Tage).

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("Setzen 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 Hashmap abrufen.

Daten mit einem Schlüssel abrufen

Um einen Wert abzurufen, der mit einem Schlüssel aus der Hashmap verknüpft ist, rufen Sie MemoryStoreHashMap:GetAsync() mit dem Schlüsselnamen auf.

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("Setzen 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 Hashmap in einem einzelnen Vorgang abzurufen, rufen Sie MemoryStoreHashMap:ListItemsAsync() mit der gewünschten Seitengröße auf. Diese Funktion listet alle vorhandenen Schlüssel in paginierter Form auf. Zum Beispiel ruft die folgende Codeprobe bis zu 32 Elemente aus der Hashmap ab.

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Liste von Artikeln abrufen, 32 Artikel 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()
		-- Durch alle Schlüssel-Wert-Paare auf der Seite iterieren
		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("----------")
			-- Zur nächsten Seite weiterblättern
			pages:AdvanceToNextPageAsync()
		end
	end
end

Daten aktualisieren

Um den Wert eines Schlüssels aus einer Hashmap abzurufen und zu aktualisieren, rufen Sie MemoryStoreHashMap:UpdateAsync() mit dem Schlüsselnamen, einer Callback-Funktion zur Aktualisierung des Schlüssels und einer Ablaufzeit in Sekunden auf.

Für die meisten Spiele können mehrere Server denselben Schlüssel gleichzeitig aktualisieren und den Wert ändern. Da UpdateAsync() immer den neuesten Wert vor der Aktualisierung ändert, sollten Sie diese Funktion verwenden, um den neuesten Wert als Eingabe für Ihre Callback-Funktion zu lesen.

Zum Beispiel aktualisiert die folgende Codeprobe die Ressourcenanzahl einer Ressource in einem gemeinsamen Inventar. UpdateAsync() stellt sicher, dass alle Spielerbeiträge in dieses gemeinsame Inventar gelangen, selbst wenn diese Beiträge gleichzeitig geleistet werden. In dieser Funktion wird außerdem eine maximale Ressourcenanzahl von 500 durchgesetzt.

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

			-- sicherstellen, dass wir die maximale Ressourcenanzahl 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 GetAsync() und SetAsync(), es sei denn, es liegt eine Konkurrenzsituation vor.

Wenn es zu Konflikten kommt, versucht das System automatisch, den Vorgang erneut auszuführen, bis einer dieser drei Fälle eintritt: der Vorgang wird erfolgreich ausgeführt, die Callback-Funktion gibt nil zurück oder die maximale Anzahl an Wiederholungen wird 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 von der Hashmap als auch für das Löschen aller Daten in einer Speicher-Store-Hashmap verwenden.

Einen Schlüssel entfernen

Um einen Schlüssel aus der Hashmap zu entfernen, rufen Sie MemoryStoreHashMap:RemoveAsync() mit einem Schlüsselnamen auf.

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("Setzen 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 Hashmap zu löschen, listen Sie alle Ihre Artikel mit MemoryStoreHashMap:ListItemsAsync(), und entfernen Sie diese dann mit MemoryStoreHashMap:RemoveAsync().

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Liste von Artikeln abrufen, 32 Artikel 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
		-- Durch alle Schlüssel-Wert-Paare auf der Seite iterieren
		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("Alle Daten gelöscht.")
			break
		else
			print("----------")
			-- Zur nächsten Seite weiterblättern
			pages:AdvanceToNextPageAsync()
		end
	end
end