Memoria store mappa ordinata

La struttura dei dati della mappa ordinata sortita di magazzini di memoria ti consente di archiviare dati frequenti in memoria come coppie chiave-valore con una chiave di ordinamento opzionale e mantenere un ordine specifico in base alle chiavi e alle chiavi.A differenza delle code, l'ordine delle chiavi che entrano in una mappa non determina l'ordine di esecuzione, rendendo le mappe ordinate utili per ordinare i dati organizzati per la realizzazione di entità di coinvolgimento come classifiche e aste cross-server.

Limitazioni

Oltre ai limiti della dimensione della struttura dei 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 devi archiviare dati che superano questo limite per la tua esperienza, puoi adottare la tecnica di sharding per dividerli e distribuirli attraverso prefisso chiave in più strutture di dati.Anche i depositi di memoria frammentati possono aiutare a migliorare la scalabilità del tuo sistema.

Ottieni una mappa ordinata

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

Ottenere una mappa ordinata
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

Dopo aver ottenuto una mappa ordinata, chiama una qualsiasi delle seguenti funzioni per leggere o scrivere dati in essa:

Aggiungi o sovrascrivi i dati

Per aggiungere una nuova chiave o sovrascrivere il valore o il tipo di chiave di una chiave nella mappa ordinata, chiama MemoryStoreSortedMap:SetAsync() con la chiave nome , il suo valore , un tempo di scadenza in secondi e una chiave di sorta opzionale .La memoria si pulisce automaticamente una volta che la chiave scade.Il tempo massimo di scadenza è 3,888,000 secondi (45 giorni).La chiave di ordinamento, se fornita, deve essere un numero valido (intero o punto fluttuante) o una Stringa.

Nell'ordine di selezione delle tue chiavi, una chiave di selezione ha precedenza su una chiave.Ad esempio, quando si ordina in ordine crescente, le chiavi di ordinamento numeriche si ordinano prima, seguite da chiavi di ordinamento delle stringhe, seguite da oggetti senza chiave di ordinamento.Tutti gli elementi con chiavi di ordinamento numeriche vengono ordinati per chiave di ordinamento, se la chiave di ordinamento per due elementi è uguale, vengono ordinati per chiave.Allo stesso modo, tutti gli elementi con chiavi di ordinamento delle stringhe sono ordinati per chiave di ordinamento, se la chiave di ordinamento per due elementi è uguale, vengono ordinati per chiave.Tutti gli elementi senza chiave di tipo vengono ordinati solo dalla 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 ordina dopo tutte le chiavi con una chiave di ordinamento.player6 ordina dopo tutte le chiavi con una chiave di ordinamento numerica.player4 e player5 hanno la stessa chiave di tipo, quindi vengono ordinati in ordine crescente per chiave.

Aggiungere dati a una mappa ordinata
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

Ottieni dati

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

Ottieni dati con una chiave

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

Ottenere una chiave particolare da una mappa ordinata
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

Ottieni dati con più chiavi

Per ottenere i 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 l'intervallo superiore e inferiore per la gamma di chiavi.Ad esempio, il seguente esempio 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 inferiori o uguali a 50 , chiavi di ordinamento inferiori o uguali a 500 .

Ottenere un intervallo di chiavi da una mappa ordinata
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 oggetti 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 il tasto di ordinamento di una chiave da una mappa ordinata e aggiornarla, chiama con il nome della chiave , una funzione di richiamo per aggiornare il valore e il tasto di ordinamento per questa chiave e un tempo di scadenza in secondi.Il tempo massimo di scadenza è 3,888,000 secondi (45 giorni).

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

Ad esempio, il seguente esempio di codice aggiorna il punteggio in una classifica per un giocatore in una Gioco.Il punteggio viene calcolato come uccisioni / decessi.UpdateAsync() garantisce che le uccisioni e le morti vengono aggiornate per i valori più recenti anche se più server di gioco aggiornano lo stesso oggetto contemporaneamente.Le uccisioni e le morti di un Giocatoreaumentano monotonamente e possono quindi aumentare solo di valore in una Sessione.

Aggiornamento del punteggio della classifica per un giocatore in una mappa ordinata
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

Il ritardo per UpdateAsync() è simile a GetAsync() e SetAsync() a meno che non ci sia una concorrenza.

Quando si verifica una concorrenza, il sistema riprova automaticamente l'operazione fino a quando uno di questi tre eventi non accade: l'operazione ha successo, la funzione di richiamo restituisce nil , o si raggiunge il numero massimo di riprobi.Se il sistema raggiunge il numero massimo di riprobi, restituisce un conflitto.

Rimuovi i dati

Puoi usare MemoryStoreSortedMap:RemoveAsync() per entrambi rimuovere una chiave dalla mappa ordinata e eliminare tutti i dati in una mappa memorizzata ordinata.

Rimuovi una chiave

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

Rimuovi una chiave da una mappa ordinata
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

Elimina tutti i dati

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

Elimina memoria in una mappa ordinata
local MemoryStoreService = game:GetService("MemoryStoreService")

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

-- Limite inferiore iniziale di nil inizia a scorrere dall'Articoloprimo
local exclusiveLowerBound = nil

while true do
	-- Ottieni fino a cento elementi a partire dal limite inferiore attuale
	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'era un errore nell'eliminazione degli elementi, riprova con lo stesso limite inferiore esclusivo
		if not removeSuccess then
			warn(removeError)
		-- Se la portata è inferiore a cento elementi, viene raggiunto il limite della mappa
		elseif #items < 100 then
			break
		else
			-- L'ultima chiave recuperata è il limite inferiore esclusivo per la prossima iterazione
			exclusiveLowerBound = {}
			exclusiveLowerBound["key"] = items[#items].key
			exclusiveLowerBound["sortKey"] = items[#items].sortKey
		end
	end
end