Bản đồ kho lưu trữ bộ nhớ

Bản đồ hash , tương tự như bản đồ sắp xếp, cho phép bạn lưu dữ liệu trong bộ nhớ như cặp chìa khóa-giá trị.Không giống như bản đồ được sắp xếp, chúng không duy trì bảo đảm xếp hạng.Cấu trúc dữ liệu này hữu ích cho các trường hợp yêu cầu lưu trữ dữ liệu đơn giản và truy cập nhanh, chẳng hạn như kho chia sẻ, nhà đấu giá vật lý và nhiều hơn nữa.Bản đồ hash tự động xử lý phân chia dữ liệu của bạn và rất hữu ích nếu bạn có hơn 1,000 chìa khóa.Đối với không gian chìa khóa nhỏ hơn, chúng tôi khuyên bạn nên sử dụng bản đồ sắp xếp.

Giới hạn

Bản đồ hash có giới hạn kích thước chìa khóa là 128 ký tự và giới hạn kích thước giá trị là 32 KB.

Nếu không, bản đồ hash sử dụng cùng yêu cầu API và giới hạn bộ nhớ tương tự như các cấu trúc dữ liệu khác của kho lưu trữ nhớ.

Nhận bản đồ hash

Để có được bản đồ hash, gọi MemoryStoreService:GetHashMap() với tên cho bản đồ hash.Tên là toàn cầu trong trải nghiệm, vì vậy bạn có thể truy cập cùng một bản đồ hash trên bất kỳ kịch bản nào bằng cách sử dụng tên này.

Nhận bản đồ Hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

Sau khi có bản đồ hash, hãy gọi bất kỳ chức năng nào sau đây để đọc hoặc ghi dữ liệu vào nó:

Đối với tài liệu chi tiết về mỗi chức năng, xem MemoryStoreHashMap .

Thêm hoặc ghi đè dữ liệu

Để thêm một chìa khóa mới hoặc ghi đè giá trị của một chìa khóa trong bản đồ hash, gọi MemoryStoreHashMap:SetAsync() với chìa khóa tên , giá trị của nó , và thời gian hết hạn trong giây lát .Bộ nhớ tự động dọn dẹp một khi chìa khóa hết hạn.Thời gian hết hạn tối đa là 3,888,000 giây (45 ngày).

Thêm dữ liệu vào bản đồ 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("Set succeeded.")
end

Nhận dữ liệu

Bạn có thể nhận được một giá trị liên quan đến một chìa khóa cụ thể hoặc nhận nhiều cặp chìa khóa-giá trị trong bản đồ hash.

Nhận dữ liệu với một chìa khóa

Để lấy một giá trị liên quan đến một chìa khóa từ bản đồ hash, gọi MemoryStoreHashMap:GetAsync() với chìa khóa tên .

Nhận một chìa khóa cụ thể từ bản đồ 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("Set succeeded.")
end

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

Nhận dữ liệu với nhiều cặp chìa khóa-giá trị

Để lấy tất cả các cặp chìa khóa-giá trị từ bản đồ hash như một lần thực hiện duy nhất, hãy gọi MemoryStoreHashMap:ListItemsAsync() với kích thước trang mong muốn.Chức năng này liệt kê tất cả các chìa khóa hiện có theo cách phân trang.Ví dụ, mã mẫu sau đây lấy lại tối đa 32 vật phẩm từ bản đồ hash.

Danh sách vật phẩm trong Bản đồ Hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Nhận danh sách các mục, 32 mục cùng một lúc
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Lấy trang hiện tại
		local entries = pages:GetCurrentPage()
		-- Lặp qua tất cả các cặp chìa khóa-giá trị trên trang
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Kiểm tra xem trang cuối cùng đã được truy cập hay chưa
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Tiến tới trang tiếp theo
			pages:AdvanceToNextPageAsync()
		end
	end
end

Cập nhật dữ liệu

Để lấy giá trị của một chìa khóa từ bản đồ hash và cập nhật nó, gọi MemoryStoreHashMap:UpdateAsync() với chìa khóa tên , một chức năng gọi lại để cập nhật chìa khóa, và một thời gian hết hạn trong giây lát.

Đối với hầu hết các trải nghiệm, nhiều máy chủ có thể cập nhật cùng một chìa khóa cùng một lúc và thay đổi giá trị.Vì UpdateAsync() luôn luôn sửa giá trị mới nhất trước khi cập nhật, bạn nên sử dụng nó để đọc giá trị mới nhất làm đầu vào cho chức năng gọi lại của bạn.

Ví dụ, mã mẫu sau đây cập nhật số lượng tài nguyên của một tài nguyên trong kho chia sẻ.UpdateAsync() đảm bảo rằng tất cả các đóng góp của người chơi sẽ đi vào kho chia sẻ này, ngay cả khi các đóng góp này được thực hiện cùng một lúc.Trong chức năng này, nó cũng áp dụng một số lượng tài nguyên tối đa là 500.

Cập nhật số lượng tài nguyên cho một tài nguyên trong kho chia sẻ
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

			-- đảm bảo chúng tôi không vượt quá số lượng tài nguyên tối đa
			if resource.count > 500 then
				resource.count = 500
			end
			return resource
		end, 1200)
	end)
	if success then
		print(newResourceCount)
	end
end

Thời gian trễ cho UpdateAsync() giống như GetAsync() và SetAsync() trừ khi có sự cạnh tranh.

Khi xảy ra tranh chấp, hệ thống tự động thử lại hoạt động cho đến khi một trong ba xảy ra: hoạt động thành công, chức năng gọi lại trả về nil , hoặc số lần thử lại tối đa được đạt được.Nếu hệ thống đạt đến số lần thử lại tối đa, nó trả về một xung đột.

Xóa dữ liệu

Bạn có thể sử dụng MemoryStoreHashMap:RemoveAsync() để xóa một chìa khóa khỏi bản đồ hash và xóa tất cả dữ liệu trong bản đồ khóa ký ức.

Xóa một chìa khóa

Để xóa một chìa khóa khỏi bản đồ hash, gọi MemoryStoreHashMap:RemoveAsync() với một chìa khóa tên .

Xóa một chìa khóa từ bản đồ 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("Set succeeded.")
end

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

Xóa tất cả dữ liệu

Để xóa tất cả dữ liệu trong bản đồ hash, liệt kê tất cả các mục của bạn với MemoryStoreHashMap:ListItemsAsync() , sau đó xóa chúng với MemoryStoreHashMap:RemoveAsync() .

Xóa tất cả dữ liệu trong Bản đồ Hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Nhận danh sách các mục, 32 mục cùng một lúc
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Lấy trang hiện tại
		local entries = pages:GetCurrentPage()
		local removeSuccess = true
		local removeError = nil
		-- Lặp qua tất cả các cặp chìa khóa-giá trị trên trang
		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
		-- Kiểm tra xem trang cuối cùng đã được truy cập hay chưa
		if pages.IsFinished then
			print("Finished deleting all data.")
			break
		else
			print("----------")
			-- Tiến tới trang tiếp theo
			pages:AdvanceToNextPageAsync()
		end
	end
end