Speicherstore sortierte Karte

Die sortierte Karte-Datenstruktur von Speicherstores ermöglicht es Ihnen, häufige im Speicher gespeicherte Daten als Schlüssel-Wert-Paare mit einem optionalen Sortierschlüssel zu speichern und eine spezifische Reihenfolge basierend auf den Sortierschlüsseln und Schlüsseln 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 für die Organisation von datensortierten Implementierungen für Spiel-Entitäten wie Ranglisten und serverübergreifende Auktionen macht.

Limits

Zusätzlich zu den Limits der Datenstrukturgrößen haben sortierte Karten ein Schlüssellimit von 128 Zeichen, ein Werteslimit von 32 KB und ein Sortierschlüssel-Limit von 128 Zeichen.

Wenn Sie Daten speichern müssen, die dieses Limit für Ihr Spiel überschreiten, können Sie die Sharding-Technik anwenden, um sie über Schlüsselpräfixe in mehrere Datenstrukturen zu splitten und zu verteilen. Das Sharding von Speicherstores 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 aufrufen können.

Eine sortierte Karte abrufen
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

Nachdem Sie eine sortierte Karte erhalten 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 Ablaufzeit in Sekunden und einem optionalem Sortierschlüssel auf. Der Speicher bereinigt automatisch, sobald der Schlüssel abläuft. Die maximale Ablaufzeit beträgt 3.888.000 Sekunden (45 Tage). Der Sortierschlüssel, sofern angegeben, muss eine gültige Zahl (ganzzahlig oder Gleitkommazahl) oder eine Zeichenfolge sein.

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

Beispiel einiger 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 wird nach allen Schlüsseln mit einem numerischen Sortierschlüssel sortiert. player4 und player5 haben den gleichen Sortierschlüssel, daher werden sie in aufsteigender Reihenfolge nach dem Schlüssel sortiert.

Daten zu einer sortierten Karte hinzufügen
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 war erfolgreich.")
end

Daten abrufen

Sie können entweder einen Datenwert und einen Sortierschlüssel, die mit einem bestimmten Schlüssel verknüpft sind, abrufen oder mehrere Werte und Sortierschlüssel für Schlüssel innerhalb eines Bereichs erhalten.

Daten mit einem Schlüssel abrufen

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

Einen bestimmten Schlüssel aus einer sortierten Karte abrufen
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 war 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. Zum Beispiel ruft das folgende Codebeispiel bis zu 20 Elemente ab, beginnend am Anfang der sortierten Karte, mit Schlüsseln größer oder gleich 10, Sortierschlüssel größer oder gleich 100 und Schlüsseln kleiner oder gleich 50, Sortierschlüssel kleiner oder gleich 500.

Einen Bereich von Schlüsseln aus einer sortierten Karte abrufen
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 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 den Sortierschlüssel eines Schlüssels aus einer sortierten Karte abzurufen und zu aktualisieren, rufen Sie MemoryStoreSortedMap:UpdateAsync() mit dem Schlüssel Namen, einer Callback-Funktion, um den Wert und den Sortierschlüssel für diesen Schlüssel zu aktualisieren, und einer Ablaufzeit in Sekunden auf. Die maximale Ablaufzeit 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 dem Aktualisieren ändert, sollten Sie es verwenden, um den neuesten Wert als Eingabe für Ihre Callback-Funktion zu lesen.

Zum Beispiel aktualisiert das folgende Codebeispiel den Punktestand in einer Rangliste für einen Spieler. Der Punktestand wird als Kills / Tode berechnet. UpdateAsync() stellt sicher, dass die Kills und Tode für 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 im Wert einer Sitzung steigen.

Aktualisieren des Ranglistenpunktestands für einen Spieler in einer sortierten Karte
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 verwendet wird, um Elemente in der Karte zu sortieren
				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 liegt eine Konkurrenzsituation vor.

Wenn eine Konkurrenzsituation auftritt, versucht das System automatisch, die Operation erneut, bis eines dieser drei Ereignisse eintritt: die Operation ist erfolgreich, 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 MemoryStoreSortedMap:RemoveAsync() sowohl verwenden, um einen Schlüssel aus der sortierten Karte zu entfernen, als auch um alle Daten in einer Speicherstore sortierten Karte zu löschen.

Einen Schlüssel entfernen

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

Einen Schlüssel aus einer sortierten Karte entfernen
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 war erfolgreich.")
end

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

Alle Daten löschen

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

Speicher in einer sortierten Karte löschen
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

-- Anfangs untere Grenze von nil beginnt mit der ersten Position zu löschen
local exclusiveLowerBound = nil

while true do
	-- Holen Sie bis zu hundert Elemente, beginnend von der aktuellen unteren Grenze
	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 exklusiven unteren Grenze
		if not removeSuccess then
			warn(removeError)
		-- Wenn der Bereich weniger als hundert Elemente beträgt, wurde das Ende der Karte erreicht
		elseif #items < 100 then
			break
		else
			-- Der zuletzt 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.

Die Größe einer sortierten Karte abrufen
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 war erfolgreich.")
end

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

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