記憶體儲存排序地圖

排序地圖 數據結構的記憶存儲允許您將頻繁的內存數據存儲為鑰匙值對，並附有可選排序鑰匙，以維持基於排序鑰匙和鑰匙的特定順序。與排隊不同，進入地圖的鑰匙順序不會決定處理順序，使排序的地圖對排序基於數據組織的實現有用，例如排行榜和跨服務器拍賣的排名。

限制

除了 數據結構尺寸限制 外，排序地圖還有 128 個字元的鑰匙尺寸限制、32 KB 的值尺寸限制和 128 個字元的排序鑰匙限制。

如果您需要為體驗存儲超出此限制的數據，您可以通過碎片技術將它們分割並通過 鑰匙前缀 分配到多個數據結構中。碎片化記憶存儲也可以幫助改善您的系統的可擴展性。

獲得排序的地圖

要獲得排序的地圖，請呼叫 MemoryStoreService:GetSortedMap() 使用 名稱 您想為地圖定義的名稱。名稱在體驗中是全球的，因此您可以使用名稱存取任何腳本的相同排序地圖。

取得排序的地圖
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

在你獲得排序的地圖之後，呼叫以下任何一個函數來在其中閱讀或寫入數據：

添加或覆蓋數據

要在排序地圖中添加新的鑰匙或覆蓋鑰匙的值或排序鑰匙的值，請使用 MemoryStoreSortedMap:SetAsync() 鑰匙 名稱 、其 值 、秒內的 過期時間 和一個 可選排序鑰匙 。記憶將在鑰匙過期時自動清理。最長有效時間為 3,888,000 秒（45 天）。如果提供，排序鍵必須是有效的數字（整數或浮點）或字串。

在您的鑰匙排序順序中，排序鑰匙會優先於鑰鍵。例如，當按升序排序時，數字排序鑰匙先排序，然後是字串排序鑰匙，然後是沒有排序鑰鍵的項目。所有具有數字排序鑰匙的項目都會按排序鑰匙排序，如果兩個項目的排序鑰匙相同，則按鍵匙排鍵。相同地，所有擁有字串排序鑰匙的項目都會依排序鑰匙排序，如果兩個項目的排序鑰匙相同，則會依鑰匙排序。沒有排序鑰匙的所有項目只會按鍵匙排序。

一些數據排序在上升順序的例子 -

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

注意如何 player0 排序所有具有排序鍵的鍵。player6排序所有具有數字排序鑰匙的鍵後。player4 和 player5 具有相同的排序鑰匙，因此按鑰匙排序在上升順序。

將資料添加到排序的地圖
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

取得資料

您可以獲得與特定鑰匙相關的數值和排序鑰匙，或獲得範圍內鑰匙的多個值和排序鑰匙。

使用一個鑰匙獲取資鍵

要從排序地圖中獲得與一個鑰匙相關的值和排序鑰匙，請使用鑰匙 MemoryStoreSortedMap:GetAsync() 呼叫 **** 。

從排序地圖獲得特定鑰匙
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

使用多個鑰匙取得資料

若要從排序的地圖獲得多個鑰匙的資料作為單一操作，請呼叫 MemoryStoreSortedMap:GetRangeAsync() 。此功能預設列出所有現有鑰匙，但您可以設置鑰匙範圍的上限和下限。例如，以下代碼樣本可以檢索到最多 20 個項目，從排序地圖的開始時間起，其鑰匙大於或等於 10 、排序鑰匙大於或等於 100 和鑰匙小於或等於 50 、排序鑰匙小於或等於 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

-- 從一開始就獲得最多 20 個項目
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

更新資料

要從排序的地圖中恢復值和排序鑰匙的值並更新它，請使用 MemoryStoreSortedMap:UpdateAsync() 鑰匙 名稱 來呼叫 回調函數 來更新此鍵匙的值和排序鑰匙，以及在秒數內的 過期時間 。最長有效時間為 3,888,000 秒（45 天）。

對於大多數體驗，多個伺服器可以同時更新相同的鑰匙並更改值。因為 UpdateAsync() 總是在更新前修改最新值，你應該使用它來閱讀最新值作為回調函數的輸入。

例如，以下代碼樣本會更新遊戲中玩家的排名榜分數。得分計算為擊殺/死亡。UpdateAsync()確保在多個遊戲伺服器同時更新相同項目的情況下，最新的擊殺和死亡值也會更新到最新值。玩家的擊殺和死亡是一致增加的值，因此只能在一個會作業中增加值。

在排序地圖中更新玩家的排行榜分數
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` 是用於在地圖中排序項目的排序鑰匙
				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

對於 UpdateAsync() 的延遲類似於 GetAsync() 和 SetAsync() ，除非存在競爭。

當爭議發生時，系統會自動重試操作，直到其中一個發生：操作成功、回呼函返回 nil 或最大重試次數達到。如果系統達到重試次數上限，它會返回一個衝突。

移除資料

您可以使用 MemoryStoreSortedMap:RemoveAsync() 來從排序地圖中移除一個鑰匙和刪除記憶庫排序地圖中的所有數據。

移除鑰鍵

要從排序的地圖中移除鑰匙，請使用 MemoryStoreSortedMap:RemoveAsync() 鑰匙 名稱 來呼叫。

從排序地圖中移除鑰匙
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

刪除所有資料

要刪除排序的地圖中的記憶，請用 MemoryStoreSortedMap:GetRangeAsync() 列出所有的鑰匙，然後用 MemoryStoreSortedMap:RemoveAsync() 移除它們。

在排序地圖中刪除記憶體
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

-- 初始零值下限從第一個道具目開始刷新
local exclusiveLowerBound = nil

while true do
	-- 從目前的最低限度開始，獲得最多一百個項目
	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

		-- 如果移除項目時發生錯誤，請再試一次，使用相同的獨家下限
		if not removeSuccess then
			warn(removeError)
		-- 如果範圍少於一百個項目，地圖盡頭已達到
		elseif #items < 100 then
			break
		else
			-- 最後一次取得的鑰匙是下一個循環的獨家下限
			exclusiveLowerBound = {}
			exclusiveLowerBound["key"] = items[#items].key
			exclusiveLowerBound["sortKey"] = items[#items].sortKey
		end
	end
end