Posortowana mapa pamięci

Struktura danych posortowanej mapy w magazynach pamięci pozwala na przechowywanie częstych danych w pamięci jako par klucz-wartość z opcjonalnym kluczem sortującym i utrzymywaniu określonego porządku w oparciu o klucze sortujące i klucze. W przeciwieństwie do kolejek, kolejność kluczy wchodzących do mapy nie określa kolejności przetwarzania, co sprawia, że posortowane mapy są użyteczne do organizacji danych opartej na sortowaniu w celu implementacji elementów w grze, takich jak rankingi i aukcje międzyserwerowe.

Ograniczenia

Oprócz ograniczeń rozmiaru struktury danych, posortowane mapy mają limit rozmiaru klucza wynoszący 128 znaków, limit rozmiaru wartości wynoszący 32 KB i limit rozmiaru klucza sortującego wynoszący 128 znaków.

Jeśli potrzebujesz przechowywać dane, które przekraczają ten limit w swojej grze, możesz zastosować technikę sharding, aby podzielić je i rozprowadzić przez prefiks klucza do wielu struktur danych. Sharding magazynów pamięci może również pomóc w poprawie skalowalności twojego systemu.

Uzyskanie posortowanej mapy

Aby uzyskać posortowaną mapę, wywołaj MemoryStoreService:GetSortedMap() z nazwą, którą chcesz zdefiniować dla mapy. Nazwa jest globalna w grze, więc możesz uzyskać dostęp do tej samej posortowanej mapy w każdym skrypcie używając tej samej nazwy.

Uzyskiwanie posortowanej mapy
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

Po uzyskaniu posortowanej mapy, wywołaj dowolną z następujących funkcji:

Dodaj lub nadpisz dane

Aby dodać nowy klucz lub nadpisać wartość lub klucz sortujący klucza w posortowanej mapie, wywołaj MemoryStoreSortedMap:SetAsync() z kluczem nazwa, jego wartością, czasem wygaśnięcia w sekundach i opcjonalnym kluczem sortującym. Pamięć automatycznie oczyszcza się, gdy klucz wygaśnie. Maksymalny czas wygaśnięcia wynosi 3 888 000 sekund (45 dni). Klucz sortujący, jeśli jest podany, musi być prawidłową liczbą (całkowitą lub zmiennoprzecinkową) lub ciągiem.

W biurze sortującym twoich kluczy klucz sortujący ma pierwszeństwo przed kluczem. Na przykład, sortując w kolejności rosnącej, klucze sortujące numeryczne są sortowane w pierwszej kolejności, następnie klucze sortujące ciągowe, a następnie elementy bez klucza sortującego. Wszystkie elementy z kluczami sortującymi numerycznymi są sortowane według klucza sortującego, jeśli klucz sortujący dla dwóch elementów jest równy, są sortowane według klucza. Podobnie, wszystkie elementy z kluczami sortującymi ciągowymi są sortowane według klucza sortującego, jeśli klucz sortujący dla dwóch elementów jest równy, są sortowane według klucza. Wszystkie elementy bez klucza sortującego są sortowane tylko według klucza.

Przykład danych posortowanych w kolejności rosnącej -

{key: "gracz1", value: someValue1, sortKey: -1}
{key: "gracz2", value: someValue2, sortKey: 0}
{key: "gracz4", value: someValue3, sortKey: 1}
{key: "gracz5", value: someValue4, sortKey: 1}
{key: "gracz3", value: someValue5, sortKey: 3.14}
{key: "gracz6", value: someValue6, sortKey: "jakisCiąg"}
{key: "gracz0", value: someValue7}
{key: "gracz7", value: someValue8}

Zauważ, jak gracz0 znajduje się po wszystkich kluczach z kluczem sortującym. gracz6 znajduje się po wszystkich kluczach z numerycznym kluczem sortującym. gracz4 i gracz5 mają ten sam klucz sortujący, więc są sortowani w kolejności rosnącej według klucza.

Dodawanie danych do posortowanej mapy
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

local setSuccess, _ = pcall(function()
	return sortedMap:SetAsync("Użytkownik_1234", 1000, 30, 3.14152)
end)
if setSuccess then
	print("Ustawienie powiodło się.")
end

Uzyskaj dane

Możesz uzyskać wartość danych i klucz sortujący związany z konkretnym kluczem lub uzyskać wiele wartości i kluczy sortujących dla kluczy w obrębie zakresu.

Uzyskaj dane z jednym kluczem

Aby uzyskać wartość i klucz sortujący związany z jednym kluczem z posortowanej mapy, wywołaj MemoryStoreSortedMap:GetAsync() z kluczem nazwa.

Uzyskiwanie konkretnego klucza z posortowanej mapy
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

local setSuccess, _ = pcall(function()
	return sortedMap:SetAsync("Użytkownik_1234", 1000, 30, 3.14152)
end)
if setSuccess then
	print("Ustawienie powiodło się.")
end

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

Uzyskaj dane z wieloma kluczami

Aby uzyskać dane dla wielu kluczy z posortowanej mapy w jednej operacji, wywołaj MemoryStoreSortedMap:GetRangeAsync(). Ta funkcja domyślnie zwraca wszystkie istniejące klucze, ale możesz ustawić górną i dolną granicę dla zakresu klucza. Na przykład, poniższy przykład kodu pobiera do 20 elementów, zaczynając od początku posortowanej mapy, z kluczami większymi lub równymi 10, kluczami sortującymi większymi lub równymi 100 i kluczami mniejszymi lub równymi 50, kluczami sortującymi mniejszymi lub równymi 500.

Uzyskiwanie zakresu kluczy z posortowanej mapy
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

-- Uzyskaj do 20 elementów, zaczynając od początku
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

Aktualizacja danych

Aby pobrać wartość i klucz sortujący danego klucza z posortowanej mapy i zaktualizować je, wywołaj MemoryStoreSortedMap:UpdateAsync() z kluczem nazwa, funkcją zwrotną do zaktualizowania wartości i klucza sortującego dla tego klucza oraz czasem wygaśnięcia w sekundach. Maksymalny czas wygaśnięcia wynosi 3 888 000 sekund (45 dni).

W przypadku większości gier wiele serwerów może jednocześnie aktualizować ten sam klucz i zmieniać jego wartość. Ponieważ UpdateAsync() zawsze modyfikuje najnowszą wartość przed aktualizacją, powinieneś go użyć do odczytu najnowszej wartości jako wejścia do swojej функции zwrotnej.

Na przykład poniższy kod aktualizuje wynik w rankingu dla gracza. Wynik jest obliczany jako zabójstwa / śmierci. UpdateAsync() zapewnia, że zabójstwa i śmierci są aktualizowane dla najnowszych wartości, nawet jeśli wiele serwerów gier aktualizuje ten sam element jednocześnie. Zabójstwa i śmierci gracza są wartościami monotonicznie rosnącymi, więc mogą tylko wzrastać w wartości w sesji.

Aktualizacja wyniku w rankingu dla gracza w posortowanej mapie
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("Ranking")

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` to klucz sortujący używany do sortowania elementów w mapie
				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

Opóźnienie dla UpdateAsync() jest podobne do GetAsync() i SetAsync(), chyba że występuje konflikt.

Gdy występuje konflikt, system automatycznie próbuje ponownie operację, aż jedno z trzech zdarzeń zajdzie: operacja zakończy się sukcesem, funkcja zwrotna zwróci nil, lub osiągnięta zostanie maksymalna liczba prób. Jeśli system osiągnie maksymalną liczbę prób, zwraca błąd konfliktu.

Usuń dane

Możesz użyć MemoryStoreSortedMap:RemoveAsync() zarówno do usunięcia jednego klucza z posortowanej mapy, jak i do usunięcia wszystkich danych w posortowanej mapie magazynu pamięci.

Usuń klucz

Aby usunąć klucz z posortowanej mapy, wywołaj MemoryStoreSortedMap:RemoveAsync() z kluczem nazwa.

Usuń klucz z posortowanej mapy
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

local setSuccess, _ = pcall(function()
	return sortedMap:SetAsync("Użytkownik_1234", 1000, 30, "jakisCiągSortKey")
end)
if setSuccess then
	print("Ustawienie powiodło się.")
end

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

Usuń wszystkie dane

Aby usunąć pamięć w posortowanych mapach, wymień wszystkie swoje klucze z MemoryStoreSortedMap:GetRangeAsync(), a następnie usuń je za pomocą MemoryStoreSortedMap:RemoveAsync().

Usuń pamięć w posortowanej mapie
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

-- Początkowy dolny limit nil zaczyna opróżnienie od pierwszego elementu
local exclusiveLowerBound = nil

while true do
	-- Uzyskaj do stu elementów od obecnego dolnego limitu
	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

		-- Jeśli wystąpił błąd podczas usuwania elementów, spróbuj ponownie z tym samym dolnym limitem
		if not removeSuccess then
			warn(removeError)
		-- Jeśli zakres jest mniejszy niż sto elementów, osiągnięto koniec mapy
		elseif #items < 100 then
			break
		else
			-- Ostatnio pobrany klucz jest dolnym limitem wyłączającym dla następnej iteracji
			exclusiveLowerBound = {}
			exclusiveLowerBound["key"] = items[#items].key
			exclusiveLowerBound["sortKey"] = items[#items].sortKey
		end
	end
end

Uzyskaj rozmiar

Aby uzyskać liczbę elementów w posortowanej mapie, wywołaj MemoryStoreSortedMap:GetSizeAsync().

Uzyskiwanie rozmiaru posortowanej mapy
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

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

if setSuccess then
	print("Ustawienie powiodło się.")
end

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

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