메모리 저장소 해시 맵 | 설명서 - Roblox 크리에이터 허브

해시 맵은 정렬된 맵과 유사하게 데이터 저장소를 키-값 쌍으로 메모리에 저장합니다. 정렬된 맵과 달리 해시 맵은 순서 보장을 하지 않습니다. 이 데이터 구조는 공유 인벤토리, 물리적 경매장 등과 같이 간단한 데이터 캐싱과 빠른 접근이 필요한 경우에 유용합니다. 해시 맵은 데이터를 자동으로 분할 처리하며, 1,000개 이상의 키가 있는 경우 매우 유용합니다. 더 작은 키 공간의 경우 정렬된 맵을 추천합니다.

제한 사항

해시 맵의 키 크기 제한은 128자이며, 값 크기 제한은 32KB입니다.

그 외에도 해시 맵은 다른 메모리 저장소 데이터 구조와 동일한 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()를 호출하세요.

대부분의 게임에서는 여러 서버가 동일한 키를 동시에 업데이트하고 값을 변경할 수 있습니다. 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