Mapa de armazenamento de memória

Mapas de hash , semelhantes a mapas ordenados, permitem que você armazene dados em memória como pares de chave-valor.Ao contrário de mapas classificados, eles não mantêm garantias de ordem.Essa estrutura de dados é útil para casos que requerem armazenamento simples de dados e acesso rápido, como inventários compartilhados, casas de leilão físicas e muito mais.Mapas de hash lidam automaticamente com 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.

Limitos

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

Caso contrário, os mapas de hash usam os mesmos limites de solicitação de API e quota de memória e os mesmos limites de estruturas de dados de armazenamento de memória do outro armazenamento de memória.

Obtenha um mapa de hash

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

Obtendo um Mapa de Hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

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

Para documentação aprofundada sobre cada função, veja MemoryStoreHashMap.

Adicionar ou substituir dados

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

Adicionando Dados a um Mapa de 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("Set succeeded.")
end

Obter dados

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

Obtenha dados com uma chave

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

Obtendo uma Chave Particular de um Mapa de 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("Set succeeded.")
end

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

Obtenha dados com vários pares de chave-valor

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

Listando itens em um Mapa de Hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Obtenha lista de itens, 32 itens de cada 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 de chave-valor na página
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Verifique 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 de hash e atualizá-la, chame com o nome da chave , uma função de chamada de volta para atualizar a chave e um tempo de expiração de segundos em segundos.

Para a maioria das experiências, vários servidores podem atualizar a mesma chave simultaneamente e alterar 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 função de chamada de volta.

Por exemplo, o seguinte código de exemplo atualiza o número de recursos de um recurso em um inventário compartilhado.UpdateAsync() garante que todas as contribuições do jogador cheguem a esse inventário compartilhado, mesmo que essas contribuições sejam feitas simultaneamente.Nesta função, também impõe um limite máximo 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 excedamos o número máximo 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() é semelhante a GetAsync() e SetAsync() a menos que haja concorrência.

Quando ocorre conflito, o sistema tenta automaticamente a operação novamente até que uma dessas três ocorra: a operação tenha sucesso, a função de retorno retorne nil ou o número máximo de tentativas seja atingido.Se o sistema atingir o número máximo de tentativas, ele retorna um conflito.

Remover dados

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

Remova uma chave

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

Remova uma chave de um mapa de 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("Set succeeded.")
end

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

Excluir todos os dados

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

Exclua todos os dados em um Mapa de Hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Obtenha lista de itens, 32 itens de cada 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 de 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
		-- Verifique se a última página foi alcançada
		if pages.IsFinished then
			print("Finished deleting all data.")
			break
		else
			print("----------")
			-- Avançar para a próxima página
			pages:AdvanceToNextPageAsync()
		end
	end
end