Mapa hash do armazenamento em memória | Documentação

Mapas hash, similar a mapas ordenados, permitem que você armazene dados em memória como pares chave-valor. Ao contrário dos mapas ordenados, eles não mantêm garantias de ordenação. Esta estrutura de dados é útil para casos que exigem cache de dados simples e acesso rápido, como inventários compartilhados, leilões físicos e mais. Mapas hash gerenciam automaticamente a partição de seus dados e são muito úteis se você tiver mais de 1.000 chaves. Para espaços de chave menores, recomendamos mapas ordenados.

Limites

Mapas hash têm um limite de tamanho de chave de 128 caracteres e um limite de tamanho de valor de 32 KB.

Fora isso, mapas hash usam as mesmas limitações de solicitações de API e cota de memória que as outras estruturas de dados do armazenamento em memória.

Obter um mapa hash

Para obter um mapa hash, chame MemoryStoreService:GetHashMap() com um nome para o mapa hash. O nome é global dentro do jogo, então você pode acessar o mesmo mapa hash em qualquer script usando este nome.

Obtendo um Mapa Hash

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

Após obter um mapa hash, chame qualquer uma das seguintes funções para ler ou escrever dados nele:

Função	Ação
MemoryStoreHashMap:SetAsync()	Adicionar uma nova chave ou sobrescrever o valor se a chave já existir.
MemoryStoreHashMap:GetAsync()	Ler uma chave específica.
MemoryStoreHashMap:ListItemsAsync()	Listar itens em um mapa hash.
MemoryStoreHashMap:UpdateAsync()	Atualizar o valor de uma chave após recuperá-la de um mapa hash.
MemoryStoreHashMap:RemoveAsync()	Remover uma chave do mapa hash.

Para documentação detalhada sobre cada função, consulte MemoryStoreHashMap.

Todas as funções que acessam estruturas de dados em armazenamentos em memória são chamadas de rede assíncronas que podem ocasionalmente falhar. Você deve envolver essas chamadas em pcall() para capturar e tratar erros, como mostrado nos exemplos de código.

Adicionar ou sobrescrever dados

Para adicionar uma nova chave ou sobrescrever o valor de uma chave no mapa hash, chame MemoryStoreHashMap:SetAsync() com o nome da chave, seu valor, e um tempo de expiração em segundos. A memória limpa automaticamente uma vez que a chave expira. O tempo máximo de expiração é 3.888.000 segundos (45 dias).

Adicionando Dados a um Mapa Hash

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("Definição bem-sucedida.")
end

Obter dados

Você pode obter um valor associado a uma chave específica ou obter múltiplos pares chave-valor no mapa hash.

Obter dados com uma chave

Para obter um valor associado a uma chave no mapa hash, chame MemoryStoreHashMap:GetAsync() com o nome da chave.

Obtendo uma Chave Específica de um Mapa Hash

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("Definição bem-sucedida.")
end

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

Obter dados com múltiplos pares chave-valor

Para obter todos os pares chave-valor do mapa hash em uma única operação, chame MemoryStoreHashMap:ListItemsAsync() com o tamanho da página desejado. Esta função lista todas as chaves existentes de forma paginada. Por exemplo, o seguinte exemplo de código recupera até 32 itens do mapa hash.

Listando itens em um Mapa Hash

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Obter lista de itens, 32 itens por vez
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Obter a página atual
		local entries = pages:GetCurrentPage()
		-- Iterar por todos os pares chave-valor na página
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Verificar se a última página foi alcançada
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Avançar para a próxima página
			pages:AdvanceToNextPageAsync()
		end
	end
end

Atualizar dados

Para recuperar o valor de uma chave de um mapa hash e atualizá-lo, chame MemoryStoreHashMap:UpdateAsync() com o nome da chave, uma função de callback para atualizar a chave e um tempo de expiração em segundos.

Para a maioria dos jogos, múltiplos servidores podem atualizar a mesma chave simultaneamente e mudar o valor. Como UpdateAsync() sempre modifica o último valor antes de atualizar, você deve usá-lo para ler o último valor como a entrada para a sua função de callback.

Por exemplo, o seguinte exemplo de código atualiza a contagem de recursos de um recurso em um inventário compartilhado. UpdateAsync() garante que todas as contribuições dos jogadores entrem nesse inventário compartilhado, mesmo se essas contribuições forem feitas simultaneamente. Nesta função, também é aplicada uma contagem máxima de recursos de 500.

Atualizando a Contagem de Recursos para um Recurso em um Inventário Compartilhado

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

			-- garantir que não excedemos a contagem máxima de recursos
			if resource.count > 500 then
				resource.count = 500
			end
			return resource
		end, 1200)
	end)
	if success then
		print(newResourceCount)
	end
end

A latência para UpdateAsync() é similar a GetAsync() e SetAsync() a menos que haja contenda.

Quando ocorre contenda, o sistema automaticamente tenta reiniciar a operação até que um desses três eventos aconteça: a operação é bem-sucedida, a função de callback retorna nil, ou o número máximo de tentativas é alcançado. Se o sistema atingir o número máximo de tentativas, ele retornará um conflito.

Remover dados

Você pode usar MemoryStoreHashMap:RemoveAsync() tanto para remover uma chave do mapa hash quanto para excluir todos os dados em um mapa hash de armazenamento em memória.

Remover uma chave

Para remover uma chave do mapa hash, chame MemoryStoreHashMap:RemoveAsync() com o nome da chave.

Remover uma Chave de um Mapa Hash

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("Definição bem-sucedida.")
end

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

Deletar todos os dados

Para deletar todos os dados em um mapa hash, liste todos os seus itens com MemoryStoreHashMap:ListItemsAsync(), e então remova-os com MemoryStoreHashMap:RemoveAsync().

Deletar todos os dados em um Mapa Hash

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Obter lista de itens, 32 itens por vez
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Obter a página atual
		local entries = pages:GetCurrentPage()
		local removeSuccess = true
		local removeError = nil
		-- Iterar por todos os pares chave-valor na página
		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
		-- Verificar se a última página foi alcançada
		if pages.IsFinished then
			print("Finalizado ao deletar todos os dados.")
			break
		else
			print("----------")
			-- Avançar para a próxima página
			pages:AdvanceToNextPageAsync()
		end
	end
end