記憶體存儲哈希表 | 文件 - 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 天）。

向哈希表添加數據

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()，並傳遞鍵名稱、一個回調函數來更新鍵，以及過期時間（以秒為單位）。

對於大多數遊戲，多個服務器可以同時更新同一鍵並更改其值。由於 UpdateAsync() 始終在更新之前修改最新值，因此您應該使用它來讀取最新值作為回調函數的輸入。

例如，以下代碼範例更新共享庫存中資源的數量。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

UpdateAsync() 的延遲類似於 GetAsync() 和 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