Bản đồ được sắp xếp kho lưu trí nhớ

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

Giới hạn

Ngoài giới hạn kích thước cấu trúc dữ liệu , các bản đồ sắp xếp có giới hạn kích thước chìa 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 chìa khóa sắp xếp là 128 ký tự.

Nếu bạn cần lưu trữ dữ liệu vượt giới hạn cho trải nghiệm của mình, bạn có thể áp dụng kỹ thuật phân mảnh để chia và phân phối chúng thông qua chữ cái chìa khóa vào nhiều cấu trúc dữ liệu.Kho lưu trữ bộ nhớ phân mả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.

Nhận bản đồ được sắp xếp

Để có được bản đồ được sắp xếp, gọi MemoryStoreService:GetSortedMap() với một tên bạn muốn định nghĩa cho bản đồ.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 đồ sắp xếp tương tự trên bất kỳ kịch bản nào bằng cách sử dụng tên.

Nhận bản đồ được sắp xếp
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

Sau khi bạn có được bản đồ được sắp xếp, gọi bất kỳ chức năng nào sau đây để đọc hoặc ghi dữ liệu vào nó:

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

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

Trong trật tự sắp xếp của các chìa khóa của bạn, một chìa khóa sắp xếp có ưu tiên hơn một chìa khóa.Ví dụ, khi sắp xếp theo thứ tự tăng dần, các chìa khóa sắp xếp số được sắp xếp trước, sau đó là chìa khóa sắp xếp chuỗi, sau đó là các mục không có chìa khóa sắp xếp.Tất cả các mục có chìa khóa sắp xếp theo số được sắp xếp theo chìa khóa sắp xếp, nếu chìa khóa sắp xếp cho hai mục bằng nhau, chúng được sắp xếp theo chìa khóa.Tương tự, tất cả các mục có chìa khóa sắp xếp chuỗi được sắp xếp theo chìa khóa sắp xếp, nếu chìa khóa sắp xếp cho hai mục bằng nhau, chúng được sắp xếp theo chìa khóa.Tất cả các mục không có chìa khóa sắp xếp chỉ bằng chìa 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 sắp xếp sau tất cả các chìa khóa với một chìa khóa sắp xếp.player6 sắp xếp sau tất cả các chìa khóa có chìa khóa sắp xếp theo số.player4 và player5 có cùng một chìa khóa loại, vì vậy chúng được sắp xếp theo thứ tự tăng dần theo chìa khóa.

Thêm dữ liệu vào bản đồ được sắp xếp
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 succeeded.")
end

Nhận dữ liệu

Bạn có thể nhận giá trị dữ liệu và sắp xếp chìa khóa liên quan đến một chìa khóa cụ thể hoặc nhận nhiều giá trị và sắp xếp chìa khóa cho các chìa khóa trong phạm vi.

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

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

Nhận một chìa khóa cụ thể từ một bản đồ được sắp xếp
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 succeeded.")
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 chìa khóa

Để lấy dữ liệu cho nhiều chìa khóa từ bản đồ sắp xếp như một hoạt động duy nhất, hãy gọi MemoryStoreSortedMap:GetRangeAsync() .Chức năng này liệt kê tất cả các chìa khóa hiện có theo mặc định, nhưng bạn có thể đặt giới hạn trên và dưới cho phạm vi chìa khóa.Ví dụ, mã mẫu sau đây lấy lại tối đa 20 vật phẩm bắt đầu từ đầu của bản đồ được sắp xếp, với các chìa khóa lớn hơn hoặc bằng 10 , sắp xếp chìa khóa lớn hơn hoặc bằng 100 và chìa khóa nhỏ hơn hoặc bằng 50 , sắp xếp chìa khóa nhỏ hơn hoặc bằng 500 .

Lấy một phạm vi các chìa khóa từ một bản đồ được sắp xếp
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

-- Nhận tối đa 20 vật phẩm 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à sắp xếp chìa khóa của một chìa khóa từ bản đồ được sắp xếp và cập nhật nó, gọi MemoryStoreSortedMap:UpdateAsync() với chìa khóa tên , một chức năng gọi lại **** để cập nhật giá trị và sắp xếp chìa khóa cho chìa khóa này, và một thời gian hết hạn trong giây lát .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ả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 điểm số trong bảng xếp hạng cho một người chơi trong một trò chơi.Điểm số được tính là số lần giết / chết.UpdateAsync() đảm bảo rằng các lượt giết và cái 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 tương tự cùng một lúc.Số lần giết và chết của một người chơi tăng lên theo cấp số nhân và chỉ có thể tăng giá trị trong một phiên.

Cập nhật điểm bảng xếp hạng cho một người chơi trong Bản đồ được sắp xếp
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à chìa 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

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 MemoryStoreSortedMap:RemoveAsync() để xóa một chìa khóa từ bản đồ được sắp xếp và xóa tất cả dữ liệu trong bản đồ lưu trữ bộ nhớ sắp xếp.

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

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

Loại bỏ một Chìa khóa từ Bản đồ được sắp xếp
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 succeeded.")
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 bản đồ được sắp xếp, liệt kê tất cả các chìa khóa của bạn với MemoryStoreSortedMap:GetRangeAsync() , sau đó xóa chúng với MemoryStoreSortedMap:RemoveAsync() .

Xóa bộ nhớ trong bản đồ được sắp xếp
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

-- Giới hạn thấp nhất ban đầu của nil bắt đầu thoát khỏi vật phẩm đầu tiên
local exclusiveLowerBound = nil

while true do
	-- Nhận lên đến hàng trăm vật phẩm bắt đầu từ giới hạn thấp hơn 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 xóa vật phẩm, hãy thử lại với giới hạn thấp độc quyền tương tự
		if not removeSuccess then
			warn(removeError)
		-- Nếu phạm vi nhỏ hơn một trăm vật phẩm, cuối bản đồ được đạt tới
		elseif #items < 100 then
			break
		else
			-- Chìa khóa cuối cùng được lấy lại là giới hạn thấp hơn độc quyền cho lần lặp tiếp theo
			exclusiveLowerBound = {}
			exclusiveLowerBound["key"] = items[#items].key
			exclusiveLowerBound["sortKey"] = items[#items].sortKey
		end
	end
end