Magasins de données

Le DataStoreService vous permet de stocker des données qui doivent persister entre les sessions, comme les objets dans l'inventaire d'un joueur ou les points de compétence. Les magasins de données sont cohérents par jeu, donc n'importe quel endroit dans un jeu peut accéder et changer les mêmes données, y compris des endroits sur différents serveurs.

Si vous souhaitez ajouter un contrôle d'autorisation granulaire à vos magasins de données et y accéder en dehors de Studio ou des serveurs Roblox, vous pouvez utiliser les API Open Cloud pour les magasins de données.

Pour visualiser et surveiller tous les magasins de données dans un jeu à travers le Creator Hub, utilisez le Gestionnaire de magasins de données.

Pour les données temporaires que vous devez mettre à jour ou accéder fréquemment, utilisez les magasins en mémoire.

Activer l'accès Studio

Par défaut, les jeux testés dans Studio ne peuvent pas accéder aux magasins de données, vous devez donc d'abord les activer. Accéder aux magasins de données dans Studio peut être dangereux pour les jeux en ligne, car Studio accède aux mêmes magasins de données que l'application cliente. Pour éviter de remplacer les données de production, ne pas activer ce paramètre pour les jeux en ligne. Au lieu de cela, activez-le pour une version de test séparée du jeu.

Pour activer l'accès Studio dans un jeu publié :

1. Ouvrez la fenêtre Fichier ⟩ Paramètres d'expérience de Studio.
2. Allez à Sécurité.
3. Activez le commutateur Activer l'accès Studio aux services API.
4. Cliquez sur Enregistrer.

Accéder aux magasins de données

Pour accéder à un magasin de données à l'intérieur d'un jeu :

1. Ajoutez DataStoreService à un Script côté serveur.
2. Utilisez la fonction GetDataStore() et spécifiez le nom du magasin de données que vous souhaitez utiliser. Si le magasin de données n'existe pas, Studio en crée un lors de l'enregistrement de vos données de jeu pour la première fois.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

Créer des données

Un magasin de données est essentiellement un dictionnaire, similaire à une table Luau. Une clé unique indexe chaque valeur dans le magasin de données, comme l'Player.UserId unique d'un utilisateur ou une chaîne nommée pour une promotion de jeu.

Pour créer une nouvelle entrée, appelez SetAsync() avec le nom de la clé et une valeur.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local success, errorMessage = pcall(function()
	gameStore:SetAsync("User_1234", 50)
end)
if not success then
	print(errorMessage)
end

Mettre à jour des données

Pour changer n'importe quelle valeur stockée dans un magasin de données, appelez UpdateAsync() avec le nom de la clé de l'entrée et une fonction de rappel qui définit comment vous souhaitez mettre à jour l'entrée. Ce rappel prend la valeur actuelle et retourne une nouvelle valeur basée sur la logique que vous définissez. Si le rappel retourne nil, l'opération d'écriture est annulée et la valeur n'est pas mise à jour.

local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local function makeNameUpper(currentName)
	local nameUpper = string.upper(currentName)
	return nameUpper
end

local success, updatedName = pcall(function()
	return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
end)
if success then
	print("Nom en majuscules :", updatedName)
end

Définir vs mettre à jour

Utilisez set pour mettre à jour rapidement une clé spécifique. La fonction SetAsync() :

• Peut causer des incohérences de données si deux serveurs tentent de définir la même clé en même temps.
• Ne compte que pour la limite d'écriture.

Utilisez update pour gérer les tentatives multi-serveurs. La fonction UpdateAsync() :

• Lit la valeur actuelle de la clé depuis le serveur qui l'a mise à jour en dernier avant de faire des modifications.
• Est plus lente car elle lit avant d'écrire.
• Compte pour les limites de lecture et d'écriture.

Lire des données

Pour lire la valeur d'une entrée de magasin de données, appelez GetAsync() avec le nom de la clé de l'entrée.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local success, currentGame = pcall(function()
	return gameStore:GetAsync("User_1234")
end)
if success then
	print(currentGame)
end

Incrémenter des données

Pour incrémenter un entier dans un magasin de données, appelez IncrementAsync() avec le nom de la clé de l'entrée et un nombre pour combien changer la valeur. IncrementAsync() est une fonction de commodité qui vous permet d'éviter d'appeler UpdateAsync() et d'incrémenter manuellement l'entier.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local success, newGame = pcall(function()
	return gameStore:IncrementAsync("Player_1234", 1)
end)
if success then
	print(newGame)
end

Supprimer des données

Pour supprimer une entrée et retourner la valeur associée à la clé, appelez RemoveAsync().

local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local success, removedValue = pcall(function()
	return nicknameStore:RemoveAsync("User_1234")
end)
if success then
	print(removedValue)
end

Métadonnées

Il existe deux types de métadonnées associées aux clés :

• Défini par le service : Métadonnées par défaut en lecture seule, comme le temps de mise à jour le plus récent et le temps de création. Chaque objet a des métadonnées définies par le service.
• Défini par l'utilisateur : Métadonnées personnalisées pour le marquage et la catégorisation. Définies à l'aide de l'objet DataStoreSetOptions et de la fonction SetMetadata().

Pour gérer les métadonnées, développez les fonctions SetAsync(), UpdateAsync(), GetAsync(), IncrementAsync() et RemoveAsync().

• SetAsync() accepte les troisième et quatrième arguments optionnels :

  • Une table de UserIds. Cela peut aider à suivre et à supprimer les droits d'auteur et la propriété intellectuelle du contenu.

  • Un objet DataStoreSetOptions, où vous pouvez définir des métadonnées personnalisées à l'aide de la fonction SetMetadata().

    local DataStoreService = game:GetService("DataStoreService")
    
    local gameStore = DataStoreService:GetDataStore("PlayerGame")
    
    local setOptions = Instance.new("DataStoreSetOptions")
    setOptions:SetMetadata({["GameElement"] = "Fire"})
    
    local success, errorMessage = pcall(function()
        gameStore:SetAsync("User_1234", 50, {1234}, setOptions)
    end)
    if not success then
        print(errorMessage)
    end

• GetAsync(), IncrementAsync() et RemoveAsync() retournent une deuxième valeur dans l'objet DataStoreKeyInfo. Cette deuxième valeur contient à la fois les propriétés définies par le service et les fonctions permettant de récupérer les métadonnées définies par l'utilisateur.

  • La fonction GetUserIds() récupère la table de UserIds que vous avez passée à SetAsync().
  • La fonction GetMetadata() récupère les métadonnées définies par l'utilisateur que vous avez passées à SetAsync() à travers SetMetadata().
  • La propriété Version récupère la version de la clé.
  • La propriété CreatedTime récupère le temps de création de la clé, formaté en nombre de millisecondes depuis l'époque.
  • La propriété UpdatedTime récupère la dernière fois que la clé a été mise à jour, formatée comme le nombre de millisecondes depuis l'époque.

  local DataStoreService = game:GetService("DataStoreService")
  
  local gameStore = DataStoreService:GetDataStore("PlayerGame")
  
  local success, currentGame, keyInfo = pcall(function()
      return gameStore:GetAsync("User_1234")
  end)
  if success then
      print(currentGame)
      print(keyInfo.Version)
      print(keyInfo.CreatedTime)
      print(keyInfo.UpdatedTime)
      print(keyInfo:GetUserIds())
      print(keyInfo:GetMetadata())
  end

• La fonction de rappel de UpdateAsync() prend un paramètre supplémentaire dans l'objet DataStoreKeyInfo qui décrit l'état actuel de la clé. Elle retourne la valeur modifiée, les clés associées à UserIds, et les métadonnées de la clé.

  local DataStoreService = game:GetService("DataStoreService")
  
  local nicknameStore = DataStoreService:GetDataStore("Nicknames")
  
  local function makeNameUpper(currentName, keyInfo)
      local nameUpper = string.upper(currentName)
      local userIDs = keyInfo:GetUserIds()
      local metadata = keyInfo:GetMetadata()
      return nameUpper, userIDs, metadata
  end
  
  local success, updatedName, keyInfo = pcall(function()
      return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
  end)
  if success then
      print(updatedName)
      print(keyInfo.Version)
      print(keyInfo.CreatedTime)
      print(keyInfo.UpdatedTime)
      print(keyInfo:GetUserIds())
      print(keyInfo:GetMetadata())
  end

Pour les limites lors de la définition des métadonnées, voir les limites des métadonnées.

Magasins de données ordonnés

Par défaut, les magasins de données ne trient pas leur contenu. Si vous devez obtenir des données de manière ordonnée, comme dans les statistiques de tableaux des leaders persistants, appelez GetOrderedDataStore() au lieu de GetDataStore().

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

Les magasins de données ordonnés prennent en charge les mêmes fonctions de base que les magasins de données par défaut, plus la fonction unique GetSortedAsync(). Cela récupère plusieurs clés triées en fonction d'un ordre spécifique de tri, de la taille de la page, et des valeurs minimales/maximales.

L'exemple suivant trie les données des personnages en pages de trois entrées, chacune dans un ordre décroissant, puis parcourt les pages et affiche le nom et l'âge de chaque personnage.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- Remplit le magasin de données ordonné
local characters = {
	Mars = 19,
	Janus = 20,
	Diana = 18,
	Venus = 25,
	Neptune = 62
}
for char, age in characters do
	local success, errorMessage = pcall(function()
		characterAgeStore:SetAsync(char, age)
	end)
	if not success then
		print(errorMessage)
	end
end

-- Trie les données par ordre décroissant dans des pages de trois entrées chacune
local success, pages = pcall(function()
	return characterAgeStore:GetSortedAsync(false, 3)
end)
if success then
	while true do
		-- Obtient la page actuelle (première)
		local entries = pages:GetCurrentPage()
		-- Itère à travers toutes les paires clé-valeur de la page
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Vérifie si la dernière page a été atteinte
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Avance à la page suivante
			pages:AdvanceToNextPageAsync()
		end
	end
end