記憶體儲存雜湊表 | 文件 - Roblox 創作者中心

雜湊表，類似於排序映射，讓你以鍵-值對的形式存儲記憶體中的數據。與排序映射不同的是，它們不維持任何排序的保證。這種資料結構在需要簡單的數據快取和快速訪問的情況下非常有用，例如共享庫存、實體拍賣行等。如果你的鍵數量超過 1,000，雜湊表會自動處理數據的分區。如果鍵空間較小，我們建議使用排序映射。

限制

雜湊表的鍵大小限制為 128 個字元，值大小限制為 32 KB。

除此之外，雜湊表使用與其他記憶體儲存資料結構相同的 API 請求和記憶體配額限制。

獲取雜湊表

要獲取雜湊表，請使用 MemoryStoreService:GetHashMap() 並指定雜湊表的名稱。名稱在遊戲中是全局的，因此你可以在任何腳本中使用這個名稱訪問相同的雜湊表。

獲取雜湊表
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

獲取雜湊表後，可以調用以下任何函數來讀取或寫入數據：

函數	操作
MemoryStoreHashMap:SetAsync()	添加新的鍵，或在該鍵已存在的情況下覆蓋其值。
MemoryStoreHashMap:GetAsync()	讀取特定的鍵。
MemoryStoreHashMap:ListItemsAsync()	列舉雜湊表中的項目。
MemoryStoreHashMap:UpdateAsync()	更新從雜湊表中檢索的鍵的值。
MemoryStoreHashMap:RemoveAsync()	移除雜湊表中的鍵。

有關每個函數的詳細文檔，請參見 MemoryStoreHashMap。

所有訪問記憶體儲存中數據結構的函數都是異步網絡調用，可能會偶爾失敗。你應該將這些調用包裝在 pcall() 中以捕獲並處理錯誤，如代碼示例所示。

添加或覆蓋數據

要添加新的鍵或覆蓋雜湊表中鍵的值，請調用 MemoryStoreHashMap:SetAsync()，並傳遞鍵名稱、其值以及過期時間（以秒為單位）。一旦鍵過期，記憶體會自動清理。最大過期時間為 3,888,000 秒（45 天）。

根據歐盟通用數據保護條例（GDPR），如果你的記憶體儲存中有受被遺忘權影響的用戶數據，你必須在 30 天內刪除該數據，即使你將記憶體儲存鍵的過期時間設置為 45 天。

向雜湊表添加數據
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("設置成功。")
end

獲取數據

你可以根據特定鍵獲取關聯的值，也可以獲取雜湊表中的多個鍵-值對。

通過單個鍵獲取數據

要根據一個鍵從雜湊表中獲取值，請使用 MemoryStoreHashMap:GetAsync() 並傳遞鍵名稱。

從雜湊表獲取特定鍵
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("設置成功。")
end

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

通過多個鍵-值對獲取數據

要一次性獲取所有鍵-值對，可以使用 MemoryStoreHashMap:ListItemsAsync()，並指定所需的頁面大小。此函數以翻頁的方式列出所有現有鍵。例如，以下代碼示例從雜湊表中檢索最多 32 個項目。

列出雜湊表中的項目
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- 每次獲取 32 個項目的列表
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- 獲取當前頁面
		local entries = pages:GetCurrentPage()
		-- 遍歷頁面上的所有鍵-值對
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- 檢查是否已達到最後一頁
		if pages.IsFinished then
			break
		else
			print("----------")
			-- 前進到下一頁
			pages:AdvanceToNextPageAsync()
		end
	end
end

更新數據

要從雜湊表中檢索鍵的值並更新它，請使用 MemoryStoreHashMap:UpdateAsync()，傳遞鍵名稱、一個回調函數來更新該鍵，以及以秒為單位的過期時間。

對於大多數遊戲而言，多個伺服器可以同時更新相同的鍵並更改其值。由於 MemoryStoreHashMap:UpdateAsync() 總是先修改最新的值再進行更新，因此應該用它來讀取最新值作為回調函數的輸入。

例如，以下代碼示例更新了共享庫存中某項資源的數量。MemoryStoreHashMap:UpdateAsync() 確保所有玩家的貢獻都會進入這個共享庫存，即使這些貢獻同時進行。在這個函數中，還強制最大資源數量為 500。

更新共享庫存中資源的數量
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

			-- 確保不超過最大資源數量
			if resource.count > 500 then
				resource.count = 500
			end
			return resource
		end, 1200)
	end)
	if success then
		print(newResourceCount)
	end
end

MemoryStoreHashMap:UpdateAsync() 的延遲類似於 MemoryStoreHashMap:GetAsync() 和 MemoryStoreHashMap:SetAsync()，除非出現競爭條件。

當競爭條件發生時，系統會自動重試該操作，直到以下三種情況之一發生：操作成功，回調函數返回 nil，或者達到最大重試次數。如果系統達到最大重試次數，將返回衝突。

移除數據

你可以使用 MemoryStoreHashMap:RemoveAsync() 移除雜湊表中的一個鍵，或刪除記憶體儲存雜湊表中的所有數據。

移除一個鍵

要從雜湊表中移除一個鍵，請使用 MemoryStoreHashMap:RemoveAsync() 並傳遞鍵名稱。

從雜湊表中移除一個鍵
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("設置成功。")
end

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

刪除所有數據

要刪除雜湊表中的所有數據，使用 MemoryStoreHashMap:ListItemsAsync() 列出所有項目，然後使用 MemoryStoreHashMap:RemoveAsync() 將它們移除。

刪除雜湊表中的所有數據
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- 每次獲取 32 個項目的列表
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- 獲取當前頁面
		local entries = pages:GetCurrentPage()
		local removeSuccess = true
		local removeError = nil
		-- 遍歷頁面上的所有鍵-值對
		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
		-- 檢查是否已達到最後一頁
		if pages.IsFinished then
			print("已完成刪除所有數據。")
			break
		else
			print("----------")
			-- 前進到下一頁
			pages:AdvanceToNextPageAsync()
		end
	end
end