Peta hash penyimpanan memori | Dokumentasi

Peta hash, mirip dengan peta terurut, memungkinkan Anda menyimpan data dalam memori sebagai pasangan kunci-nilai. Berbeda dengan peta terurut, mereka tidak mempertahankan jaminan urutan. Struktur data ini berguna untuk kasus yang memerlukan caching data sederhana dan akses cepat, seperti inventaris bersama, rumah lelang fisik, dan lainnya. Peta hash secara otomatis menangani pemisahan data Anda dan sangat berguna jika Anda memiliki lebih dari 1.000 kunci. Untuk ruang kunci yang lebih kecil, kami merekomendasikan peta terurut.

Batasan

Peta hash memiliki batas ukuran kunci sebesar 128 karakter dan batas ukuran nilai sebesar 32 KB.

Selain itu, peta hash menggunakan batasan yang sama pada permintaan API dan kuota memori seperti struktur data penyimpanan memori lainnya.

Mendapatkan peta hash

Untuk mendapatkan peta hash, panggil MemoryStoreService:GetHashMap() dengan nama untuk peta hash tersebut. Nama ini bersifat global dalam permainan, jadi Anda dapat mengakses peta hash yang sama di skrip mana pun menggunakan nama ini.

Mendapatkan Peta Hash

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

Setelah Anda mendapatkan peta hash, panggil salah satu fungsi berikut untuk membaca atau menulis data di dalamnya:

Fungsi	Action
MemoryStoreHashMap:SetAsync()	Tambahkan kunci baru atau timpa nilai jika kunci sudah ada.
MemoryStoreHashMap:GetAsync()	Baca kunci tertentu.
MemoryStoreHashMap:ListItemsAsync()	Daftar item di peta hash.
MemoryStoreHashMap:UpdateAsync()	Perbarui nilai kunci setelah mengambilnya dari peta hash.
MemoryStoreHashMap:RemoveAsync()	Hapus kunci dari peta hash.

Untuk dokumentasi mendalam tentang setiap fungsi, lihat MemoryStoreHashMap.

Semua fungsi yang mengakses struktur data di penyimpanan memori adalah panggilan jaringan asinkron yang mungkin kadang-kadang gagal. Anda harus membungkus panggilan ini dalam pcall() untuk menangkap dan menangani kesalahan, seperti yang ditunjukkan dalam contoh kode.

Tambahkan atau timpa data

Untuk menambahkan kunci baru atau menimpa nilai kunci di peta hash, panggil MemoryStoreHashMap:SetAsync() dengan nama kunci, nilai nya, dan waktu kedaluwarsa dalam detik. Memori secara otomatis membersihkan setelah kunci kadaluwarsa. Batas waktu kedaluwarsa maksimum adalah 3.888.000 detik (45 hari).

Menambahkan Data ke Peta Hash

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

Dapatkan data

Anda bisa mendapatkan nilai yang terkait dengan kunci tertentu atau mendapatkan beberapa pasangan kunci-nilai dalam peta hash.

Dapatkan data dengan satu kunci

Untuk mendapatkan nilai yang terkait dengan satu kunci dari peta hash, panggil MemoryStoreHashMap:GetAsync() dengan nama kunci.

Mendapatkan Kunci Tertentu dari Peta Hash

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

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

Dapatkan data dengan beberapa pasangan kunci-nilai

Untuk mendapatkan semua pasangan kunci-nilai dari peta hash dalam satu operasi, panggil MemoryStoreHashMap:ListItemsAsync() dengan ukuran halaman yang diinginkan. Fungsi ini mencantumkan semua kunci yang ada dengan cara yang dipaginasikan. Misalnya, contoh kode berikut mengambil hingga 32 item dari peta hash.

Mendaftar item di Peta Hash

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Dapatkan daftar item, 32 item sekaligus
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Dapatkan halaman saat ini
		local entries = pages:GetCurrentPage()
		-- Iterasi melalui semua pasangan kunci-nilai di halaman
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Periksa apakah halaman terakhir telah tercapai
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Lanjutkan ke halaman berikutnya
			pages:AdvanceToNextPageAsync()
		end
	end
end

Perbarui data

Untuk mengambil nilai dari kunci dalam peta hash dan memperbaruinya, panggil MemoryStoreHashMap:UpdateAsync() dengan nama kunci, sebuah fungsi callback untuk memperbarui kunci, dan waktu kedaluwarsa dalam detik.

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 masukan untuk fungsi callback Anda.

Sebagai contoh, kode berikut memperbarui jumlah sumber daya suatu item dalam inventaris bersama. UpdateAsync() memastikan bahwa semua kontribusi pemain akan masuk ke inventaris bersama ini, bahkan jika kontribusi ini dilakukan secara bersamaan. Dalam fungsi ini, juga ditegakkan batas maksimum jumlah sumber daya sebesar 500.

Memperbarui Jumlah Sumber Daya untuk Sumber Daya dalam Inventaris Bersama

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

			-- pastikan kita tidak melebihi jumlah sumber daya maksimum
			if resource.count > 500 then
				resource.count = 500
			end
			return resource
		end, 1200)
	end)
	if success then
		print(newResourceCount)
	end
end

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

Ketika kontensi terjadi, sistem secara otomatis mencoba lagi operasi tersebut hingga salah satu dari tiga ini terjadi: operasi berhasil, fungsi callback mengembalikan nil, atau jumlah maksimum percobaan tercapai. Jika sistem mencapai jumlah maksimum percobaan, maka akan mengembalikan konflik.

Hapus data

Anda dapat menggunakan MemoryStoreHashMap:RemoveAsync() untuk menghapus satu kunci dari peta hash serta menghapus semua data dalam peta hash penyimpanan memori.

Hapus sebuah kunci

Untuk menghapus satu kunci dari peta hash, panggil MemoryStoreHashMap:RemoveAsync() dengan nama kunci.

Hapus Kunci dari Peta Hash

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

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

Hapus semua data

Untuk menghapus semua data dalam peta hash, daftar semua item Anda dengan MemoryStoreHashMap:ListItemsAsync(), kemudian hapus dengan MemoryStoreHashMap:RemoveAsync().

Hapus semua data dalam Peta Hash

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Dapatkan daftar item, 32 item sekaligus
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Dapatkan halaman saat ini
		local entries = pages:GetCurrentPage()
		local removeSuccess = true
		local removeError = nil
		-- Iterasi melalui semua pasangan kunci-nilai di halaman
		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
		-- Periksa apakah halaman terakhir telah tercapai
		if pages.IsFinished then
			print("Selesai menghapus semua data.")
			break
		else
			print("----------")
			-- Lanjutkan ke halaman berikutnya
			pages:AdvanceToNextPageAsync()
		end
	end
end