Mapa de Hash da Loja de Memória

Mapas de hash , semelhantes a mapas classificados, permitem armazenar dados na memória como pares de valores-chave. Ao contrário dos mapas classificados, eles não mantêm garantias de ordenação. Esta estrutura de dados é útil para casos que requerem armazenamento em cache de dados simples 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-chave menores, recomendamos mapas classificados.

Limites

Os 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 pedidos de API e limites de cota de memória como as outras estruturas de dados de armazenamento de memória.

Obtendo 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:

Adicionando ou substituindo dados

Para adicionar uma nova chave ou substituir o valor de uma chave no mapa de hash, chame MemoryStoreHashMap:SetAsync() com o nome da chave **** , seu valor **** e um tempo de expiração de **** em segundos. A memória limpa automaticamente quando a chave expirar. O tempo máximo de expiração é de 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

Obtendo dados

Você pode obter um valor associado a uma chave específica ou vários pares de valores de chave no mapa de hash.

Obtendo 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 específica 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

Obtendo dados com vários pares de chaves e valores

Para obter todos os pares de chaves e valores do mapa de hash como uma única operação, chame MemoryStoreHashMap:ListItemsAsync() com o tamanho de página desejado. Esta função lista todas as chaves existentes de forma paginada. Por exemplo, a seguinte amostra de código extrai 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 uma 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 através de todos os pares de chaves e valores 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("----------")
			-- Avance para a próxima página
			pages:AdvanceToNextPageAsync()
		end
	end
end

Atualizando dados

Para obter o valor de uma chave de um mapa de hash e atualizá-la, chame MemoryStoreHashMap:UpdateAsync() com o nome da chave **** , uma função de chamada **** para atualizar a chave e um tempo de expiração **** 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 valor mais recente antes de atualizar, você deve usá-lo para ler o valor mais recente como entrada para sua função de retorno de chamada.

Por exemplo, a seguinte amostra de código atualiza a contagem de recursos de um recurso em um inventário compartilhado. UpdateAsync() garante que todas as contribuições de jogadores entrem nesse inventário compartilhado, mesmo que essas contribuições sejam feitas simultaneamente. Nesta função, também impõe 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

			-- certifique-se de que não excedamos 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() é semelhante a GetAsync() e SetAsync(), a menos que haja contenda.

Quando ocorre uma contenda, o sistema tenta automaticamente a operação até que uma dessas três ocorram: a operação é bem-sucedida, a função de retorno de chamada retorna nulo ou o número máximo de tentativas é atingido. Se o sistema atingir o número máximo de tentativas, retornará um conflito.

Remoção de dados

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

Remover 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

Excluindo todos os dados

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

Apagar todos os dados em um mapa de hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Obtenha uma 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 através de todos os pares de chaves e valores 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("----------")
			-- Avance para a próxima página
			pages:AdvanceToNextPageAsync()
		end
	end
end