Bellek mağazası sıralı harita

Sıralı harita veri yapısı bellek mağazaları içerisinde sıklıkla kullanılan verileri anahtar-değer çiftleri olarak, isteğe bağlı bir sıralama anahtarına sahip olacak şekilde saklamanızı ve sıralama anahtarları ile anahtarlar temelinde belirli bir sırayı korumanızı sağlar. Kuyrukların aksine, bir haritaya giren anahtarların sırası işleme sırasını belirlemez; bu da sıralı haritaları oyun içi varlıklar gibi verileri düzenlemek için, örneğin liderlik tabloları ve sunucu arası müzayede uygulamaları için yararlı kılar.

Sınırlamalar

bellek mağazalarının veri yapısı boyut sınırlamaları dışında, sıralı haritaların 128 karakterlik bir anahtar boyut sınırlaması, 32 KB'lık bir değer boyut sınırlaması ve 128 karakterlik bir sıralama anahtarı boyut sınırlaması vardır.

Oyununuza bu sınırlamayı aşan verileri saklamak gerekiyorsa, bunları anahtar ön eki kullanarak birden fazla veri yapısına bölmek ve dağıtmak için parçalama tekniğini benimseyebilirsiniz. Bellek mağazalarının parçalanması aynı zamanda sisteminizin ölçeklenebilirliğini artırmada da yardımcı olabilir.

Sıralı harita alma

Sıralı haritayı almak için, haritaya tanımlamak istediğiniz isimle MemoryStoreService:GetSortedMap() çağrısını yapın. İsim oyun içerisinde küresel olduğu için, adı kullanarak herhangi bir skripte aynı sıralı haritaya erişebilirsiniz.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

Bir sıralı harita aldıktan sonra aşağıdaki fonksiyonlardan herhangi birini çağırabilirsiniz:

Veri ekleme veya üzerine yazma

Sıralı haritada yeni bir anahtar eklemek veya bir anahtarın değerini veya sıralama anahtarını üzerine yazmak için, MemoryStoreSortedMap:SetAsync() çağrısını anahtarın ismini, değerini, sona erme süresini (saniye cinsinden) ve isteğe bağlı bir sıralama anahtarını vererek gerçekleştirin. Anahtar sona erdiğinde bellek otomatik olarak temizlenir. Maksimum sona erme süresi 3,888,000 saniyedir (45 gün). Sağlanan sıralama anahtarı geçerli bir sayı (tam sayı veya kesirli) veya bir dize olmalıdır.

Anahtarlarınızın sıralama düzeninde, bir sıralama anahtarı bir anahtardan daha önceliklidir. Örneğin, artan sırada sıralarken, sayısal sıralama anahtarları önce sıralanır, ardından dize sıralama anahtarları ve en son sıralama anahtarı olmayan öğeler sıralanır. Sayısal sıralama anahtarlarına sahip tüm öğeler sıralama anahtarına göre sıralanır; eğer iki öğenin sıralama anahtarları eşitse, anahtara göre sıralanırlar. Benzer şekilde, dize sıralama anahtarlarına sahip tüm öğeler sıralama anahtarına göre sıralanır; eğer iki öğenin sıralama anahtarları eşitse, anahtara göre sıralanırlar. Sıralama anahtarı olmayan tüm öğeler yalnızca anahtarlarına göre sıralanır.

Artan sırada sıralanmış bazı verilerin örneği -

{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}

player0'ın tüm sıralama anahtarlarına sahip anahtarlardan sonra sıralandığına dikkat edin. player6, sayısal sıralama anahtarına sahip tüm anahtarlardan sonra sıralanır. player4 ve player5 aynı sıralama anahtarına sahip olduklarından anahtarlarına göre artan sırada sıralanırlar.

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 işlemi başarılı.")
end

Veri alma

Belirli bir anahtara bağlı olan bir değer ile sıralama anahtarını veya bir aralıktaki anahtarlar için birden fazla değer ve sıralama anahtarını alabilirsiniz.

Tek anahtarla veri alma

Sıralı haritadan bir anahtar ile ilişkili olan bir değer ve sıralama anahtarını almak için, MemoryStoreSortedMap:GetAsync() çağrısını anahtarın ismini kullanarak gerçekleştirin.

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 işlemi başarılı.")
end

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

Birden fazla anahtarla veri alma

Sıralı haritadan birden fazla anahtar için verileri tek bir işlem olarak almak için MemoryStoreSortedMap:GetRangeAsync() çağrısını yapın. Bu fonksiyon varsayılan olarak tüm mevcut anahtarları sıralar, ancak anahtar aralığı için üst ve alt sınırları belirleyebilirsiniz. Örneğin, aşağıdaki kod örneği sıralı haritanın başından itibaren 20 öğe alır; anahtarları 10'dan büyük veya eşit, sıralama anahtarları 100'den büyük veya eşit ve anahtarları 50'den küçük veya eşit, sıralama anahtarları da 500'den küçük veya eşit olacak şekilde getirilir.

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

-- Başlangıçtan itibaren 20 öğe al
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

Veri güncelleme

Sıralı haritadan bir anahtarın değerini ve sıralama anahtarını almak ve güncellemek için, MemoryStoreSortedMap:UpdateAsync() çağrısını anahtarın ismini, bu anahtarın değerini ve sıralama anahtarını güncelleyecek bir geri çağırma fonksiyonunu ve bir sona erme süresini (saniye cinsinden) vererek yapın. Maksimum sona erme süresi 3,888,000 saniyedir (45 gün).

Çoğu oyun için, birden fazla sunucu aynı anahtarı eşzamanlı olarak güncelleyip değeri değiştirebilir. MemoryStoreSortedMap:UpdateAsync() en son değeri güncellemeden önce her zaman değiştirir; bu nedenle, geri çağırma fonksiyonunuz için giriş olarak en son değeri okumak için kullanılmasını öneririz.

Örneğin, aşağıdaki kod örneği bir oyuncu için liderlik tablosundaki skoru günceller. Skor, öldürme sayısı / ölüm sayısı olarak hesaplanır. MemoryStoreSortedMap:UpdateAsync() oyunun sunucularının aynı öğeyi eşzamanlı olarak güncelleyebilmesine rağmen, öldürmelerin ve ölümlerin en son güncellenmiş değerleriyle güncellenmesini sağlar. Bir oyuncunun öldürmeleri ve ölümleri monotonik olarak artan değerlerdir ve bu nedenle bir oturumda sadece değeri artırabilir.

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`, haritadaki öğeleri sıralamak için kullanılan sıralama anahtarıdır
				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

MemoryStoreSortedMap:UpdateAsync()'ın gecikmesi, MemoryStoreSortedMap:GetAsync() ve MemoryStoreSortedMap:SetAsync() ile benzer olup; rekabet durumlarında farklılık gösterebilir.

Rekabet durumları oluştuğunda sistem, bu üç durumdan biri gerçekleşene kadar işlemi otomatik olarak tekrarlar: işlem başarıyla gerçekleşir, geri çağırma fonksiyonu nil döner veya maksimum yeniden deneme sayısına ulaşılır. Eğer sistem maksimum yeniden deneme sayısına ulaşırsa, bir tutarsızlık döner.

Veri kaldırma

Sıralı haritadan bir anahtarı kaldırmak ve bellek mağazası sıralı haritasındaki tüm verileri silmek için MemoryStoreSortedMap:RemoveAsync() kullanılabilir.

Anahtar kaldırma

Sıralı haritadan bir anahtarı kaldırmak için, MemoryStoreSortedMap:RemoveAsync() ile bir anahtarın ismini kullanarak çağrıda bulunun.

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 işlemi başarılı.")
end

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

Tüm verileri silme

Sıralı haritalardaki belleği silmek için, MemoryStoreSortedMap:GetRangeAsync() ile tüm anahtarlarınızı listeleyin, ardından bunları MemoryStoreSortedMap:RemoveAsync() ile kaldırın.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

-- Başlangıçta nil olan alt sınır, ilk öğeden temizleme yapar
local exclusiveLowerBound = nil

while true do
	-- Mevcut alt sınırdan itibaren 100 öğe kadar alın
	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

		-- Eğer öğeleri kaldırırken bir hata oluştuysa, aynı alt sınır ile tekrar deneyin
		if not removeSuccess then
			warn(removeError)
		-- Eğer aralık 100 öğeden az ise, haritanın sonuna ulaşılmıştır
		elseif #items < 100 then
			break
		else
			-- Alınan son anahtar sonraki yineleme için özel alt sınırdır
			exclusiveLowerBound = {}
			exclusiveLowerBound["key"] = items[#items].key
			exclusiveLowerBound["sortKey"] = items[#items].sortKey
		end
	end
end

Boyut alma

Sıralı haritadaki öğe sayısını almak için MemoryStoreSortedMap:GetSizeAsync() çağrısını yapın.

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 işlemi başarılı.")
end

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

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