메모리 저장소 해시 맵 | 설명서 - 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