Carte de stockage de mémoire

Cartes de hachage , semblables aux cartes triées, vous permettent de stocker des données en mémoire en tant que paires clé-valeur.Contrairement aux cartes triées, elles ne maintiennent aucune garantie d'ordre.Cette structure de données est utile pour les cas qui nécessitent un stockage de données simple et un accès rapide, tels que les inventaires partagés, les maisons d'enchères physiques et plus encore.Les cartes de hachage gèrent automatiquement la partition de vos données et sont très utiles si vous avez plus de 1 000 clés.Pour les espaces de clé plus petits, nous recommandons cartes triées.

Limites

Les cartes de hachage ont une limite de taille de clé de 128 caractères et une limite de taille de valeur de 32 KB.

Sinon, les cartes de hachage utilisent la même demande d'API et la même limite de mémoire que les autres structures de données de stockage de mémoire.

Obtenir une carte de hachage

Pour obtenir une carte de hachage, appelez MemoryStoreService:GetHashMap() avec un nom pour la carte de hachage.Le nom est global dans l'expérience, vous pouvez donc accéder à la même carte de hachage sur n'importe quel script en utilisant ce nom.

Obtenir une carte de hash
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

Après avoir obtenu une carte de hachage, appelez l'une des fonctions suivantes pour lire ou écrire des données dedans :

Pour une documentation approfondie sur chaque fonction, voir MemoryStoreHashMap .

Ajouter ou écraser des données

Pour ajouter une nouvelle clé ou écraser la valeur d'une clé dans la carte de hachage, appelez avec la clé nom , sa valeur et un temps d'expiration en secondes.La mémoire se nettoie automatiquement une fois que la clé expire.Le temps d'expiration maximum est de 3 888 000 secondes (45 jours).

Ajouter des données à une carte de hachage
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

local setSuccess, _ = pcall(function()
	return hashMap:SetAsync("User_1234", 1000, 30)
end)
if setSuccess then
	print("Set succeeded.")
end

Obtenir des données

Vous pouvez soit obtenir une valeur associée à une clé spécifique, soit obtenir plusieurs paires de valeur-clé dans la carte de hachage.

Obtenir des données avec une clé

Pour obtenir une valeur associée à une clé de la carte de hachage, appelez MemoryStoreHashMap:GetAsync() avec le nom clé .

Obtenir une clé spécifique d'une carte de hachage
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

local setSuccess, _ = pcall(function()
	return hashMap:SetAsync("User_1234", 1000, 30)
end)
if setSuccess then
	print("Set succeeded.")
end

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

Obtenir des données avec plusieurs paires clé-valeur

Pour obtenir tous les couples clé-valeur de la carte de hachage comme une seule opération, appelez MemoryStoreHashMap:ListItemsAsync() avec la taille de page souhaitée.Cette fonction liste toutes les clés existantes de manière paginée.Par exemple, l'échantillon de code suivant récupère jusqu'à 32 éléments de la carte de hachage.

Liste des éléments dans une carte de hachage
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Obtenir la liste des articles, 32 articles à la fois
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Obtenir la page actuelle
		local entries = pages:GetCurrentPage()
		-- Itérer à travers tous les couples clé-valeur sur la page
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Vérifier si la dernière page a été atteinte
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Avancer à la page suivante
			pages:AdvanceToNextPageAsync()
		end
	end
end

Mettre à jour les données

Pour récupérer la valeur d'une clé à partir d'une carte de hachage et la mettre à jour, appelez avec le nom de clé , une fonction d'appel de retour pour mettre à jour la clé, et un temps d'expiration en secondes.

Pour la plupart des expériences, plusieurs serveurs peuvent mettre à jour la même clé simultanément et modifier sa valeur.Comme UpdateAsync() modifie toujours la dernière valeur avant de mettre à jour, vous devez l'utiliser pour lire la dernière valeur en tant qu'entrée pour votre fonction de rappel.

Par exemple, l'exemple de code suivant met à jour le nombre de ressources d'une ressource dans un inventaire partagé.UpdateAsync() garantit que toutes les contributions des joueurs se retrouveront dans cet inventaire partagé, même si ces contributions sont faites simultanément.Dans cette fonction, il applique également un nombre maximum de ressources de 500.

Mise à jour du nombre de ressources pour une ressource dans un inventaire partagé
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("ResourceInventory")

local function contributeResources(itemResource, addedCount)
	local success, newResourceCount = pcall(function()
		return hashMap:UpdateAsync(itemResource, function(resource)
			resource = resource or {count = 0}
			resource.count = resource.count + addedCount

			-- veiller à ne pas dépasser le nombre de ressources maximum
			if resource.count > 500 then
				resource.count = 500
			end
			return resource
		end, 1200)
	end)
	if success then
		print(newResourceCount)
	end
end

Le délai pour UpdateAsync() est similaire à GetAsync() et SetAsync() à moins qu'il y ait une compétition.

Lorsque la controverse se produit, le système réessaie automatiquement l'opération jusqu'à ce que l'une de ces trois choses se produise : l'opération réussit, la fonction de rappel retourne nil ou le nombre maximum de tentatives est atteint.Si le système atteint le nombre maximum de réessais, il renvoie un conflit.

Supprimer des données

Vous pouvez utiliser MemoryStoreHashMap:RemoveAsync() pour supprimer une clé de la carte de hachage et supprimer toutes les données dans une carte de stockage de mémoire.

Supprimer une clé

Pour supprimer une clé de la carte de hachage, appelez avec un nom de clé .

Supprimer une clé d'une carte de hachage
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

local setSuccess, _ = pcall(function()
	return hashMap:SetAsync("User_1234", 1000, 30)
end)
if setSuccess then
	print("Set succeeded.")
end

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

Supprimer toutes les données

Pour supprimer toutes les données dans une carte de hachage, listez tous vos articles avec MemoryStoreHashMap:ListItemsAsync() , puis supprimez-les avec MemoryStoreHashMap:RemoveAsync() .

Supprimer toutes les données dans une carte de hachage
local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Obtenir la liste des articles, 32 articles à la fois
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Obtenir la page actuelle
		local entries = pages:GetCurrentPage()
		local removeSuccess = true
		local removeError = nil
		-- Itérer à travers tous les couples clé-valeur sur la page
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
			removeSuccess, removeError = pcall(function()
				hashMap:RemoveAsync(entry.key)
			end)

			if not removeSuccess then
				warn(removeError)
			end
		end
		-- Vérifier si la dernière page a été atteinte
		if pages.IsFinished then
			print("Finished deleting all data.")
			break
		else
			print("----------")
			-- Avancer à la page suivante
			pages:AdvanceToNextPageAsync()
		end
	end
end