Bellek deposu sıralı harita

Sıralı harita veri yapısı, bellek depoları sayesinde, her zaman bellek içinde sık kullanılan verileri, isteğe bağlı bir sıralama anahtarı ile birlikte anahtar-değer çiftleri olarak depolamanıza ve anahtarlar ile sıralama anahtarlarına dayalı belirli bir sırayı korumanıza olanak tanır. Kuyrukların aksine, bir haritaya giren anahtarların sırası işleme sırasını belirlemez, bu nedenle sıralı haritalar, oyun içi varlıkların (örneğin, liderlik tabloları ve çapraz sunucu açık artırmaları gibi) düzenlenmesi için sıralı veri organizasyonu sağlamak amacıyla yararlıdır.

Sınırlamalar

Sıralı haritalar, veri yapı boyutu sınırlamaları haricinde, 128 karakterlik bir anahtar boyutu sınırlamasına, 32 KB'lık bir değer boyutu sınırlamasına ve 128 karakterlik bir sıralama anahtarı boyutu sınırlamasına sahiptir.

Oyununuza bu sınırı aşan verileri depolamanız gerekirse, verileri anahtar öneki ile birden fazla veri yapısına bölmek ve dağıtmak için parçalama tekniğini benimseyebilirsiniz. Bellek depolarını parçalamak, sisteminizin ölçeklenebilirliğini artırmaya da yardımcı olabilir.

Sıralı harita al

Sıralı bir harita almak için, tanımlamak istediğiniz isim ile MemoryStoreService:GetSortedMap() çağrısını yapın. İsim, oyun içinde globaldir, bu nedenle ismi kullanarak aynı sıralı haritaya herhangi bir script'te erişebilirsiniz.

Sıralı Harita Alma
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

Sıralı bir harita aldıktan sonra, aşağıdaki işlevlerden herhangi birini çağırın:

Veri ekleme veya üzerine yazma

Yeni bir anahtar eklemek veya sıralı haritadaki bir anahtarın değerini veya sıralama anahtarını üzerine yazmak için, anahtar ismini, değerini, sona erme süresini (saniye olarak) ve isteğe bağlı bir sıralama anahtarını içeren MemoryStoreSortedMap:SetAsync() çağrısını yapın. Anahtar sona erdiğinde bellek otomatik olarak temizlenir. Maksimum sona erme süresi 3,888,000 saniyedir (45 gün). Eğer sağlanırsa, sıralama anahtarı geçerli bir sayı (tam sayı veya ondalık) veya bir dize olmalıdır.

Anahtarlarınızın sıralanma düzeninde, sıralama anahtarı anahtarın önceliğine sahiptir. Örneğin, artan sıralama düzeninde sayı sıralama anahtarları önce sıralanır, sonra dize sıralama anahtarları, ardından sıralama anahtarı olmayan öğeler gelir. Sayı sıralama anahtarına sahip tüm öğeler sıralama anahtarına göre sıralanır; eğer iki öğenin sıralama anahtarı eşitse, anahtara göre sıralanır. Benzer şekilde, dize sıralama anahtarına sahip tüm öğeler sıralama anahtarına göre sıralanır; eğer iki öğenin sıralama anahtarı eşitse, anahtara göre sıralanır. Sıralama anahtarı olmayan tüm öğeler yalnızca anahtara göre sıralanır.

Artan sıralamada sıralanmış bazı veri ö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 sıralama anahtarı olan tüm anahtarlardan sonra sıralandığını not edin. player6, tüm sayı sıralama anahtarına sahip anahtarların ardından sıralanır. player4 ve player5, aynı sıralama anahtarına sahip olduğu için artan sıralama düzenine göre anahtara göre sıralanır.

Sıralı Haritaya Veri Ekleme
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("Ayar başarılı.")
end

Veri alma

Belirli bir anahtarla ilişkili bir veri değeri ve sıralama anahtarını alabilir veya bir aralık içinde birçok anahtar için birden fazla değeri ve sıralama anahtarını alabilirsiniz.

Bir anahtarla veri alma

Sıralı haritadan bir anahtarla ilişkili bir değer ve sıralama anahtarını almak için, anahtar ismini içeren MemoryStoreSortedMap:GetAsync() çağrısını yapın.

Sıralı Haritadan Belirli Bir Anahtarı Alma
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("Ayar 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 bir seferde birden fazla anahtar için veri almak üzere MemoryStoreSortedMap:GetRangeAsync() çağrısını yapabilirsiniz. Bu işlev varsayılan olarak tüm mevcut anahtarları listeler, 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 başlayarak 20 öğe alır, anahtarlar 10 veya daha büyük, sıralama anahtarları 100 veya daha büyük ve anahtarlar 50 veya daha küçük, sıralama anahtarları 500 veya daha küçük olan öğeleri alır.

Sıralı Haritadan Anahtar Aralığı Alma
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 en fazla 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ı bir haritadan bir anahtarın değerini ve sıralama anahtarını almak ve güncellemek için, anahtar ismini, bu anahtar için değeri ve sıralama anahtarını güncelleyen bir geri çağırma işlevi ve saniye cinsinden bir sona erme süresi ile MemoryStoreSortedMap:UpdateAsync() çağrısını yapın. Maksimum sona erme süresi 3,888,000 saniyedir (45 gün).

Birçok oyunda, birden fazla sunucu aynı anahtarı aynı anda güncelleyebilir ve değeri değiştirebilir. MemoryStoreSortedMap:UpdateAsync() en son değeri güncellemeden önce her zaman değiştirir, bu nedenle geri çağırma işleviniz için girdi olarak en son değeri okumak için bunu kullanmalısınız.

Örneğin, aşağıdaki kod örneği bir oyuncunun liderlik tablosundaki puanını günceller. Puan, öldürme / ölüm olarak hesaplanır. MemoryStoreSortedMap:UpdateAsync() diğer sunucuların aynı öğeyi aynı anda güncelleyebildiği durumlarda bile, öldürmelerin ve ölümlerin en son değerleri için güncellenmesini sağlar. Bir oyuncunun öldürmeleri ve ölümleri monotonik artan değerlerdir, bu nedenle sadece oturumda artabilir.

Sıralı Haritada Bir Oyuncunun Liderlik Tablosu Puanını Güncelleme
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

UpdateAsync()'nin gecikmesi,(GetAsync() ve SetAsync() ile benzer) bir içerik fotomontaj durumu olmadıkça.

Çatışma durumunda, sistem otomatik olarak işlemi yeniden dener, ta ki bunlardan biri gerçekleşene dek: işlem başarılı olur, geri çağırma işlevi nil döndürür veya en fazla yeniden deneme sayısına ulaşıldı. Sistem maksimum tekrar sayısına ulaştığında, bir çatışma döndürür.

Veriyi kaldırma

Sıralı haritadan bir anahtarı kaldırmak ve bellek deposu sıralı haritasındaki tüm verileri silmek için MemoryStoreSortedMap:RemoveAsync() kullanabilirsiniz.

Bir anahtarı kaldırma

Sıralı haritadan bir anahtarı kaldırmak için, anahtar ismini içeren MemoryStoreSortedMap:RemoveAsync() çağrısını yapın.

Sıralı Haritadan Bir Anahtarı Kaldırma
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("Ayar başarılı.")
end

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

Tüm veriyi silme

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

Sıralı Haritada Belleği Silme
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

-- Başlangıç için alt sınırın yokluğu, ilk öğeden silme işlemi başlatır
local exclusiveLowerBound = nil

while true do
	-- Mevcut alt sınırdan 100 öğe almak
	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 hata olursa, aynı dışlama alt sınırı ile tekrar deneyin
		if not removeSuccess then
			warn(removeError)
		-- Eğer aralık 100 öğeden azsa, haritanın sonuna ulaşılmıştır
		elseif #items < 100 then
			break
		else
			-- Alınan son anahtar, bir sonraki yineleme için dışlama alt sınırıdı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.

Sıralı Haritanın Boyutunu Alma
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("Ayar başarılı.")
end

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

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