Bellek deposu hash haritası | Dokümantasyon

Hash haritaları, sıralı haritalara benzer şekilde, bellekteki verileri anahtar-değer çiftleri olarak saklamanızı sağlar. Sıralı haritaların aksine, hiçbir sıralama garantisi vermezler. Bu veri yapısı, paylaşılan envanterler, fiziksel açık artırma evleri gibi basit veri önbellekleme ve hızlı erişim gerektiren durumlar için yararlıdır. Hash haritaları verilerinizi otomatik olarak parçalara ayırır ve 1,000'den fazla anahtarınız varsa çok kullanışlıdır. Daha küçük anahtar alanları için, sıralı haritaları öneririz.

Sınırlar

Hash haritalarının bir anahtar boyutu sınırı 128 karakter ve bir değer boyutu sınırı 32 KB'dir.

Bunun dışında, hash haritaları diğer bellek deposu veri yapılarıyla aynı API istekleri ve bellek kotası sınırlarını kullanır.

Hash haritası al

Bir hash haritası almak için, MemoryStoreService:GetHashMap() çağrısında bulunun ve hash haritası için bir isim belirtin. İsim, oyunun içinde küreseldir, bu nedenle bu ismi kullanarak aynı hash haritasına herhangi bir betikte erişebilirsiniz.

Hash Haritası Alma

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

Bir hash haritasını aldıktan sonra, veri okumak veya yazmak için aşağıdaki işlevlerden herhangi birini çağırın:

Fonksiyon	İşlem
MemoryStoreHashMap:SetAsync()	Yeni bir anahtar ekleyin veya anahtar mevcutsa değeri üzerini yazın.
MemoryStoreHashMap:GetAsync()	Belirli bir anahtarı okuyun.
MemoryStoreHashMap:ListItemsAsync()	Listeleyin bir hash haritasındaki öğeleri.
MemoryStoreHashMap:UpdateAsync()	Güncelleyin bir anahtarın değerini hash haritasından aldıktan sonra.
MemoryStoreHashMap:RemoveAsync()	Bir anahtarı kaldırın hash haritasından.

Her bir işlev hakkında ayrıntılı belgeler için MemoryStoreHashMap'a bakın.

Bellek depolarındaki veri yapısına erişen tüm işlevler, bazen başarısız olabilecek asenkron ağ çağrılarıdır. Bu çağrıları, örnek kodlarda gösterildiği gibi hataları yakalamak ve ele almak için pcall() ile sarmalamalısınız.

Veri ekleme veya üzerine yazma

Hash haritasında yeni bir anahtar eklemek veya bir anahtarın değerini üzerine yazmak için, MemoryStoreHashMap:SetAsync() çağrısında bulunun ve isim, değer ve sona erme süresi (saniye cinsinden) belirtin. Anahtar sona erdiğinde bellek otomatik olarak temizlenir. Maksimum sona erme süresi 3,888,000 saniyedir (45 gün).

Hash Haritasına Veri Ekleme

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

Veri alma

Belirli bir anahtarla ilişkili bir değeri alabilir veya hash haritasındaki birden fazla anahtar-değer çiftini alabilirsiniz.

Bir anahtar ile veri alma

Hash haritasından bir anahtarla ilişkili bir değeri almak için, MemoryStoreHashMap:GetAsync() çağrısında bulunun ve anahtar ismi belirtin.

Hash Haritasından Belirli Bir Anahtarı Alma

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

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

Birden fazla anahtar-değer çifti ile veri alma

Hash haritasından tüm anahtar-değer çiftlerini tek bir işlemde almak için, MemoryStoreHashMap:ListItemsAsync() çağrısında bulunun ve istenen sayfa boyutunu belirtin. Bu işlev, tüm mevcut anahtarları sayfalanmış bir şekilde listeler. Örneğin, aşağıdaki kod örneği hash haritasından 32 öğeye kadar alır.

Hash Haritasındaki Öğeleri Listeleme

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Öğelerin listesini al, 32 öğe bir seferde
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Mevcut sayfayı al
		local entries = pages:GetCurrentPage()
		-- Sayfadaki tüm anahtar-değer çiftlerini döngüye al
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Son sayfanın ulaşılıp ulaşılmadığını kontrol et
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Sonraki sayfaya geç
			pages:AdvanceToNextPageAsync()
		end
	end
end

Veri güncelleme

Hash haritasından bir anahtarın değerini almak ve güncellemek için, MemoryStoreHashMap:UpdateAsync() çağrısında bulunun ve anahtar ismi, bir geri çağırma işlevi ve sona erme süresi (saniye cinsinden) belirtin.

Çoğu oyun için, birden fazla sunucu aynı anahtarı eşzamanlı olarak güncelleyebilir ve değeri değiştirebilir. UpdateAsync() her zaman en son değeri güncellemeden önce değiştirerek, geri çağırma işlevinizin girişi olarak en son değeri okumanız için kullanılmalıdır.

Örneğin, aşağıdaki kod örneği, paylaşılan bir envanterdeki bir kaynağın sayısını günceller. UpdateAsync() tüm oyuncu katkılarının bu paylaşılan envantere ulaşmasını sağlarken, katkılar aynı anda yapılmış olsa bile bu işlevde maksimum kaynak sayısını 500 olarak zorlar.

Paylaşılan Envanterde Bir Kaynağın Kaynak Sayısını Güncelleme

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

			-- maksimum kaynak sayısını aşmadığımızdan emin olun
			if resource.count > 500 then
				resource.count = 500
			end
			return resource
		end, 1200)
	end)
	if success then
		print(newResourceCount)
	end
end

UpdateAsync() için gecikme, GetAsync() ve SetAsync() ile benzerdir, ancak bir içerleme olduğunda.

İçerleme olduğunda, sistem işlemi, bu üç durumdan biri gerçekleşene kadar otomatik olarak tekrar denemektedir: işlem başarılı olur, geri çağırma işlevi nil döner veya maksimum tekrar sayısına ulaşılır. Sistem maksimum tekrar sayısına ulaşırsa, çakışmayı döndürür.

Veri kaldırma

MemoryStoreHashMap:RemoveAsync() hem hash haritasından bir anahtarı kaldırmak hem de bir bellek deposu hash haritasındaki tüm verileri silmek için kullanılabilir.

Bir anahtarı kaldırma

Hash haritasından bir anahtarı kaldırmak için, MemoryStoreHashMap:RemoveAsync() çağrısında bulunun ve anahtar ismi belirtin.

Hash Haritasından Bir Anahtarı Kaldırma

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

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

Tüm verileri silme

Hash haritasındaki tüm verileri silmek için, MemoryStoreHashMap:ListItemsAsync() ile tüm öğelerinizi listeleyin, ardından bunları MemoryStoreHashMap:RemoveAsync() ile kaldırın.

Hash Haritasındaki Tüm Verileri Silme

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Öğelerin listesini al, 32 öğe bir seferde
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Mevcut sayfayı al
		local entries = pages:GetCurrentPage()
		local removeSuccess = true
		local removeError = nil
		-- Sayfadaki tüm anahtar-değer çiftlerini döngüye al
		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
		-- Son sayfanın ulaşılıp ulaşılmadığını kontrol et
		if pages.IsFinished then
			print("Tüm verileri silme işlemi tamamlandı.")
			break
		else
			print("----------")
			-- Sonraki sayfaya geç
			pages:AdvanceToNextPageAsync()
		end
	end
end