Peta Terurut Penyimpanan Memori

Struktur data peta terurut dari penyimpanan memori memungkinkan Anda untuk menyimpan data dalam memori yang sering digunakan sebagai pasangan kunci-nilai dengan kunci urut opsional dan mempertahankan urutan tertentu berdasarkan kunci urut dan kunci. Berbeda dengan antrian, urutan kunci yang memasuki peta tidak menentukan urutan pemrosesan, menjadikan peta terurut berguna untuk organisasi data yang berbasis urutan dalam mengimplementasikan entitas dalam permainan untuk keterlibatan seperti papan peringkat dan lelang antar-server.

Batasan

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 permainan Anda, Anda dapat mengadopsi teknik sharding untuk memecah dan mendistribusikannya melalui prefiks kunci ke beberapa struktur data. Sharding 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 ini bersifat global dalam permainan, sehingga Anda dapat mengakses peta terurut yang sama di skrip mana pun menggunakan nama tersebut.

Mendapatkan Peta Terurut
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

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

Tambah atau ganti data

Untuk menambah kunci baru atau mengganti nilai atau kunci urut suatu kunci dalam peta terurut, panggil MemoryStoreSortedMap:SetAsync() dengan nama kunci, nilai-nya, waktu kedaluwarsa dalam detik dan kunci urut opsional. Memori akan otomatis membersihkan setelah kunci kadaluwarsa. Waktu kedaluwarsa maksimum adalah 3.888.000 detik (45 hari). Kunci urut, jika disediakan, harus berupa angka yang valid (bilangan bulat atau floating point) atau string.

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

Contoh beberapa data yang disortir 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 terurut setelah semua kunci dengan kunci urut. player6 terurut setelah semua kunci dengan kunci urut numerik. player4 dan player5 memiliki kunci urut yang sama, sehingga mereka diurutkan dalam urutan menaik menurut kunci.

Menambahkan Data ke Peta Terurut
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 mengget nilai data dan kunci urut yang terkait dengan kunci tertentu atau mendapatkan beberapa nilai dan kunci urut untuk kunci dalam rentang.

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.

Mendapatkan Kunci Tertentu dari Peta Terurut
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 operasi tunggal, panggil MemoryStoreSortedMap:GetRangeAsync(). Fungsi ini secara default mencantumkan semua kunci yang ada, tetapi Anda dapat menetapkan batas atas dan batas bawah untuk rentang kunci. Misalnya, contoh kode berikut mengambil hingga 20 item mulai dari awal peta terurut, dengan kunci lebih besar dari atau sama dengan 10, kunci urut lebih besar dari atau sama dengan 100 dan kunci kurang dari atau sama dengan 50, kunci urut kurang dari atau sama dengan 500.

Mendapatkan Rentang Kunci dari Peta Terurut
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

-- Dapatkan 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 kedaluwarsa dalam detik. Waktu kedaluwarsa maksimum adalah 3.888.000 detik (45 hari).

Untuk sebagian besar permainan, 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.

Sebagai contoh, berikut adalah contoh kode yang memperbarui skor di papan peringkat untuk seorang pemain. Skor dihitung sebagai pembunuhan / kematian. UpdateAsync() memastikan bahwa pembunuhan dan kematian diperbarui untuk nilai terbaru meskipun beberapa server permainan memperbarui item yang sama secara bersamaan. Pembunuhan dan kematian seorang pemain adalah nilai yang monoton meningkat dan karena itu hanya dapat meningkat nilainya dalam satu sesi.

Memperbarui skor papan peringkat untuk seorang pemain di Peta Terurut
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("PapanPeringkat")

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.

Saat kontensi terjadi, sistem secara otomatis mencoba ulang operasi sampai salah satu dari tiga hal ini terjadi: operasi berhasil, fungsi callback mengembalikan nil, atau jumlah maksimum percobaan tercapai. Jika sistem mencapai jumlah maksimum percobaan, ia 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.

Hapus Kunci dari Peta Terurut
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(), lalu hapus dengan MemoryStoreSortedMap:RemoveAsync().

Hapus Memori dalam Peta Terurut
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

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

while true do
	-- Dapatkan 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 ada kesalahan saat menghapus item, coba lagi dengan batas bawah eksklusif yang sama
		if not removeSuccess then
			warn(removeError)
		-- Jika rentang 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().

Mendapatkan Ukuran dari Peta Terurut
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