Sortierte Karten im Speichersystem

Die sortierte Karte-Datenstruktur von Speicherstellen ermöglicht es Ihnen, häufige Daten im Arbeitsspeicher als Schlüssel-Wert-Paare mit einem optionalen Sortierschlüssel zu speichern und eine bestimmte Reihenfolge auf der Grundlage der Sortierschlüssel und Schlüssel aufrechtzuerhalten. Im Gegensatz zu Warteschlangen bestimmt die Reihenfolge der Schlüssel, die in eine Karte eingehen, nicht die Reihenfolge der Verarbeitung, was sortierte Karten nützlich macht für die Organisation von Daten zur Implementierung von Spiel-Entitäten für Engagement, wie z.B. Bestenlisten und serverübergreifendes Auktionieren.

Grenzen

Neben den Größenbeschränkungen für Datenstrukturen haben sortierte Karten eine Schlüsselgrößenbeschränkung von 128 Zeichen, eine Wertegröße von 32 KB und eine Sortierschlüsselgröße von 128 Zeichen.

Wenn Sie Daten speichern müssen, die diese Grenze für Ihr Spiel überschreiten, können Sie die Sharding-Technik anwenden, um sie durch Schlüsselpräfix auf mehrere Datenstrukturen aufzuteilen und zu verteilen. Das Sharding von Speicherstellen kann auch helfen, die Skalierbarkeit Ihres Systems zu verbessern.

Eine sortierte Karte abrufen

Um eine sortierte Karte abzurufen, rufen Sie MemoryStoreService:GetSortedMap() mit einem Namen auf, den Sie für die Karte definieren möchten. Der Name ist global innerhalb des Spiels, sodass Sie die gleiche sortierte Karte in jedem Skript mit dem Namen darauf zugreifen können.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

Nachdem Sie eine sortierte Karte abgerufen haben, können Sie eine der folgenden Funktionen aufrufen:

Daten hinzufügen oder überschreiben

Um einen neuen Schlüssel hinzuzufügen oder den Wert oder Sortierschlüssel eines Schlüssels in der sortierten Karte zu überschreiben, rufen Sie MemoryStoreSortedMap:SetAsync() mit dem Schlüssel Namen, seinem Wert, einer Ablaufrate in Sekunden und einem optionalem Sortierschlüssel auf. Der Speicher bereinigt automatisch, sobald der Schlüssel abläuft. Die maximale Ablaufrate beträgt 3.888.000 Sekunden (45 Tage). Der Sortierschlüssel, falls bereitgestellt, muss eine gültige Zahl (ganzzahlig oder fließend) oder eine Zeichenfolge sein.

In der Sortierreihenfolge Ihrer Schlüssel hat ein Sortierschlüssel Vorrang vor einem Schlüssel. Beispielsweise sortieren bei aufsteigender Reihenfolge numerische Sortierschlüssel zuerst, gefolgt von Zeichenfolgen-Sortierschlüsseln, gefolgt von Elementen ohne Sortierschlüssel. Alle Elemente mit numerischen Sortierschlüsseln werden nach Sortierschlüssel sortiert. Wenn der Sortierschlüssel für zwei Elemente gleich ist, werden sie nach Schlüssel sortiert. Ähnlich werden alle Elemente mit Zeichenfolgen-Sortierschlüsseln nach Sortierschlüssel sortiert. Wenn der Sortierschlüssel für zwei Elemente gleich ist, werden sie nach Schlüssel sortiert. Alle Elemente ohne Sortierschlüssel werden nur nach dem Schlüssel sortiert.

Beispiel von einigen Daten, die in aufsteigender Reihenfolge sortiert sind -

{key: "player1", value: someValue1, sortKey: -1}
{key: "player2", value: someValue2, sortKey: 0}
{key: "player4", value: someValue3, sortKey: 1}
{key: "player5", value: someValue4, sortKey: 1}
{key: "player3", value: someValue5, sortKey: 3.14}
{key: "player6", value: someValue6, sortKey: "someString"}
{key: "player0", value: someValue7}
{key: "player7", value: someValue8}

Beachten Sie, wie player0 nach allen Schlüsseln mit einem Sortierschlüssel sortiert wird. player6 sortiert nach allen Schlüsseln mit einem numerischen Sortierschlüssel. player4 und player5 haben den gleichen Sortierschlüssel, daher werden sie in aufsteigender Reihenfolge nach Schlüssel sortiert.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

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

Daten abrufen

Sie können entweder einen Datenwert und Sortierschlüssel abzurufen, der mit einem bestimmten Schlüssel verbunden ist, oder mehrere Werte und Sortierschlüssel für Schlüssel innerhalb eines Bereichs abrufen.

Daten mit einem Schlüssel abrufen

Um einen Wert und Sortierschlüssel abzurufen, der mit einem Schlüssel aus der sortierten Karte verbunden ist, rufen Sie MemoryStoreSortedMap:GetAsync() mit dem Schlüssel Namen auf.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

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

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

Daten mit mehreren Schlüsseln abrufen

Um Daten für mehrere Schlüssel aus der sortierten Karte als eine einzige Operation abzurufen, rufen Sie MemoryStoreSortedMap:GetRangeAsync() auf. Diese Funktion listet standardmäßig alle vorhandenen Schlüssel auf, aber Sie können die oberen und unteren Grenzen für den Schlüsselbereich festlegen. Beispielsweise ruft das folgende Codebeispiel bis zu 20 Elemente ab, die am Anfang der sortierten Karte beginnen, mit Schlüsseln, die größer oder gleich 10 sind, Sortierschlüsseln, die größer oder gleich 100 sind, und Schlüsseln, die kleiner oder gleich 50 und Sortierschlüsseln sind, die kleiner oder gleich 500 sind.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

local lowerBound = {}
lowerBound["key"] = "10"
lowerBound["sortKey"] = 100
local upperBound = {}
upperBound["key"] = "50"
upperBound["sortKey"] = 500

-- Holen Sie sich bis zu 20 Elemente, die am Anfang beginnen
local getSuccess, items = pcall(function()
	return sortedMap:GetRangeAsync(
		Enum.SortDirection.Ascending, 20, lowerBound, upperBound)
end)
if getSuccess then
	for _, item in items do
		print(item.key)
		print(item.sortKey)
	end
end

Daten aktualisieren

Um den Wert und Sortierschlüssel eines Schlüssels aus einer sortierten Karte abzurufen und ihn zu aktualisieren, rufen Sie MemoryStoreSortedMap:UpdateAsync() mit dem Schlüssel Namen, einer Rückruffunktion zum Aktualisieren des Wertes und Sortierschlüssels für diesen Schlüssel und einer Ablaufrate in Sekunden auf. Die maximale Ablaufrate beträgt 3.888.000 Sekunden (45 Tage).

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 es verwenden, um den neuesten Wert als Eingabe für Ihre Rückruffunktion zu lesen.

Zum Beispiel aktualisiert das folgende Codebeispiel die Punktzahl in einer Bestenliste für einen Spieler. Die Punktzahl wird als Kills / Tode berechnet. UpdateAsync() stellt sicher, dass die Kills und Tode auf die aktuellsten Werte aktualisiert werden, selbst wenn mehrere Spieleserver gleichzeitig dasselbe Element aktualisieren. Die Kills und Tode eines Spielers sind monoton wachsende Werte und können daher nur in einem Spielverlauf ansteigen.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("Leaderboard")

local function updateLeaderboard(itemKey, killsToAdd, deathsToAdd)
	local success, newStats, newScore = pcall(function()
		return sortedMap:UpdateAsync(itemKey, function(playerStats, playerScore)
			playerStats = playerStats or { kills = 0, deaths = 0 }
			playerStats.kills += killsToAdd
			playerStats.deaths += deathsToAdd
			if playerStats then
				-- `playerScore` ist der Sortierschlüssel, der zum Sortieren der Elemente in der Karte verwendet wird
				playerScore = playerStats.kills / math.max(playerStats.deaths, 1)
				return playerStats, playerScore
			end
			return nil
		end, 30)
	end)
	if success then
		print(newStats)
		print(newScore)
	end
end

Die Latenz für UpdateAsync() ist ähnlich wie bei GetAsync() und SetAsync(), es sei denn, es gibt Konflikte.

Bei Konflikten versucht das System automatisch, den Vorgang erneut durchzuführen, bis eines der drei Folgendes eintritt: der Vorgang erfolgreich ist, die Rückruffunktion nil zurückgibt oder die maximale Anzahl von Versuchen erreicht wird. Wenn das System die maximale Anzahl von Versuchen erzielt, gibt es einen Konflikt zurück.

Daten entfernen

Sie können MemoryStoreSortedMap:RemoveAsync() sowohl zum Entfernen eines Schlüssels aus der sortierten Karte als auch zum Löschen aller Daten in einer Speicherstelle-sortierten Karte verwenden.

Einen Schlüssel entfernen

Um einen Schlüssel aus der sortierten Karte zu entfernen, rufen Sie MemoryStoreSortedMap:RemoveAsync() mit einem Schlüssel Namen auf.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

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

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

Alle Daten löschen

Um den Speicher in sortierten Karten zu löschen, listen Sie alle Ihre Schlüssel mit MemoryStoreSortedMap:GetRangeAsync(), und entfernen Sie sie dann mit MemoryStoreSortedMap:RemoveAsync().

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

-- Anfangs untere Grenze von nil startet die Löschung vom ersten Element
local exclusiveLowerBound = nil

while true do
	-- Holen Sie sich bis zu hundert Elemente, die von der aktuellen unteren Grenze starten
	local getRangeSuccess, items = pcall(function()
		return sortedMap:GetRangeAsync(Enum.SortDirection.Ascending, 100, exclusiveLowerBound)
	end)
	if getRangeSuccess then
		local removeSuccess = true
		local removeError = nil

		for _, item in items do
			removeSuccess, removeError = pcall(function()
				sortedMap:RemoveAsync(item.key)
			end)
		end

		-- Wenn ein Fehler beim Entfernen von Elementen aufgetreten ist, versuchen Sie es erneut mit der gleichen exklusive unteren Grenze
		if not removeSuccess then
			warn(removeError)
		-- Wenn der Bereich weniger als hundert Elemente umfasst, ist das Ende der Karte erreicht
		elseif #items < 100 then
			break
		else
			-- Der letzte abgerufene Schlüssel ist die exklusive untere Grenze für die nächste Iteration
			exclusiveLowerBound = {}
			exclusiveLowerBound["key"] = items[#items].key
			exclusiveLowerBound["sortKey"] = items[#items].sortKey
		end
	end
end

Größe abrufen

Um die Anzahl der Elemente in der sortierten Karte zu erhalten, rufen Sie MemoryStoreSortedMap:GetSizeAsync() auf.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

local setSuccess, _ = pcall(function()
	return sortedMap:SetAsync("User_1234", 1000, 30, 3.14152)
end)

if setSuccess then
	print("Set erfolgreich.")
end

local size
local success, sizError = pcall(function()
	size = sortedMap:GetSizeAsync()
end)

if success then
	print(size)
else
	warn(sizeError)
end