Mappa ordinata della memoria

La mappa ordinata della struttura dati dei memorizzatori in memoria consente di memorizzare dati frequenti in memoria come coppie chiave-valore con una chiave di ordinamento opzionale e mantenere un ordine specifico basato sulle chiavi di ordinamento e sulle chiavi. A differenza delle code, l'ordine delle chiavi che entrano in una mappa non determina l'ordine di elaborazione, rendendo le mappe ordinate utili per l'organizzazione dei dati basata sull'ordinamento per implementare entità di gioco per il coinvolgimento come classifiche e aste tra server.

Limiti

Oltre ai limiti delle dimensioni della struttura dati, le mappe ordinate hanno un limite di dimensione della chiave di 128 caratteri, un limite di dimensione del valore di 32 KB e un limite di dimensione della chiave di ordinamento di 128 caratteri.

Se hai bisogno di memorizzare dati che superano questo limite per il tuo gioco, puoi adottare la tecnica dello sharding per suddividerli e distribuirli tramite prefisso della chiave in più strutture dati. Lo sharding dei memorizzatori in memoria può anche aiutare a migliorare la scalabilità del tuo sistema.

Ottieni una mappa ordinata

Per ottenere una mappa ordinata, chiama MemoryStoreService:GetSortedMap() con un nome che desideri definire per la mappa. Il nome è globale all'interno del gioco, quindi puoi accedere alla stessa mappa ordinata da qualsiasi script utilizzando il nome.

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

Dopo aver ottenuto una mappa ordinata, chiama una delle seguenti funzioni:

Aggiungi o sovrascrivi dati

Per aggiungere una nuova chiave o sovrascrivere il valore o la chiave di ordinamento di una chiave nella mappa ordinata, chiama MemoryStoreSortedMap:SetAsync() con il nome della chiave name, il suo valore, un tempo di scadenza in secondi e una chiave di ordinamento facoltativa. La memoria si pulisce automaticamente una volta che la chiave scade. Il tempo di scadenza massimo è di 3.888.000 secondi (45 giorni). La chiave di ordinamento, se fornita, deve essere un numero valido (intero o a punto mobile) o una stringa.

Nell'ordine di ordinamento delle tue chiavi, una chiave di ordinamento ha la precedenza su una chiave. Ad esempio, quando si ordina in ordine crescente, le chiavi di ordinamento numeriche vengono ordinate per prime, seguite dalle chiavi di ordinamento stringa, seguite dagli elementi senza chiave di ordinamento. Tutti gli elementi con chiavi di ordinamento numeriche sono ordinati in base alla chiave di ordinamento; se la chiave di ordinamento per due elementi è uguale, vengono ordinati in base alla chiave. Analogamente, tutti gli elementi con chiavi di ordinamento stringa sono ordinati in base alla chiave di ordinamento; se la chiave di ordinamento per due elementi è uguale, vengono ordinati in base alla chiave. Tutti gli elementi senza chiave di ordinamento sono ordinati solo in base alla chiave.

Esempio di alcuni dati ordinati in ordine 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}

Nota come player0 si ordina dopo tutte le chiavi con una chiave di ordinamento. player6 si ordina dopo tutte le chiavi con una chiave di ordinamento numerica. player4 e player5 hanno la stessa chiave di ordinamento, quindi vengono ordinate in ordine crescente in base alla chiave.

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("Impostazione riuscita.")
end

Ottieni dati

Puoi ottenere sia un valore dei dati e la chiave di ordinamento associata a una chiave specifica o ottenere più valori e chiavi di ordinamento per chiavi all'interno di un intervallo.

Ottieni dati con una chiave

Per ottenere un valore e la chiave di ordinamento associati a una chiave dalla mappa ordinata, chiama MemoryStoreSortedMap:GetAsync() con il nome della chiave name.

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("Impostazione riuscita.")
end

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

Ottieni dati con più chiavi

Per ottenere dati per più chiavi dalla mappa ordinata come un'unica operazione, chiama MemoryStoreSortedMap:GetRangeAsync(). Questa funzione elenca tutte le chiavi esistenti per impostazione predefinita, ma puoi impostare i limiti superiori e inferiori per l'intervallo delle chiavi. Ad esempio, il seguente campione di codice recupera fino a 20 elementi a partire dall'inizio della mappa ordinata, con chiavi maggiori o uguali a 10, chiavi di ordinamento maggiori o uguali a 100 e chiavi minori o uguali a 50, chiavi di ordinamento minori o uguali 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

-- Ottieni fino a 20 elementi a partire dall'inizio
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

Aggiorna dati

Per recuperare il valore e la chiave di ordinamento di una chiave da una mappa ordinata e aggiornarlo, chiama MemoryStoreSortedMap:UpdateAsync() con il nome della chiave name, una funzione di callback per aggiornare il valore e la chiave di ordinamento per questa chiave e un tempo di scadenza in secondi. Il tempo di scadenza massimo è di 3.888.000 secondi (45 giorni).

Per la maggior parte dei giochi, più server possono aggiornare la stessa chiave contemporaneamente e cambiare il valore. Poiché UpdateAsync() modifica sempre l'ultimo valore prima dell'aggiornamento, dovresti usarlo per leggere l'ultimo valore come input per la tua funzione di callback.

Ad esempio, il seguente campione di codice aggiorna il punteggio in una classifica per un giocatore. Il punteggio è calcolato come uccisioni / morti. UpdateAsync() garantisce che le uccisioni e le morti siano aggiornate per i valori più recenti anche se più server di gioco aggiornano contemporaneamente lo stesso elemento. Le uccisioni e le morti di un giocatore sono valori in aumento monotono e possono quindi solo aumentare di valore in una sessione.

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` è la chiave di ordinamento utilizzata per ordinare gli elementi nella mappa
				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 latenza per UpdateAsync() è simile a GetAsync() e SetAsync() a meno che non ci sia contesa.

Quando si verifica contesa, il sistema ripete automaticamente l'operazione fino a quando una di queste tre cose non succede: l'operazione ha successo, la funzione di callback restituisce nil o viene raggiunto il numero massimo di ripetizioni. Se il sistema raggiunge il numero massimo di ripetizioni, restituisce un conflitto.

Rimuovi dati

Puoi usare MemoryStoreSortedMap:RemoveAsync() sia per rimuovere una chiave dalla mappa ordinata sia per eliminare tutti i dati in una mappa ordinata di memorizzazione in memoria.

Rimuovi una chiave

Per rimuovere una chiave dalla mappa ordinata, chiama MemoryStoreSortedMap:RemoveAsync() con un nome della chiave name.

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("Impostazione riuscita.")
end

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

Elimina tutti i dati

Per eliminare la memoria nelle mappe ordinate, elenca tutte le tue chiavi con MemoryStoreSortedMap:GetRangeAsync(), quindi rimuovile con MemoryStoreSortedMap:RemoveAsync().

local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

-- Il limite inferiore iniziale di nil inizia a svuotare dal primo elemento
local exclusiveLowerBound = nil

while true do
	-- Ottieni fino a cento elementi a partire dal limite inferiore corrente
	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 c'è stato un errore nella rimozione degli elementi, riprova con lo stesso limite inferiore esclusivo
		if not removeSuccess then
			warn(removeError)
		-- Se l'intervallo è inferiore a cento elementi, è stata raggiunta la fine della mappa
		elseif #items < 100 then
			break
		else
			-- L'ultima chiave recuperata è il limite inferiore esclusivo per l'iterazione successiva
			exclusiveLowerBound = {}
			exclusiveLowerBound["key"] = items[#items].key
			exclusiveLowerBound["sortKey"] = items[#items].sortKey
		end
	end
end

Ottieni dimensione

Per ottenere il numero di elementi nella mappa ordinata, chiama 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("Impostazione riuscita.")
end

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

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