Mapa de almacenamiento de memoria

Mapas de hash , similares a los mapas ordenados, te permiten almacenar datos en memoria como pares de clave-valor.A diferencia de los mapas ordenados, no mantienen ninguna garantía de orden.Esta estructura de datos es útil para casos que requieren caché de datos simple y acceso rápido, como inventarios compartidos, casas de subasta físicas y más.Los mapas de hash manejan automáticamente la partición de sus datos y son muy útiles si tiene más de 1,000 claves.Para espacios de tecla más pequeños, recomendamos mapas ordenados .

Límites

Las tablas de 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, las tablas de hash utilizan las mismas solicitudes de API y límites de memoria como las otras estructuras de datos de almacenamiento de memoria.

Obtener un mapa de hash

Para obtener un mapa de hash, llame a MemoryStoreService:GetHashMap() con un nombre para el mapa de hash.El nombre es global dentro de la experiencia, por lo que puedes acceder al mismo mapa de hash con cualquier script usando este nombre.

Obtener un mapa de hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

Después de obtener un mapa de hash, llame a cualquiera de las siguientes funciones para leer o escribir datos en él:

Para obtener una documentación detallada sobre cada función, consulte MemoryStoreHashMap .

Añadir o reemplazar datos

Para agregar una nueva clave o reemplazar el valor de una clave en el mapa de hash, llame a MemoryStoreHashMap:SetAsync() con la clave nombre , su valor y un tiempo de expiración en segundos.La memoria se limpia automáticamente una vez que expira la clave.El tiempo de expiración máximo es de 3,888,000 segundos (45 días).

Agregar datos a un 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

Obtener datos

Puedes obtener un valor asociado con una clave específica o obtener múltiples pares de clave-valor en el mapa de hash.

Obtener datos con una clave

Para obtener un valor asociado con una clave del mapa de hash, llame a con el nombre de clave .

Obtener una clave particular de un 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

Obtener datos con múltiples pares de clave-valor

Para obtener todos los pares clave-valor de la tabla de hash como una sola operación, llame 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 de hash.

Listar elementos en un mapa de 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
		-- Compruebe si se ha llegado a 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 de hash y actualizarla, llame a con el nombre de clave , una función de llamada de devolución para actualizar la clave y un tiempo de expiración de segundos en segundos.

Para la mayoría de las experiencias, varios servidores pueden actualizar la misma clave simultáneamente y cambiar el valor.Como UpdateAsync() siempre modifica el último valor antes de actualizar, deberías usarlo para leer el último valor como la entrada para tu función de llamada de devolución.

Por ejemplo, el siguiente ejemplo de código actualiza el recuento de recursos de un recurso en un inventario compartido. UpdateAsync() asegura que todas las contribuciones de los jugadores llegarán a este inventario compartido, incluso si estas contribuciones se hacen simultáneamente.En esta función, también aplica un recuento máximo de recursos de 500.

Actualización del recuento 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

			-- asegurarnos de que no excedamos el recuento 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 competencia.

Cuando ocurre la competencia, el sistema vuelve a intentar la operación automáticamente hasta que ocurra una de estas tres cosas: la operación tiene éxito, la función de llamada de devolución devuelve nil , o se alcanza el número máximo de intentos.Si el sistema llega al número máximo de intentos, devuelve un conflicto.

Eliminar datos

Puedes usar MemoryStoreHashMap:RemoveAsync() para eliminar una clave del mapa de hash y eliminar todos los datos en un mapa de almacenamiento de memoria.

Eliminar una clave

Para eliminar una clave del mapa de hash, llama con un nombre de clave .

Eliminar una clave de un 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

Eliminar todos los datos

Para eliminar todos los datos en un mapa de hash, lista todos tus artículos con MemoryStoreHashMap:ListItemsAsync() , luego elimínalos con MemoryStoreHashMap:RemoveAsync() .

Eliminar todos los datos en un mapa de 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
		-- Compruebe si se ha llegado a la última página
		if pages.IsFinished then
			print("Finished deleting all data.")
			break
		else
			print("----------")
			-- Avanzar a la siguiente página
			pages:AdvanceToNextPageAsync()
		end
	end
end