Mapa ordenado de almacenamiento en memoria

La estructura de datos de mapa ordenado de almacenamientos en memoria te permite almacenar datos en memoria frecuentemente como pares clave-valor con una clave de orden opcional y mantener un orden específico basado en las claves de orden y claves. A diferencia de las colas, el orden de las claves que ingresan a un mapa no determina el orden de procesamiento, lo que hace que los mapas ordenados sean útiles para organizar datos agrupados para implementar entidades en el juego para el compromiso, como tablas de clasificación y subastas entre servidores.

Límites

Además de los límites de tamaño de la estructura de datos, los mapas ordenados tienen un límite de tamaño de clave de 128 caracteres, un límite de tamaño de valor de 32 KB y un límite de tamaño de clave de orden de 128 caracteres.

Si necesitas almacenar datos que superen este límite para tu juego, puedes adoptar la técnica de particionamiento para dividir y distribuir estos datos a través de prefijo de clave en múltiples estructuras de datos. El particionamiento de los almacenamientos en memoria también puede ayudar a mejorar la escalabilidad de tu sistema.

Obtener un mapa ordenado

Para obtener un mapa ordenado, llama a MemoryStoreService:GetSortedMap() con un nombre que desees definir para el mapa. El nombre es global dentro del juego, por lo que puedes acceder al mismo mapa ordenado desde cualquier script usando el nombre.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

Después de obtener un mapa ordenado, llama a cualquiera de las siguientes funciones:

Agregar o sobrescribir datos

Para agregar una nueva clave o sobrescribir el valor o la clave de orden de una clave en el mapa ordenado, llama a MemoryStoreSortedMap:SetAsync() con el nombre de la clave, su valor, un tiempo de expiración en segundos y una clave de orden opcional. La memoria se limpia automáticamente una vez que la clave expira. El tiempo de expiración máximo es de 3,888,000 segundos (45 días). La clave de orden, si se proporciona, debe ser un número válido (entero o de punto flotante) o una cadena.

En el orden de clasificación de tus claves, una clave de orden tiene prioridad sobre una clave. Por ejemplo, al ordenar en orden ascendente, las claves de orden numéricas se ordenan primero, seguidas de las claves de orden de cadena, seguidas de los elementos sin clave de orden. Todos los elementos con claves de orden numéricas se ordenan por clave de orden, si la clave de orden para dos elementos es igual, se ordenan por clave. De manera similar, todos los elementos con claves de orden de cadena se ordenan por clave de orden, si la clave de orden para dos elementos es igual, se ordenan por clave. Todos los elementos sin clave de orden se ordenan solo por clave.

Ejemplo de algunos datos ordenados en orden ascendente -

{key: "jugador1", value: someValue1, sortKey: -1}
{key: "jugador2", value: someValue2, sortKey: 0}
{key: "jugador4", value: someValue3, sortKey: 1}
{key: "jugador5", value: someValue4, sortKey: 1}
{key: "jugador3", value: someValue5, sortKey: 3.14}
{key: "jugador6", value: someValue6, sortKey: "someString"}
{key: "jugador0", value: someValue7}
{key: "jugador7", value: someValue8}

Nota cómo jugador0 se ordena después de todas las claves con una clave de orden. jugador6 se ordena después de todas las claves con un clave de orden numérica. jugador4 y jugador5 tienen la misma clave de orden, por lo que se ordenan en orden ascendente por clave.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

local setSuccess, _ = pcall(function()
	return sortedMap:SetAsync("Usuario_1234", 1000, 30, 3.14152)
end)
if setSuccess then
	print("La configuración fue exitosa.")
end

Obtener datos

Puedes obtener un valor de datos y una clave de orden asociada con una clave específica o obtener múltiples valores y claves de orden para claves dentro de un rango.

Obtener datos con una clave

Para obtener un valor y una clave de orden asociada con una clave del mapa ordenado, llama a MemoryStoreSortedMap:GetAsync() con el nombre de la clave.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

local setSuccess, _ = pcall(function()
	return sortedMap:SetAsync("Usuario_1234", 1000, 30, 3.14152)
end)
if setSuccess then
	print("La configuración fue exitosa.")
end

local item
local getSuccess, getError = pcall(function()
	item = sortedMap:GetAsync("Usuario_1234")
end)
if getSuccess then
	print(item)
else
	warn(getError)
end

Obtener datos con múltiples claves

Para obtener datos de múltiples claves del mapa ordenado como una sola operación, llama a MemoryStoreSortedMap:GetRangeAsync(). Esta función lista todas las claves existentes por defecto, pero puedes establecer los límites superior e inferior para el rango de claves. Por ejemplo, el siguiente código recupera hasta 20 elementos comenzando desde el principio del mapa ordenado, con claves mayores o iguales a 10, claves de orden mayores o iguales a 100 y claves menores o iguales a 50, claves de orden menores o iguales a 500.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

local lowerBound = {}
lowerBound["key"] = "10"
lowerBound["sortKey"] = 100
local upperBound = {}
upperBound["key"] = "50"
upperBound["sortKey"] = 500

-- Obtener hasta 20 elementos comenzando desde el principio
local getSuccess, items = pcall(function()
	return sortedMap:GetRangeAsync(
		Enum.SortDirection.Ascending, 20, lowerBound, upperBound)
end)
if getSuccess then
	for _, item in items do
		print(item.key)
		print(item.sortKey)
	end
end

Actualizar datos

Para recuperar el valor y la clave de orden de una clave de un mapa ordenado y actualizarlo, llama a MemoryStoreSortedMap:UpdateAsync() con el nombre de la clave, una función de callback para actualizar el valor y la clave de orden de esta clave, y un tiempo de expiración en segundos. El tiempo de expiración máximo es de 3,888,000 segundos (45 días).

Para la mayoría de los juegos, múltiples servidores pueden actualizar la misma clave de forma concurrente y cambiar el valor. Como UpdateAsync() siempre modifica el valor más reciente antes de actualizar, deberías utilizarlo para leer el valor más reciente como entrada para tu función de callback.

Por ejemplo, el siguiente código actualiza la puntuación en una tabla de clasificación para un jugador. La puntuación se calcula como muertes / muertes. UpdateAsync() asegura que las muertes y las muertes se actualicen para los valores más recientes, incluso si múltiples servidores de juego actualizan el mismo elemento simultáneamente. Las muertes y muertes de un jugador son valores de incremento monótono y, por lo tanto, solo pueden aumentar en valor en una sesión.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("TablaDeClasificación")

local function updateLeaderboard(itemKey, killsToAdd, deathsToAdd)
	local success, newStats, newScore = pcall(function()
		return sortedMap:UpdateAsync(itemKey, function(playerStats, playerScore)
			playerStats = playerStats or { kills = 0, deaths = 0 }
			playerStats.kills += killsToAdd
			playerStats.deaths += deathsToAdd
			if playerStats then
				-- `playerScore` es la clave de orden que se utiliza para ordenar elementos en el mapa
				playerScore = playerStats.kills / math.max(playerStats.deaths, 1)
				return playerStats, playerScore
			end
			return nil
		end, 30)
	end)
	if success then
		print(newStats)
		print(newScore)
	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 MemoryStoreSortedMap:RemoveAsync() tanto para eliminar una clave del mapa ordenado como para eliminar todos los datos en un mapa ordenado de almacenamiento en memoria.

Eliminar una clave

Para eliminar una clave del mapa ordenado, llama a MemoryStoreSortedMap:RemoveAsync() con un nombre de clave.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

local setSuccess, _ = pcall(function()
	return sortedMap:SetAsync("Usuario_1234", 1000, 30, "someStringSortKey")
end)
if setSuccess then
	print("La configuración fue exitosa.")
end

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

Eliminar todos los datos

Para eliminar la memoria en mapas ordenados, lista todas tus claves con MemoryStoreSortedMap:GetRangeAsync(), luego elimínalas con MemoryStoreSortedMap:RemoveAsync().

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

-- El límite inferior inicial de nil comienza limpieza desde el primer elemento
local exclusiveLowerBound = nil

while true do
	-- Obtener hasta cien elementos comenzando desde el límite inferior actual
	local getRangeSuccess, items = pcall(function()
		return sortedMap:GetRangeAsync(Enum.SortDirection.Ascending, 100, exclusiveLowerBound)
	end)
	if getRangeSuccess then
		local removeSuccess = true
		local removeError = nil

		for _, item in items do
			removeSuccess, removeError = pcall(function()
				sortedMap:RemoveAsync(item.key)
			end)
		end

		-- Si hubo un error al eliminar elementos, intenta nuevamente con el mismo límite inferior exclusivo
		if not removeSuccess then
			warn(removeError)
		-- Si el rango tiene menos de cien elementos, se alcanzó el final del mapa
		elseif #items < 100 then
			break
		else
			-- La última clave recuperada es el límite inferior exclusivo para la próxima iteración
			exclusiveLowerBound = {}
			exclusiveLowerBound["key"] = items[#items].key
			exclusiveLowerBound["sortKey"] = items[#items].sortKey
		end
	end
end

Obtener el tamaño

Para obtener el número de elementos en el mapa ordenado, llama a MemoryStoreSortedMap:GetSizeAsync().

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

local setSuccess, _ = pcall(function()
	return sortedMap:SetAsync("Usuario_1234", 1000, 30, 3.14152)
end)

if setSuccess then
	print("La configuración fue exitosa.")
end

local size
local success, sizError = pcall(function()
	size = sortedMap:GetSizeAsync()
end)

if success then
	print(size)
else
	warn(sizeError)
end