Peta terurut penyimpanan memori

Struktur data peta terurut dari penyimpanan memori memungkinkan Anda menyimpan data sering yang ada di memori sebagai pasangan kunci-nilai dengan kunci urut yang opsional dan mempertahankan urutan tertentu berdasarkan kunci urut dan kunci. Berbeda dengan antrian, urutan kunci yang masuk ke dalam peta tidak menentukan urutan pemrosesan, membuat peta terurut berguna untuk pengorganisasian data berbasis pengurutan dalam menerapkan entitas dalam game untuk keterlibatan seperti papan peringkat dan lelang antar-server.

Batas

Selain batas ukuran struktur data, peta terurut memiliki batas ukuran kunci sebesar 128 karakter, batas ukuran nilai sebesar 32 KB, dan batas ukuran kunci urut sebesar 128 karakter.

Jika Anda perlu menyimpan data yang melebihi batas ini untuk game Anda, Anda dapat mengadopsi teknik sharding untuk memisahkan dan mendistribusikannya melalui prefiks kunci ke dalam beberapa struktur data. Sharding pada penyimpanan memori juga dapat membantu meningkatkan skalabilitas sistem Anda.

Dapatkan peta terurut

Untuk mendapatkan peta terurut, panggil MemoryStoreService:GetSortedMap() dengan nama yang ingin Anda tetapkan untuk peta tersebut. Nama tersebut bersifat global dalam game, sehingga Anda dapat mengakses peta terurut yang sama di skrip mana pun menggunakan nama tersebut.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

Setelah Anda mendapatkan peta terurut, panggil salah satu fungsi berikut:

Tambah atau timpa data

Untuk menambahkan kunci baru atau menimpa nilai atau kunci urut dari kunci dalam peta terurut, panggil MemoryStoreSortedMap:SetAsync() dengan nama kunci, nilainya, waktu kadaluarsa dalam detik dan kunci urut opsional. Memori secara otomatis membersihkan setelah kunci kadaluarsa. Waktu kadaluarsa maksimum adalah 3.888.000 detik (45 hari). Kunci urut, jika disediakan, harus berupa angka yang valid (integer atau floating point) atau string.

Dalam urutan pengurutan kunci Anda, kunci urut memiliki prioritas di atas kunci. Misalnya, ketika mengurutkan dalam urutan menaik, kunci urut numerik diurutkan terlebih dahulu, diikuti oleh kunci urut string, diikuti oleh item tanpa kunci urut. Semua item dengan kunci urut numerik diurutkan berdasarkan kunci urut, jika kunci urut untuk dua item sama, mereka diurutkan berdasarkan kunci. Demikian pula, semua item dengan kunci urut string diurutkan berdasarkan kunci urut, jika kunci urut untuk dua item sama, mereka diurutkan berdasarkan kunci. Semua item tanpa kunci urut hanya diurutkan berdasarkan kunci.

Contoh beberapa data yang diurutkan dalam urutan menaik -

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

Perhatikan bagaimana player0 diurutkan setelah semua kunci dengan kunci urut. player6 diurutkan setelah semua kunci dengan kunci urut numerik. player4 dan player5 memiliki kunci urut yang sama, jadi mereka diurutkan dalam urutan menaik berdasarkan kunci.

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 berhasil.")
end

Dapatkan data

Anda dapat mengambil nilai dan kunci urut yang terkait dengan kunci tertentu atau mendapatkan beberapa nilai dan kunci urut untuk kunci dalam jangkauan.

Dapatkan data dengan satu kunci

Untuk mendapatkan nilai dan kunci urut yang terkait dengan satu kunci dari peta terurut, panggil MemoryStoreSortedMap:GetAsync() dengan nama kunci.

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 berhasil.")
end

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

Dapatkan data dengan beberapa kunci

Untuk mendapatkan data untuk beberapa kunci dari peta terurut sebagai satu operasi, panggil MemoryStoreSortedMap:GetRangeAsync(). Fungsi ini secara default mencantumkan semua kunci yang ada, tetapi Anda dapat menetapkan batas atas dan bawah untuk jangkauan kunci. Misalnya, contoh kode berikut mengambil hingga 20 item yang dimulai dari awal peta terurut, dengan kunci yang lebih besar atau sama dengan 10, kunci urut yang lebih besar atau sama dengan 100 dan kunci yang lebih kecil atau sama dengan 50, kunci urut yang lebih kecil atau sama dengan 500.

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

-- Ambil hingga 20 item mulai dari awal
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

Perbarui data

Untuk mengambil nilai dan kunci urut dari kunci dari peta terurut dan memperbaruinya, panggil MemoryStoreSortedMap:UpdateAsync() dengan nama kunci, fungsi callback untuk memperbarui nilai dan kunci urut untuk kunci ini, dan waktu kadaluarsa dalam detik. Waktu kadaluarsa maksimum adalah 3.888.000 detik (45 hari).

Untuk kebanyakan game, beberapa server dapat memperbarui kunci yang sama secara bersamaan dan mengubah nilainya. Karena UpdateAsync() selalu memodifikasi nilai terbaru sebelum memperbarui, Anda harus menggunakannya untuk membaca nilai terbaru sebagai input untuk fungsi callback Anda.

Misalnya, contoh kode berikut memperbarui skor dalam papan peringkat untuk seorang pemain. Skor dihitung sebagai kills / deaths. UpdateAsync() memastikan bahwa kills dan deaths diperbarui untuk nilai yang paling baru bahkan jika beberapa server game memperbarui item yang sama secara bersamaan. Kills dan deaths seorang pemain adalah nilai yang meningkat monotonis dan karenanya hanya dapat bertambah nilainya dalam satu sesi.

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` adalah kunci urut yang digunakan untuk mengurutkan item dalam peta
				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

Latensi untuk UpdateAsync() mirip dengan GetAsync() dan SetAsync() kecuali jika ada kontensi.

Ketika kontensi terjadi, sistem secara otomatis mencoba ulang operasi sampai salah satu dari ketiga hal ini terjadi: operasi berhasil, fungsi callback mengembalikan nil, atau jumlah maksimum pengulangan tercapai. Jika sistem mencapai jumlah maksimum pengulangan, itu mengembalikan konflik.

Hapus data

Anda dapat menggunakan MemoryStoreSortedMap:RemoveAsync() untuk menghapus satu kunci dari peta terurut dan menghapus semua data dalam peta terurut penyimpanan memori.

Hapus kunci

Untuk menghapus kunci dari peta terurut, panggil MemoryStoreSortedMap:RemoveAsync() dengan nama kunci.

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 berhasil.")
end

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

Hapus semua data

Untuk menghapus memori dalam peta terurut, daftarkan semua kunci Anda dengan MemoryStoreSortedMap:GetRangeAsync(), kemudian hapus dengan MemoryStoreSortedMap:RemoveAsync().

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

-- Batas bawah awal dari nil memulai pembersihan dari item pertama
local exclusiveLowerBound = nil

while true do
	-- Ambil hingga seratus item mulai dari batas bawah saat ini
	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

		-- Jika terdapat kesalahan saat menghapus item, coba lagi dengan batas bawah eksklusif yang sama
		if not removeSuccess then
			warn(removeError)
		-- Jika jangkauan kurang dari seratus item, akhir peta telah tercapai
		elseif #items < 100 then
			break
		else
			-- Kunci terakhir yang diambil adalah batas bawah eksklusif untuk iterasi berikutnya
			exclusiveLowerBound = {}
			exclusiveLowerBound["key"] = items[#items].key
			exclusiveLowerBound["sortKey"] = items[#items].sortKey
		end
	end
end

Dapatkan ukuran

Untuk mendapatkan jumlah item dalam peta terurut, panggil MemoryStoreSortedMap:GetSizeAsync().

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 berhasil.")
end

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

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