Mapas hash, similares a los mapas ordenados, te permiten almacenar datos en memoria como pares clave-valor. A diferencia de los mapas ordenados, no mantienen garantías de orden. Esta estructura de datos es útil para casos que requieren un almacenamiento de datos simple y acceso rápido, como inventarios compartidos, casas de subastas físicas y más. Los mapas hash manejan automáticamente la partición de tus datos y son muy útiles si tienes más de 1,000 claves. Para espacios de clave más pequeños, recomendamos mapas ordenados.
Límites
Los mapas hash tienen un límite de tamaño de clave de 128 caracteres y un límite de tamaño de valor de 32 KB.
De lo contrario, los mapas hash utilizan los mismos límites de solicitud de API y cuota de memoria que las otras estructuras de datos de almacenamiento en memoria.
Obtener un mapa hash
Para obtener un mapa hash, llama a MemoryStoreService:GetHashMap() con un nombre para el mapa hash. El nombre es global dentro del juego, por lo que puedes acceder al mismo mapa hash en cualquier script usando este nombre.
Obteniendo un Mapa Hash
Después de obtener un mapa hash, llama a cualquiera de las siguientes funciones para leer o escribir datos en él:
| Función | Acción |
|---|---|
| MemoryStoreHashMap:SetAsync() | Agregar una nueva clave o sobrescribir el valor si la clave ya existe. |
| MemoryStoreHashMap:GetAsync() | Leer una clave particular. |
| MemoryStoreHashMap:ListItemsAsync() | Listar elementos en un mapa hash. |
| MemoryStoreHashMap:UpdateAsync() | Actualizar el valor de una clave después de recuperarlo de un mapa hash. |
| MemoryStoreHashMap:RemoveAsync() | Eliminar una clave del mapa hash. |
Para documentación detallada sobre cada función, consulta MemoryStoreHashMap.
Todas las funciones que acceden a estructuras de datos en almacenes de memoria son llamadas de red asincrónicas que pueden fallar ocasionalmente. Debes envolver estas llamadas en pcall() para capturar y manejar errores, como se muestra en los ejemplos de código.
Agregar o sobrescribir datos
Para agregar una nueva clave o sobrescribir el valor de una clave en el mapa hash, llama a MemoryStoreHashMap:SetAsync() con el nombre de la clave, su valor y un tiempo de expiración en segundos. La memoria se limpia automáticamente una vez que la clave expira. El tiempo máximo de expiración es de 3,888,000 segundos (45 días).
Bajo el Reglamento General de Protección de Datos (GDPR) de la UE, si tus almacenes de memoria tienen datos de usuarios sujetos al derecho a ser olvidado debes eliminar los datos dentro de 30 días, incluso si configuras la expiración de la clave de tu almacén de memoria hasta 45 días.
Agregando Datos a un 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("Establecido con éxito.")
end
Obtener datos
Puedes obtener un valor asociado con una clave específica o obtener múltiples pares clave-valor en el mapa hash.
Obtener datos con una clave
Para obtener un valor asociado con una clave del mapa hash, llama a MemoryStoreHashMap:GetAsync() con el nombre de la clave.
Obteniendo una Clave Particular de un 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("Establecido con éxito.")
end
local item
local getSuccess, getError = pcall(function()
item = hashMap:GetAsync("User_1234")
end)
if getSuccess then
print(item)
else
warn(getError)
end
Obtener datos con múltiples pares clave-valor
Para obtener todos los pares clave-valor del mapa hash como una sola operación, llama a MemoryStoreHashMap:ListItemsAsync() con el tamaño de página deseado. Esta función lista todas las claves existentes de manera paginada. Por ejemplo, el siguiente ejemplo de código recupera hasta 32 elementos del mapa hash.
Listando elementos en un Mapa Hash
local MemoryStoreService = game:GetService("MemoryStoreService")
local hashMap = MemoryStoreService:GetHashMap("HashMap1")
-- Obtener lista de elementos, 32 elementos a la vez
local success, pages = pcall(function()
return hashMap:ListItemsAsync(32)
end)
if success then
while true do
-- Obtener la página actual
local entries = pages:GetCurrentPage()
-- Iterar a través de todos los pares clave-valor en la página
for _, entry in ipairs(entries) do
print(entry.key .. " : " .. tostring(entry.value))
end
-- Verificar si se ha alcanzado la última página
if pages.IsFinished then
break
else
print("----------")
-- Avanzar a la siguiente página
pages:AdvanceToNextPageAsync()
end
end
end
Actualizar datos
Para recuperar el valor de una clave de un mapa hash y actualizarlo, llama a MemoryStoreHashMap:UpdateAsync() con el nombre de la clave, una función de callback para actualizar la clave y un tiempo de expiración en segundos.
Para la mayoría de los juegos, múltiples servidores pueden actualizar la misma clave concurrentemente y cambiar el valor. Como UpdateAsync() siempre modifica el último valor antes de actualizar, deberías utilizarlo para leer el último valor como entrada para tu función de callback.
Por ejemplo, el siguiente ejemplo de código actualiza el conteo de recursos de un recurso en un inventario compartido. UpdateAsync() asegura que todas las contribuciones de los jugadores se integren en este inventario compartido, incluso si se hacen simultáneamente. En esta función, también se aplica un límite máximo de conteo de recursos de 500.
Actualizando el Conteo de Recursos para un Recurso en un Inventario Compartido
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
-- Asegurarse de que no excedemos el conteo 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
La latencia para UpdateAsync() es similar a GetAsync() y SetAsync() a menos que haya contención.
Cuando ocurre contención, el sistema vuelve a intentar automáticamente la operación hasta que uno de estos tres sucesos ocurre: la operación tiene éxito, la función de callback devuelve nil, o se alcanza el número máximo de reintentos. Si el sistema alcanza el número máximo de reintentos, devuelve un conflicto.
Eliminar datos
Puedes usar MemoryStoreHashMap:RemoveAsync() tanto para eliminar una clave del mapa hash como para eliminar todos los datos en un mapa hash de almacenamiento en memoria.
Eliminar una clave
Para eliminar una clave del mapa hash, llama a MemoryStoreHashMap:RemoveAsync() con el nombre de la clave.
Eliminar una Clave de un 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("Establecido con éxito.")
end
local removeSuccess, removeError = pcall(function()
hashMap:RemoveAsync("User_1234")
end)
if not removeSuccess then
warn(removeError)
end
Eliminar todos los datos
Para eliminar todos los datos en un mapa hash, lista todos tus elementos con MemoryStoreHashMap:ListItemsAsync(), luego elimínalos con MemoryStoreHashMap:RemoveAsync().
Eliminar todos los datos en un Mapa Hash
local MemoryStoreService = game:GetService("MemoryStoreService")
local hashMap = MemoryStoreService:GetHashMap("HashMap1")
-- Obtener lista de elementos, 32 elementos a la vez
local success, pages = pcall(function()
return hashMap:ListItemsAsync(32)
end)
if success then
while true do
-- Obtener la página actual
local entries = pages:GetCurrentPage()
local removeSuccess = true
local removeError = nil
-- Iterar a través de todos los pares clave-valor en la 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 si se ha alcanzado la última página
if pages.IsFinished then
print("Finalizado al eliminar todos los datos.")
break
else
print("----------")
-- Avanzar a la siguiente página
pages:AdvanceToNextPageAsync()
end
end
end