Bản đồ đã sắp xếp trong bộ nhớ

Cấu trúc dữ liệu bản đồ đã sắp xếp của các kho nhớ cho phép bạn lưu trữ dữ liệu thường xuyên trong bộ nhớ dưới dạng cặp khóa-giá trị với một khóa sắp xếp tùy chọn và duy trì một thứ tự cụ thể dựa trên các khóa sắp xếp và khóa. Khác với hàng đợi, thứ tự của các khóa vào trong bản đồ không xác định thứ tự xử lý, khiến bản đồ đã sắp xếp hữu ích cho việc tổ chức dữ liệu theo kiểu sắp xếp để triển khai các thực thể trong trò chơi cho sự tương tác như bảng xếp hạng và đấu giá giữa các máy chủ.

Giới hạn

Ngoài giới hạn kích thước cấu trúc dữ liệu, bản đồ đã sắp xếp có giới hạn kích thước khóa là 128 ký tự, giới hạn kích thước giá trị là 32 KB và giới hạn kích thước khóa sắp xếp là 128 ký tự.

Nếu bạn cần lưu trữ dữ liệu vượt quá giới hạn này cho trò chơi của mình, bạn có thể áp dụng kỹ thuật chia khối để phân chia và phân phối chúng qua tiền tố khóa vào nhiều cấu trúc dữ liệu khác nhau. Chia khối các kho nhớ cũng có thể giúp cải thiện khả năng mở rộng của hệ thống của bạn.

Lấy một bản đồ đã sắp xếp

Để lấy một bản đồ đã sắp xếp, gọi MemoryStoreService:GetSortedMap() với một tên mà bạn muốn xác định cho bản đồ. Tên này là toàn cầu trong trò chơi, vì vậy bạn có thể truy cập cùng một bản đồ đã sắp xếp trong bất kỳ tập lệnh nào bằng cách sử dụng tên đó.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

Sau khi bạn lấy được một bản đồ đã sắp xếp, hãy gọi bất kỳ hàm nào sau đây:

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

Để thêm một khóa mới hoặc ghi đè lên giá trị hoặc khóa sắp xếp của một khóa trong bản đồ đã sắp xếp, hãy gọi MemoryStoreSortedMap:SetAsync() với tên khóa, giá trị của nó, thời gian hết hạn tính bằng giây và một khóa sắp xếp tùy chọn. Bộ nhớ tự động dọn dẹp khi 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). Khóa sắp xếp, nếu được cung cấp, phải là một số hợp lệ (nguyên hoặc số thực) hoặc một chuỗi.

Trong thứ tự sắp xếp của các khóa của bạn, một khóa sắp xếp có ưu tiên hơn một khóa. Ví dụ, khi sắp xếp theo thứ tự tăng dần, các khóa sắp xếp số sẽ được sắp xếp trước, tiếp theo là các khóa sắp xếp chuỗi, và cuối cùng là các mục không có khóa sắp xếp. Tất cả các mục có khóa sắp xếp số sẽ được sắp xếp theo khóa sắp xếp, nếu khóa sắp xếp cho hai mục bằng nhau, chúng sẽ được sắp xếp theo khóa. Tương tự, tất cả các mục có khóa sắp xếp chuỗi sẽ được sắp xếp theo khóa sắp xếp, nếu khóa sắp xếp cho hai mục bằng nhau, chúng sẽ được sắp xếp theo khóa. Tất cả các mục không có khóa sắp xếp chỉ được sắp xếp theo khóa.

Ví dụ về một số dữ liệu được sắp xếp theo thứ tự tăng dần -

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

Lưu ý cách player0 được phân loại sau tất cả các khóa có khóa sắp xếp. player6 được phân loại sau tất cả các khóa có khóa sắp xếp số. player4 và player5 có cùng một khóa sắp xếp, vì vậy chúng được phân loại theo thứ tự tăng dần theo khóa.

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("Thêm thành công.")
end

Lấy dữ liệu

Bạn có thể lấy giá trị và khóa sắp xếp liên quan đến một khóa cụ thể hoặc lấy nhiều giá trị và khóa sắp xếp cho các khóa trong một phạm vi.

Lấy dữ liệu với một khóa

Để lấy một giá trị và khóa sắp xếp liên quan đến một khóa từ bản đồ đã sắp xếp, hãy gọi MemoryStoreSortedMap:GetAsync() với tên khóa.

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("Thêm thành công.")
end

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

Lấy dữ liệu với nhiều khóa

Để lấy dữ liệu cho nhiều khóa từ bản đồ đã sắp xếp như một thao tác duy nhất, gọi MemoryStoreSortedMap:GetRangeAsync(). Hàm này liệt kê tất cả các khóa hiện có theo mặc định, nhưng bạn có thể đặt giới hạn trên và giới hạn dưới cho phạm vi khóa. Ví dụ, đoạn mã sau đây lấy tối đa 20 mục bắt đầu từ đầu bản đồ đã sắp xếp, với các khóa lớn hơn hoặc bằng 10, khóa sắp xếp lớn hơn hoặc bằng 100 và các khóa nhỏ hơn hoặc bằng 50, khóa sắp xếp nhỏ hơn hoặc bằng 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

-- Lấy tối đa 20 mục bắt đầu từ đầu
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

Cập nhật dữ liệu

Để lấy giá trị và khóa sắp xếp của một khóa từ bản đồ đã sắp xếp và cập nhật nó, hãy gọi MemoryStoreSortedMap:UpdateAsync() với tên khóa, một hàm gọi lại để cập nhật giá trị và khóa sắp xếp cho khóa này và một thời gian hết hạn tính bằng giây. Thời gian hết hạn tối đa là 3,888,000 giây (45 ngày).

Đối với hầu hết các trò chơi, nhiều máy chủ có thể cập nhật cùng một khóa đồng thời và thay đổi giá trị. Vì UpdateAsync() luôn sửa đổi 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 hàm gọi lại của bạn.

Ví dụ, đoạn mã sau đây cập nhật điểm số trong bảng xếp hạng cho một người chơi. Điểm số được tính là số lần giết / số lần chết. UpdateAsync() đảm bảo rằng số lần giết và số lần chết được cập nhật cho các giá trị mới nhất ngay cả khi nhiều máy chủ trò chơi cập nhật cùng một mục một cách đồng thời. Số lần giết và số lần chết của một người chơi là các giá trị tăng liên tục và do đó chỉ có thể tăng trong một phiên.

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` là khóa sắp xếp được sử dụng để sắp xếp các mục trong bản đồ
				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

Độ trễ cho UpdateAsync() tương tự như GetAsync() và SetAsync() trừ khi có sự tranh chấp.

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

Xóa dữ liệu

Bạn có thể sử dụng MemoryStoreSortedMap:RemoveAsync() để xóa một khóa từ bản đồ đã sắp xếp và xóa tất cả dữ liệu trong một bản đồ đã sắp xếp trong bộ nhớ.

Xóa một khóa

Để xóa một khóa khỏi bản đồ đã sắp xếp, gọi MemoryStoreSortedMap:RemoveAsync() với tên khóa.

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("Thêm thành công.")
end

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

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

Để xóa bộ nhớ trong các bản đồ đã sắp xếp, liệt kê tất cả các khóa của bạn bằng MemoryStoreSortedMap:GetRangeAsync(), sau đó xóa chúng bằng MemoryStoreSortedMap:RemoveAsync().

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

-- Giới hạn dưới ban đầu là nil bắt đầu xóa từ mục đầu tiên
local exclusiveLowerBound = nil

while true do
	-- Lấy tối đa một trăm mục bắt đầu từ giới hạn dưới hiện tại
	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

		-- Nếu có lỗi khi xóa các mục, thử lại với cùng một giới hạn dưới không bao gồm
		if not removeSuccess then
			warn(removeError)
		-- Nếu số lượng trong phạm vi ít hơn một trăm mục, đã đạt đến cuối bản đồ
		elseif #items < 100 then
			break
		else
			-- Khóa được lấy cuối cùng là giới hạn dưới không bao gồm cho vòng lặp tiếp theo
			exclusiveLowerBound = {}
			exclusiveLowerBound["key"] = items[#items].key
			exclusiveLowerBound["sortKey"] = items[#items].sortKey
		end
	end
end

Lấy kích thước

Để lấy số lượng mục trong bản đồ đã sắp xếp, hãy gọi 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("Thêm thành công.")
end

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

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