Mapa de Memória

Mapas de hash , semelhantes a mapas classificados, permitem que você armazene dados em memória como pares de valor de chave. Ao contrário dos mapas classificados, eles não fornecem garantias de classificação. Esta estrutura de dados é útil para casos que exigem armazenamento simples de dados e acesso rápido, como compartilhamento de inventários, casas de le

Limites

Os mapas de hashes 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 hashes usam os mesmos limites de API e quota de memória que as outras estruturas de dados de armazenamento de memória.

Obtendo um Mapa de Hash

Para obter um mapa de hashes, chame Class.MemoryStoreService:Get:`Class.MemoryStoreService:Get:`Class.MemoryStoreService:Get:`Class.MemoryStoreService:Get:`Class.MemoryStoreService:Get` com um nome para o hashe. O nome é global dentro da experiência, para que você possa acessar o mesmo hashe 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 hashes, chame qualquer uma das seguintes funções para ler ou escrever dados nele:

Adicionando ou Substituindo Dados

Para adicionar uma nova chave ou sobrescrever o valor de uma chave no mapa de hashes, chame MemoryStoreHashMap:SetAsync() com o nome da chave, seu valor e um tempo de expiração em segundos. O 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

Obtendo Dados

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

Obtendo Dados com uma Chave

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

Obtendo uma Chave Especial de um Mapa de Hashes
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 Valor-Chave

Para obter todos os pares de valor da chave da tabela de hashes como uma única operação, chame MemoryStoreHashMap:ListItemsAsync() com o tamanho de página desejado. Essa função lista todos os pares de chaves existentes de forma página. Por exemplo, o seguinte código de exemplo recupera até 32 itens da tabela de hashes.

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

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Obtenha lista de itens, 32 itens por vez
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Obtenha a página atual
		local entries = pages:GetCurrentPage()
		-- Iterar por todos os pares de valor da chave 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 recuperar o valor de uma chave a partir de um mapa de hashes e atualizá-lo, chame MemoryStoreHashMap:UpdateAsync() com a chave nome , uma função de chamada para atualizar a chave e um 1> tempo de expiração1> 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 mais recente valor como entrada para sua função de chamada.

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 à este inventário compartilhado, mesmo que essas contribuições sejam feitas simultaneamente. Nesta função, ele também impõe um limite máximo de 500 recursos.

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 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 contenção.

Quando ocorre contenção, o sistema automaticamente tenta novamente a operação até que um desses três aconteça: a operação é bem-sucedida, a função de chamada retorna nil ou o número máximo de retries é atingido. Se o sistema atingir o número máximo de retries, ele retorna um conflito.

Removendo Dados

Você pode usar MemoryStoreHashMap:RemoveAsync() para ambas as remoções de uma chave do mapa de hash e todas as remoções de dados em um mapa de armazenamento de memória.

Removendo uma Chave

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

Remover 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 em um mapa de hashes, liste todos os seus itens com MemoryStoreHashMap:ListItemsAsync() , então remova-os com MemoryStoreHashMap:RemoveAsync() .

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

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Obtenha lista de itens, 32 itens por vez
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Obtenha a página atual
		local entries = pages:GetCurrentPage()
		local removeSuccess = true
		local removeError = nil
		-- Iterar por todos os pares de valor da chave 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