Mapa organizado armazenado na memória

A estrutura de dados do mapa ordenado , de armazenamentos de memória, permite que você armazene dados frequentes em memória como pares de chave-valor com uma chave de classificação opcional e mantenha uma ordem específica com base nas chaves de classificação e nas chaves.Ao contrário de filas, a ordem das chaves que entram em um mapa não determina a ordem de processamento, tornando os mapas classificados úteis para organizar dados baseados em dados para implementar entidades na experiência para engajamento, como placares e leilões de servidores transversais.

Limitos

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 excedam esse limite para sua experiência, você pode adotar a técnica de sharding para dividir e distribuir através de pré-fixo de chave em múltiplas estruturas de dados.Armazenamentos de memória de fragmentação também podem ajudar a melhorar a escalabilidade do seu sistema.

Obtenha um mapa ordenado

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

Obtendo um Mapa Ordenado
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

Depois de obter um mapa ordenado, chame qualquer uma das seguintes funções para ler ou escrever dados nele:

Adicionar ou substituir dados

Para adicionar uma nova chave ou substituir o valor ou o tipo de chave de uma chave no mapa classificado, chame MemoryStoreSortedMap:SetAsync() com a chave nome , seu valor , um tempo de expiração em segundos e uma chave de classificação opcional .A memória limpa automaticamente quando a chave expira.O tempo máximo de expiração é 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 / cadeia / texto.

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, as chaves de classificação numérica se classificam primeiro, seguidas por chaves de classificação de texto e, em seguida, por itens sem chave de classificação.Todos os itens com chaves de classificação numéricas são classificados por chave de classificação, se a chave de classificação para dois itens for igual, eles são classificados por chave.Da mesma forma, todos os itens com chaves de classificação de corda são classificados por chave de classificação, se a chave de classificação para dois itens for igual, eles são classificados por chave.Todos os itens sem chave de classificação são classificados apenas pela chave.

Exemplo de alguns dados ordenados 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}

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

Adicionando dados a um 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("Set succeeded.")
end

Obter dados

Você pode obter um valor de dados e classificar a chave associada a uma chave específica ou obter vários valores e classificar chaves dentro de um alcance.

Obtenha dados com uma chave

Para obter um valor e classificar a chave associada a uma chave do mapa classificado, chame com o nome da chave .

Obtendo uma Chave Específica de um 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("Set succeeded.")
end

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

Obtenha dados com várias chaves

Para obter dados para várias chaves a partir do mapa ordenado como uma única operação, chame MemoryStoreSortedMap:GetRangeAsync().Essa função lista todas as chaves existentes por padrão, mas você pode definir os limites superiores e inferiores para o alcance de chaves.Por exemplo, o seguinte código de amostra recupera até 20 itens a partir do início do mapa ordenado, com chaves maiores que ou iguais a 10 , chaves de classificação maiores que ou iguais a 100 e chaves menores que ou iguais a 50 , chaves de classificação menores que ou iguais a 500.

Obtendo uma faixa de chaves de um 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

-- Obtenha até 20 itens a partir 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 a chave de classificação de uma chave de um mapa classificado e atualizá-la, chame com a chave nome , uma função de chamada de retorno para atualizar o valor e a chave de classificação para essa chave e um tempo de expiração em segundos.O tempo máximo de expiração é 3,888,000 segundos (45 dias).

Para a maioria das experiências, vários servidores podem atualizar a mesma chave simultaneamente e alterar o valor.Como UpdateAsync() sempre modifica o último valor antes de atualizar, você deve usá-lo para ler o último valor como a entrada para a função de chamada de volta.

Por exemplo, o seguinte código de exemplo atualiza a pontuação em uma tabela de classificação para um jogador em um jogo.A pontuação é calculada como mortes / mortes.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 assassinatos de um jogador estão aumentando monotonamente e, portanto, só podem aumentar em valor em uma sessão.

Atualizando a pontuação da tabela de classificação para um jogador em um 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` é a chave de triagem que está sendo 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 UpdateAsync() é semelhante a GetAsync() e SetAsync() a menos que haja concorrência.

Quando ocorre conflito, o sistema tenta automaticamente a operação novamente até que uma dessas três ocorra: a operação tenha sucesso, a função de retorno retorne nil ou o número máximo de tentativas seja atingido.Se o sistema atingir o número máximo de tentativas, ele retorna um conflito.

Remover dados

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

Remova uma chave

Para remover uma chave do mapa classificado, chame com um nome de chave .

Remova uma Chave de um 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("Set succeeded.")
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(), então remova-as com MemoryStoreSortedMap:RemoveAsync() .

Excluir Memória em um Mapa Ordenado
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

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

while true do
	-- Obtenha até cem itens começando pelo 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 alcance for menor que cem itens, o fim do mapa é 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