Mapa classificado da loja de memória

A estrutura de dados mapa classificado das lojas de memória permite armazenar dados frequentes em memória como pares chave-valor com uma chave de classificação opcional e manter uma ordem específica com base nas chaves de classificação e chaves. Ao contrário das filas, a ordem das chaves que entram em um mapa não determina a ordem de processamento, tornando os mapas classificados úteis para a organização de dados baseada em classificação para a implementação de entidades em jogo para engajamento, como placares e leilões entre servidores.

Limites

Além dos limites de tamanho da estrutura de dados, os mapas classificados têm um limite de tamanho de chave de 128 caracteres, um limite de tamanho de valor de 32 KB e um limite de tamanho de chave de classificação de 128 caracteres.

Se você precisar armazenar dados que ultrapassam esse limite para seu jogo, pode adotar a técnica de fragmentação para dividir e distribuir esses dados através de prefixos de chave em várias estruturas de dados. A fragmentação de lojas de memória também pode ajudar a melhorar a escalabilidade do seu sistema.

Obter um mapa classificado

Para obter um mapa classificado, chame MemoryStoreService:GetSortedMap() com um nome que você deseja definir para o mapa. O nome é global dentro do jogo, então você pode acessar o mesmo mapa classificado em qualquer script usando o nome.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

Depois de obter um mapa classificado, chame qualquer uma das seguintes funções:

Adicionar ou sobrescrever dados

Para adicionar uma nova chave ou sobrescrever o valor ou chave de classificação de uma chave no mapa classificado, chame MemoryStoreSortedMap:SetAsync() com o nome da chave, seu valor, um tempo de expiração em segundos e uma chave de classificação opcional. A memória é automaticamente limpa assim que a chave expira. O tempo máximo de expiração é de 3.888.000 segundos (45 dias). A chave de classificação, se fornecida, deve ser um número válido (inteiro ou ponto flutuante) ou uma string.

Na ordem de classificação de suas chaves, uma chave de classificação tem precedência sobre uma chave. Por exemplo, ao classificar em ordem crescente, chaves de classificação numéricas são classificadas primeiro, seguidas por chaves de classificação de string, seguidas por itens sem chave de classificação. Todos os itens com chaves de classificação numéricas são classificados pela chave de classificação; se a chave de classificação de dois itens for igual, eles são classificados pela chave. Da mesma forma, todos os itens com chaves de classificação de string são classificados pela chave de classificação; se a chave de classificação de dois itens for igual, eles são classificados pela chave. Todos os itens sem chave de classificação são classificados apenas pela chave.

Exemplo de alguns dados classificados em ordem crescente -

{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}

Note como player0 é classificado após todas as chaves com uma chave de classificação. player6 é classificado após todas as chaves com uma chave de classificação numérica. player4 e player5 têm a mesma chave de classificação, portanto, eles são classificados em ordem crescente pela chave.

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("Definido com sucesso.")
end

Obter dados

Você pode obter um valor de dados e chave de classificação associada a uma chave específica ou obter múltiplos valores e chaves de classificação para chaves dentro de um intervalo.

Obter dados com uma chave

Para obter um valor e chave de classificação associados a uma chave do mapa classificado, chame MemoryStoreSortedMap:GetAsync() com o nome da chave.

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("Definido com sucesso.")
end

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

Obter dados com múltiplas chaves

Para obter dados para múltiplas chaves do mapa classificado como uma única operação, chame MemoryStoreSortedMap:GetRangeAsync(). Esta função lista todas as chaves existentes por padrão, mas você pode definir os limites superior e inferior para o intervalo de chaves. Por exemplo, o seguinte exemplo de código recupera até 20 itens começando do início do mapa classificado, com chaves maiores ou iguais a 10, chaves de classificação maiores ou iguais a 100 e chaves menores ou iguais a 50, chaves de classificação menores ou iguais 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

-- Obter até 20 itens começando do início
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

Atualizar dados

Para recuperar o valor e chave de classificação de uma chave de um mapa classificado e atualizá-la, chame MemoryStoreSortedMap:UpdateAsync() com o nome da chave, uma função de callback para atualizar o valor e chave de classificação para essa chave e um tempo de expiração em segundos. O tempo máximo de expiração é de 3.888.000 segundos (45 dias).

Para a maioria dos jogos, vários servidores podem atualizar a mesma chave simultaneamente e alterar o valor. Como MemoryStoreSortedMap:UpdateAsync() sempre modifica o valor mais recente antes de atualizar, você deve usá-lo para ler o valor mais recente como entrada para sua função de callback.

Por exemplo, o seguinte exemplo de código atualiza a pontuação em um placar para um jogador. A pontuação é calculada como mortes / mortes. MemoryStoreSortedMap:UpdateAsync() garante que as mortes e mortes sejam atualizadas para os valores mais recentes, mesmo que vários servidores de jogo atualizem o mesmo item simultaneamente. As mortes e mortes de um jogador são valores que aumentam monotonamente e, portanto, só podem aumentar de valor em uma sessão.

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` é a chave de classificação usada para classificar itens no 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

A latência para MemoryStoreSortedMap:UpdateAsync() é semelhante a MemoryStoreSortedMap:GetAsync() e MemoryStoreSortedMap:SetAsync() a menos que ocorra contenção.

Quando ocorre contenção, o sistema automaticamente tenta a operação novamente até que um desses três aconteça: a operação tenha sucesso, a função de callback retorne nil ou o número máximo de tentativas seja alcançado. Se o sistema atingir o número máximo de tentativas, ele retorna um conflito.

Remover dados

Você pode usar MemoryStoreSortedMap:RemoveAsync() tanto para remover uma chave do mapa classificado quanto para excluir todos os dados em um mapa classificado da loja de memória.

Remover uma chave

Para remover uma chave do mapa classificado, chame MemoryStoreSortedMap:RemoveAsync() com um nome de chave.

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("Definido com sucesso.")
end

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

Excluir todos os dados

Para excluir memória em mapas classificados, liste todas as suas chaves com MemoryStoreSortedMap:GetRangeAsync(), em seguida, remova-as com MemoryStoreSortedMap:RemoveAsync().

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

-- Limite inferior inicial de nil começa a limpeza do primeiro item
local exclusiveLowerBound = nil

while true do
	-- Obter até cem itens começando do limite inferior atual
	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

		-- Se houve um erro ao remover itens, tente novamente com o mesmo limite inferior exclusivo
		if not removeSuccess then
			warn(removeError)
		-- Se o intervalo for inferior a cem itens, o final do mapa foi alcançado
		elseif #items < 100 then
			break
		else
			-- A última chave recuperada é o limite inferior exclusivo para a próxima iteração
			exclusiveLowerBound = {}
			exclusiveLowerBound["key"] = items[#items].key
			exclusiveLowerBound["sortKey"] = items[#items].sortKey
		end
	end
end

Obter tamanho

Para obter o número de itens no mapa classificado, chame MemoryStoreSortedMap:GetSizeAsync().

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("Definido com sucesso.")
end

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

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