Mapa hasz i pamięci | Dokumentacja – Centrum twórców Roblox

Mapy haszowe, podobnie jak mapy posortowane, pozwalają przechowywać dane w pamięci w postaci par klucz-wartość. W przeciwieństwie do map posortowanych, nie utrzymują gwarancji porządku. Ta struktura danych jest przydatna w przypadkach wymagających prostego buforowania danych i szybkiego dostępu, takich jak wspólne inwentarze, fizyczne domy aukcyjne i inne. Mapy haszowe automatycznie zarządzają partycjonowaniem danych i są bardzo przydatne, jeśli masz więcej niż 1000 kluczy. Dla mniejszych przestrzeni kluczy zalecamy mapy posortowane.

Limity

Mapy haszowe mają limit rozmiaru klucza wynoszący 128 znaków oraz limit rozmiaru wartości wynoszący 32 KB.

W przeciwnym razie, mapy haszowe korzystają z tych samych limitów żądań API i kwot pamięci co inne struktury danych w pamięci.

Uzyskaj mapę haszową

Aby uzyskać mapę haszową, wywołaj MemoryStoreService:GetHashMap() z nazwą mapy haszowej. Nazwa jest globalna w obrębie gry, więc możesz uzyskać dostęp do tej samej mapy haszowej w każdym skrypcie używając tej nazwy.

Uzyskiwanie mapy haszowej

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

Po uzyskaniu mapy haszowej, wywołaj którąkolwiek z poniższych funkcji, aby odczytać lub zapisać dane:

Funkcja	Akcja
MemoryStoreHashMap:SetAsync()	Dodaj nowy klucz lub nadpisz wartość, jeśli klucz już istnieje.
MemoryStoreHashMap:GetAsync()	Odczytaj dany klucz.
MemoryStoreHashMap:ListItemsAsync()	Wypisz elementy w mapie haszowej.
MemoryStoreHashMap:UpdateAsync()	Zaktualizuj wartość klucza po jej pobraniu z mapy haszowej.
MemoryStoreHashMap:RemoveAsync()	Usuń klucz z mapy haszowej.

Aby uzyskać szczegółową dokumentację na temat każdej funkcji, zobacz MemoryStoreHashMap.

Wszystkie funkcje uzyskujące dostęp do struktur danych w pamięci są asynchronicznymi wywołaniami sieciowymi, które mogą czasami się nie powieść. Powinieneś opakować te wywołania w pcall(), aby wychwycić i obsłużyć błędy, jak pokazano w przykładach kodu.

Dodaj lub nadpisz dane

Aby dodać nowy klucz lub nadpisać wartość klucza w mapie haszowej, wywołaj MemoryStoreHashMap:SetAsync() z nazwą klucza, jego wartością i czasem wygaśnięcia w sekundach. Pamięć automatycznie oczyszcza dane po wygaśnięciu klucza. Maksymalny czas wygaśnięcia wynosi 3,888,000 sekund (45 dni).

Dodawanie danych do mapy haszowej

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("Ustawienie powiodło się.")
end

Odbierz dane

Możesz uzyskać wartość skojarzoną z konkretnym kluczem lub uzyskać wiele par klucz-wartość w mapie haszowej.

Odbierz dane za pomocą jednego klucza

Aby uzyskać wartość skojarzoną z jednym kluczem z mapy haszowej, wywołaj MemoryStoreHashMap:GetAsync() z nazwą klucza.

Uzyskiwanie konkretnego klucza z mapy haszowej

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("Ustawienie powiodło się.")
end

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

Odbierz dane z wieloma parami klucz-wartość

Aby uzyskać wszystkie pary klucz-wartość z mapy haszowej jako jedną operację, wywołaj MemoryStoreHashMap:ListItemsAsync() z pożądaną wielkością strony. Ta funkcja wypisuje wszystkie istniejące klucze w sposób stronniczy. Na przykład, poniższy fragment kodu pobiera maksymalnie 32 elementy z mapy haszowej.

Wypisywanie elementów w mapie haszowej

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Pobierz listę elementów, 32 elementy na raz
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Pobierz bieżącą stronę
		local entries = pages:GetCurrentPage()
		-- Iteruj przez wszystkie pary klucz-wartość na stronie
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Sprawdź, czy osiągnięto ostatnią stronę
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Przejdź do następnej strony
			pages:AdvanceToNextPageAsync()
		end
	end
end

Zaktualizuj dane

Aby pobrać wartość klucza z mapy haszowej i zaktualizować ją, wywołaj MemoryStoreHashMap:UpdateAsync() z nazwą klucza, funkcją zwrotną do zaktualizowania klucza oraz czasem wygaśnięcia w sekundach.

Dla większości gier, wiele serwerów może jednocześnie aktualizować ten sam klucz i zmieniać wartość. Ponieważ UpdateAsync() zawsze modyfikuje najnowszą wartość przed aktualizacją, powinieneś używać go do odczytania najnowszej wartości jako wejścia dla swojej funkcji zwrotnej.

Na przykład, poniższy przykład kodu aktualizuje liczbę zasobów w zasobie w wspólnym inwentarzu. UpdateAsync() zapewnia, że wszystkie wkłady graczy znajdą się w tym wspólnym inwentarzu, nawet jeśli te wkłady są składane jednocześnie. W tej funkcji wymusza również maksymalną liczba zasobów wynoszącą 500.

Aktualizacja liczby zasobów dla zasobu w wspólnym inwentarzu

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

			-- upewnij się, że nie przekraczamy maksymalnej liczby zasobów
			if resource.count > 500 then
				resource.count = 500
			end
			return resource
		end, 1200)
	end)
	if success then
		print(newResourceCount)
	end
end

Opóźnienie dla UpdateAsync() jest podobne do GetAsync() i SetAsync() chyba, że wystąpi kolizja.

Gdy wystąpi kolizja, system automatycznie powtarza operację, aż jedno z tych trzech się wydarzy: operacja powiedzie się, funkcja zwrotna zwróci nil, lub osiągnięta zostanie maksymalna liczba prób. Jeśli system osiągnie maksymalną liczbę prób, zwraca konflikt.

Usuń dane

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

Usuń klucz

Aby usunąć klucz z mapy haszowej, wywołaj MemoryStoreHashMap:RemoveAsync() z nazwą klucza.

Usuń klucz z mapy haszowej

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("Ustawienie powiodło się.")
end

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

Usuń wszystkie dane

Aby usunąć wszystkie dane w mapie haszowej, wypisz wszystkie swoje elementy za pomocą MemoryStoreHashMap:ListItemsAsync(), a następnie usuń je za pomocą MemoryStoreHashMap:RemoveAsync().

Usuń wszystkie dane w mapie haszowej

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Pobierz listę elementów, 32 elementy na raz
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Pobierz bieżącą stronę
		local entries = pages:GetCurrentPage()
		local removeSuccess = true
		local removeError = nil
		-- Iteruj przez wszystkie pary klucz-wartość na stronie
		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
		-- Sprawdź, czy osiągnięto ostatnią stronę
		if pages.IsFinished then
			print("Zakończono usuwanie wszystkich danych.")
			break
		else
			print("----------")
			-- Przejdź do następnej strony
			pages:AdvanceToNextPageAsync()
		end
	end
end