Mapa hash de almacenamiento en memoria | Documentación del Centro de creación de Roblox

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 almacenamiento en caché de datos simples 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 claves 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 utilizando este nombre.

Obteniendo un Mapa Hash

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

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 los almacenes de memoria son llamadas a la red asíncronas 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).

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 correctamente.")
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 correctamente.")
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 única 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 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, varios servidores pueden actualizar la misma clave concurrentemente y cambiar el valor. Como UpdateAsync() siempre modifica el último valor antes de actualizar, debes usarlo para leer el último valor como entrada para tu función de callback.

Por ejemplo, el siguiente código actualiza el conteo de recursos de un recurso en un inventario compartido. UpdateAsync() asegura que todas las contribuciones de los jugadores se reflejen en este inventario compartido, incluso si estas contribuciones se hacen simultáneamente. En esta función, también se impone un conteo máximo 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 no exceder 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 reintenta automáticamente la operación hasta que suceda una de estas tres cosas: 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 borrar 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 un nombre de 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 correctamente.")
end

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

Borrar todos los datos

Para borrar todos los datos en un mapa hash, lista todos tus elementos con MemoryStoreHashMap:ListItemsAsync(), luego elimínalos con MemoryStoreHashMap:RemoveAsync().

Borrar 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("Terminado de eliminar todos los datos.")
			break
		else
			print("----------")
			-- Avanzar a la siguiente página
			pages:AdvanceToNextPageAsync()
		end
	end
end