Configurations d'expérience

Configurations d'expérience vous permettent de mettre à jour des valeurs en jeu en temps réel sans redémarrer les serveurs :

• Activer ou désactiver des fonctionnalités, comme activer ou désactiver un nouveau donjon d'introduction.
• Ajuster les valeurs en jeu telles que la santé des boss, le gain d'expérience ou les prix des objets.
• Lancer du contenu limité dans le temps, comme un événement d'Halloween qui commence à minuit.

Les configurations prennent la forme de clés et de valeurs. Plutôt que d'utiliser des constantes codées en dur dans votre code, vous pouvez utiliser la clé pour obtenir une valeur (chaîne, nombre, booléen ou objet JSON) et ensuite mettre à jour cette valeur quand vous le souhaitez sans publier une nouvelle version de votre expérience. Les modifications de code requises sont minimes :

local ConfigService = game:GetService("ConfigService")
local configSnapshot = ConfigService:GetConfigAsync()
local myValue = configSnapshot:GetValue("my_key_name")

Vous pouvez avoir jusqu'à 1 000 configurations actives à tout moment et les gérer sur Creator Hub ou dans Roblox Studio.

Créer et modifier des configurations

1. Sur la page Configurations du Creator Hub pour votre expérience, cliquez sur Créer une configuration.

2. Spécifiez une clé, un type, une valeur et, éventuellement, une description pour vous aider ou votre équipe à identifier plus tard l'objectif de la configuration. Les types pris en charge sont chaîne, nombre, booléen et objet JSON.

3. Copiez l'extrait de code généré dans un script serveur dans votre expérience, probablement dans ServerScriptService. Le code devrait ressembler à ceci :

   local ConfigService = game:GetService("ConfigService")
   
   local configSnapshot = ConfigService:GetConfigAsync()
   local MY_KEY = "my_key" -- optionnel, stockez la clé de la configuration comme une constante
   local myValue = configSnapshot:GetValue(MY_KEY)

4. Utilisez la valeur comme vous le feriez pour toute autre variable. Les configurations ne font rien à moins que vous ne les utilisiez dans votre code.

Pour plus d'informations sur le travail avec les configurations dans vos scripts, consultez Ajouter des configurations à votre code.

Modifier une configuration ne diffère pas de sa création. Cliquez sur le bouton Modifier et mettez à jour la valeur et la description comme souhaité.

Limites

Les valeurs de configuration ont les limites suivantes par type.

Publier des configurations

Après avoir créé une configuration, elle passe à un état staged afin que vous puissiez la tester avant qu'elle ne devienne publique. Les modifications mises en scène sont disponibles pour vous et votre équipe dans les sessions de jeu de Studio, mais pas pour les joueurs dans les expériences en direct. La page Configurations sur Creator Hub montre toutes les modifications actives et mises en scène.

1. Après avoir testé vos modifications mises en scène, cliquez sur Publier maintenant pour publier à tous les joueurs dans les cinq minutes. Vous pouvez également choisir Publier sur 15 min si vous préférez une période de déploiement plus longue.
2. (Recommandé) Ajoutez un message de publication descriptif qui indique ce que vous avez mis à jour. Ce message apparaît sur la page Historique et peut vous aider, vous et votre équipe, à identifier plus tard l'objectif du changement.

Créer et modifier des configurations dans Studio

Si vous le souhaitez, vous pouvez créer, modifier, mettre en scène et publier des configurations dans Roblox Studio. Cliquez sur Fichier > Ouvrir les configurations pour ouvrir le widget. L'interface de Studio est particulièrement pratique pour mettre en scène et tester de nouvelles valeurs.

Publier des configurations vers une autre expérience

Uniquement dans Studio, vous pouvez publier vos configurations vers une autre expérience, ce qui écrase complètement les configurations pour cette expérience. Cela peut être particulièrement utile pour synchroniser les configurations d'une expérience de mise en scène ou de développement vers l'expérience en direct. Accédez à l'onglet Publié dans le widget Studio et cliquez sur Publier sous dans le menu ⋮.

Voir l'historique et restaurer des configurations

Sur la page Configurations, cliquez sur Historique pour voir les mises à jour passées. Chaque mise à jour a l'heure et la date du changement, qui a effectué le changement, et le message de publication.

• Développez chaque ligne pour voir la clé, la valeur avant le changement, et la valeur après.
• Utilisez la case Rechercher la clé pour rechercher des clés - pas des descriptions ou des valeurs, juste des clés.

La page Historique vous permet également de restaurer des configurations à un état précédent :

1. Cliquez sur Restaurer à côté du changement pour mettre en scène la valeur "avant". Notez que restaurer une configuration supprime toutes les modifications mises en scène existantes.
2. Retournez à la page Configurations et publiez la configuration.

Ajouter des configurations à votre code

La classe principale pour travailler avec des configurations est ConfigService, qui récupère les dernières clés et valeurs pour votre expérience. ConfigService n'est disponible que pour des scripts serveurs. Tenter d'appeler ses méthodes à partir d'un script client entraîne une erreur.

La première étape pour travailler avec des configurations est de récupérer un ConfigSnapshot, les dernières valeurs pour toutes les configurations au moment actuel. Il y a deux méthodes pour obtenir un instantané :

• ConfigService:GetConfigAsync() est pour les configurations globales que vous souhaitez appliquer à tous les joueurs de l'expérience :

  local ConfigService = game:GetService("ConfigService")
  local configSnapshot = ConfigService:GetConfigAsync()
  local bossHealth = configSnapshot:GetValue("bossHealth")

• ConfigService:GetConfigForPlayerAsync() est pour les expériences. Il récupère des configurations spécifiques aux joueurs afin que différents joueurs puissent obtenir différentes valeurs.

  local ConfigService = game:GetService("ConfigService")
  local Players = game:GetService("Players")
  
  local function onPlayerAdded(player)
      local playerConfigSnapshot = ConfigService:GetConfigForPlayerAsync(player)
      local bossHealth = playerConfigSnapshot:GetValue("bossHealth")
  end
  
  Players.PlayerAdded:Connect(onPlayerAdded)

Dans tous les cas, si la clé n'existe pas, ConfigSnapshot:GetValue() renvoie nil.

Rafraîchir les instantanés

ConfigSnapshots représentent un point dans le temps, l'état de la configuration lorsque vous avez demandé l'instantané. Pour éviter de perturber le gameplay, les mises à jour d'une configuration ne se propagent pas automatiquement aux instantanés. Dans un tireur compétitif, par exemple, vous pourriez vouloir seulement de nouvelles valeurs de configuration entre les rounds pour que les attributs des armes ne fluctu le pas en cours de match.

Pour obtenir les dernières valeurs manuellement, utilisez la méthode ConfigSnapshot:Refresh(). En option, connectez une fonction à l'événement ConfigSnapshot.UpdateAvailable pour rafraîchir automatiquement :

configSnapshot.UpdateAvailable:Connect(function()
    configSnapshot:Refresh()
end)

Après avoir rafraîchi un instantané, vous pouvez utiliser ConfigSnapshot:GetValueChangedSignal() pour écouter les changements d'une clé spécifique afin que vous puissiez mettre à jour le code de votre expérience :

configSnapshot:GetValueChangedSignal("bossHealth"):Connect(function(newHealthValue)
    spawnNewBoss(newHealthValue)
end)

Gestion des erreurs

Dans de rares cas où la configuration échoue à se charger et n'a jamais été chargée auparavant, ConfigService:GetConfigAsync() lance une erreur.

Si ConfigService perd la connexion aux serveurs Roblox après avoir été précédemment chargée, ConfigService:GetConfigAsync() renvoie un instantané avec les dernières valeurs disponibles. Ces instantanés tentent de se reconnecter et déclenchent l'événement UpdateAvailable lorsqu'ils chargent avec succès de nouvelles mises à jour.

Comment vous gérez ces situations inhabituelles vous incombe. Vous pouvez envelopper l'appel dans un pcall() et avoir des valeurs de repli dans votre code, montrer une erreur au joueur et attendre que l'instantané se reconnecte, ou choisir une autre solution.

Tester les configurations

ConfigService dispose de méthodes intégrées pour tester temporairement des modifications de configuration à la fois dans Studio et sur des serveurs en direct sans impacter l'ensemble de l'expérience.

Pour définir une valeur de test locale, appelez ConfigService:SetTestingValue() à partir d'un script serveur ou via la Console du développeur. Les modifications des valeurs de test déclenchent une mise à jour de la configuration en plus du signal ConfigSnapshot.UpdateAvailable. Tout comme une mise à jour de production, vous devez rafraîchir les instantanés existants pour obtenir la valeur test :

local ConfigService = game:GetService("ConfigService")
ConfigService:SetTestingValue("bossHealth", 200)

local configSnapshot = ConfigService:GetConfigAsync()
local bossHealth = configSnapshot:GetValue("bossHealth") -- Maintenant 200 !

Les modifications de test s'appliquent pendant toute la durée du serveur en cours et ne se propagent pas à d'autres serveurs. Dans Studio, elles s'appliquent à la session de jeu en cours et n'affectent pas les serveurs en direct. Vous pouvez effacer manuellement les modifications de test avec ConfigService:ClearTestingValue().