Mapa ordenado de almacenamiento en memoria

La estructura de datos mapa ordenado de almacenes en memoria permite almacenar datos frecuentemente en memoria como pares clave-valor con una clave de orden opcional y mantener un orden específico basado en las claves de orden y las claves. A diferencia de las colas, el orden de las claves que ingresan en un mapa no determina el orden de procesamiento, lo que hace que los mapas ordenados sean útiles para organizar datos basados en el orden para implementar entidades dentro del 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 fragmentación para dividir y distribuir los datos a través de un prefijo de clave en múltiples estructuras de datos. La fragmentación de los almacenes 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 en cualquier script usando el nombre.

Obteniendo un Mapa Ordenado
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

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

Añadir o sobrescribir datos

Para añadir una nueva clave o sobrescribir el valor o 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 máximo de expiración 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 clasificar 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 la clave.

Ejemplo de algunos datos ordenados en orden ascendente -

{key: "player1", value: someValue1, sortKey: -1}
{key: "player2", value: someValue2, sortKey: 0}
{key: "player4", value: someValue3, sortKey: 1}
{key: "player5", value: someValue4, sortKey: 1}
{key: "player3", value: someValue5, sortKey: 3.14}
{key: "player6", value: someValue6, sortKey: "someString"}
{key: "player0", value: someValue7}
{key: "player7", value: someValue8}

Observa cómo player0 se ordena después de todas las claves con una clave de orden. player6 se ordena después de todas las claves con una clave de orden numérica. player4 y player5 tienen la misma clave de orden, por lo que se ordenan en orden ascendente por clave.

Añadiendo Datos a un Mapa Ordenado
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

local setSuccess, _ = pcall(function()
	return sortedMap:SetAsync("User_1234", 1000, 30, 3.14152)
end)
if setSuccess then
	print("Establecido con éxito.")
end

Obtener datos

Puedes obtener un valor de datos y la 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 la clave de orden asociada con una clave del mapa ordenado, llama a MemoryStoreSortedMap:GetAsync() con el nombre de la clave.

Obteniendo una Clave Particular de un Mapa Ordenado
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

local setSuccess, _ = pcall(function()
	return sortedMap:SetAsync("User_1234", 1000, 30, 3.14152)
end)
if setSuccess then
	print("Establecido con éxito.")
end

local item
local getSuccess, getError = pcall(function()
	item = sortedMap:GetAsync("User_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 ejemplo de 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.

Obteniendo un Rango de Claves de un Mapa Ordenado
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 para esta clave y un tiempo de expiración en segundos. El tiempo máximo de expiración 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 manera concurrente y cambiar el valor. Dado que UpdateAsync() siempre modifica el valor más reciente antes de actualizar, debes usarlo para leer el valor más reciente como entrada para tu función de callback.

Por ejemplo, el siguiente ejemplo de código actualiza la puntuación en una tabla de clasificación para un jugador. La puntuación se calcula como muertes / muertes. UpdateAsync() garantiza que las muertes y 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 que aumentan de manera monótona y, por lo tanto, solo pueden aumentar de valor en una sesión.

Actualizando la puntuación de la tabla de clasificación para un jugador en un Mapa Ordenado
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("Leaderboard")

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 vuelve a intentar automáticamente la operación hasta que una de estas tres cosas suceda: la operación tiene éxito, la función de callback retorna nil, o se alcanza el número máximo de intentos. Si el sistema alcanza el número máximo de intentos, 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 el nombre de la clave.

Eliminar una Clave de un Mapa Ordenado
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

local setSuccess, _ = pcall(function()
	return sortedMap:SetAsync("User_1234", 1000, 30, "someStringSortKey")
end)
if setSuccess then
	print("Establecido con éxito.")
end

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

Eliminar todos los datos

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

Eliminar Memoria en un Mapa Ordenado
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

-- El límite inferior inicial de nil comienza a vaciar 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 de nuevo con el mismo límite inferior exclusivo
		if not removeSuccess then
			warn(removeError)
		-- Si el rango es menor de cien elementos, se ha alcanzado 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 tamaño

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

Obteniendo el Tamaño de un Mapa Ordenado
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

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

if setSuccess then
	print("Establecido con éxito.")
end

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

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