Mapas de hash, semelhantes aos 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 requerem cache de dados simples e acesso rápido, como inventários compartilhados, casas de leilão físicas e mais. Os 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.
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 limites de requisições de API e cotas de memória que as outras estruturas de dados de armazenamento em memória.
Obter 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 do jogo, portanto, você pode acessar o mesmo mapa de hash em qualquer script usando este nome.
Obtendo um Mapa de Hash
Depois de obter um mapa de 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 de hash. |
| MemoryStoreHashMap:UpdateAsync() | Atualizar o valor de uma chave após recuperá-la de um mapa de hash. |
| MemoryStoreHashMap:RemoveAsync() | Remover uma chave do mapa de hash. |
Para documentação detalhada sobre cada função, consulte MemoryStoreHashMap.
Todas as funções que acessam estruturas de dados nos 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 lidar com erros, conforme mostrado nos exemplos de código.
Adicionar ou sobrescrever dados
Para adicionar uma nova chave ou sobrescrever 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 em segundos. A memória limpa automaticamente assim que a chave expira. O tempo máximo de expiração é 3.888.000 segundos (45 dias).
Sob o Regulamento Geral sobre a Proteção de Dados da UE (GDPR), se seus armazenamentos em memória tiverem dados de usuários sujeitos ao direito de ser esquecido, você deve remover os dados dentro de 30 dias, mesmo que defina a expiração da chave do seu armazenamento em memória para até 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("Definição sucedida.")
end
Obter dados
Você pode obter o valor associado a uma chave específica ou obter vários pares chave-valor no mapa de hash.
Obter dados com uma chave
Para obter um valor associado a uma chave no 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("Definição 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 de 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 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")
-- 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 de 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 valor mais recente antes de atualizar, você deve usá-lo para ler o valor mais recente como entrada para 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 cheguem a este inventário compartilhado, mesmo que essas contribuições sejam feitas simultaneamente. Nesta função, também é imposto um máximo de contagem de recursos de 500.
Atualizando a Contagem de Recursos de 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 ultrapassemos 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 contestação.
Quando a contestação ocorre, o sistema automaticamente tenta a operação novamente até que uma dessas três coisas aconteça: a operação seja bem-sucedida, a função de callback retorne nil, ou o número máximo de tentativas seja alcançado. Se o sistema atingir o número máximo de tentativas, ele retorna um conflito.
Remover dados
Você pode usar MemoryStoreHashMap:RemoveAsync() tanto para remover uma chave do mapa de hash quanto para deletar todos os dados em um mapa de hash de armazenamento em memória.
Remover uma chave
Para remover uma chave do mapa de hash, chame MemoryStoreHashMap:RemoveAsync() com o nome da chave.
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("Definição 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 de hash, liste todos os seus itens com MemoryStoreHashMap:ListItemsAsync(), e em seguida remova-os com MemoryStoreHashMap:RemoveAsync().
Deletar todos os dados em um Mapa de 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("Concluído a exclusão de todos os dados.")
break
else
print("----------")
-- Avançar para a próxima página
pages:AdvanceToNextPageAsync()
end
end
end