Mappa ordinata dello store di memoria

La struttura dati mappa ordinata degli store di memoria consente di memorizzare dati in memoria frequenti 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 basati su ordinamento per implementare entità di gioco per il coinvolgimento, come le classifiche e le aste tra server.

Limiti

Oltre ai limiti di dimensione 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 di sharding per suddividerli e distribuirli tramite prefisso della chiave in più strutture dati. Lo sharding degli store di 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 in 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 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, il suo valore, un tempo di scadenza in secondi e una chiave di ordinamento opzionale. La memoria si pulisce automaticamente appena la chiave scade. Il tempo massimo di scadenza è di 3.888.000 secondi (45 giorni). La chiave di ordinamento, se fornita, deve essere un numero valido (intero o decimale) 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 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 stringa 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 ordinamento sono ordinati solo per 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 viene ordinato dopo tutte le chiavi con una chiave di ordinamento. player6 viene ordinato dopo tutte le chiavi con una chiave di ordinamento numerica. player4 e player5 hanno la stessa chiave di ordinamento, 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("Impostazione riuscita.")
end

Ottieni dati

Puoi ottenere sia un valore di dati e una chiave di ordinamento associati a una chiave specifica, sia più valori e chiavi di ordinamento per 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 della 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("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 di 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.

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 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 aggiornarla, chiama MemoryStoreSortedMap:UpdateAsync() con il nome della chiave, 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 massimo di scadenza è di 3.888.000 secondi (45 giorni).

Per la maggior parte dei giochi, più server possono aggiornare la stessa chiave in modo concorrente 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 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 lo stesso elemento simultaneamente. Le uccisioni e le morti di un giocatore sono valori crescenti e quindi possono solo aumentare di valore in una sessione.

Aggiornare il 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

La latenza per UpdateAsync() è simile a GetAsync() e SetAsync() a meno che non ci sia contesa.

Quando si verifica la contesa, il sistema ripete automaticamente l'operazione finché non si verifica una delle seguenti tre situazioni: l'operazione ha successo, la funzione di callback restituisce nil, o viene raggiunto il numero massimo di tentativi. Se il sistema raggiunge il numero massimo di tentativi, restituisce un conflitto.

Rimuovi dati

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

Rimuovi una chiave

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

Rimuovere 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("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().

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

local sortedMap = MemoryStoreService:GetSortedMap("SortedMap1")

-- Limite inferiore iniziale di nil inizia a scaricare dal primo elemento
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'è stato un errore durante la 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().

Ottenere la dimensione di 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("Impostazione riuscita.")
end

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

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