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 permettre ou désactiver un nouveau donjon d'intégration.
• Ajuster des valeurs en jeu telles que la santé du boss, le gain d'expérience ou les prix des objets.
• Lancer du contenu temporaire, 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, vous 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 de 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 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 des configurations dans vos scripts, consultez Ajouter des configurations à votre code.

Modifier une configuration n'est pas différent de sa création. Cliquez sur le bouton Modifier et mettez à jour la valeur et la description si vous le souhaitez.

Limites

Les valeurs de configuration ont les limites suivantes par type.

Publier des configurations

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

1. Après avoir testé vos modifications préparées, cliquez sur Publier maintenant pour les publier auprès de 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 indiquant 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, préparer et publier des configurations dans Roblox Studio. Cliquez sur Fichier > Ouvrir les Configurations. L'interface du Studio est particulièrement pratique pour préparer et tester de nouvelles valeurs.

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 boîte Rechercher la clé pour rechercher des clés—pas de descriptions ou de 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 préparer la valeur "avant". Notez que restaurer une configuration annule toutes les modifications préparées existantes.
2. Retournez sur 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 les scripts serveur. Essayer d'appeler ses méthodes depuis 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 existe deux méthodes pour obtenir un instantané :

• ConfigService:GetConfigAsync() est destiné aux 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 les deux cas, si la clé n'existe pas, ConfigSnapshot:GetValue() renvoie nil.

Actualiser 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 ne vouloir que de nouvelles valeurs de configuration entre les tours afin que les attributs des armes ne fluctuent pas pendant le 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 actualiser automatiquement :

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

Après avoir actualisé 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() génère une erreur.

Si ConfigService perd la connexion aux serveurs Roblox après avoir été précédemment chargé, 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 lorsque de nouvelles mises à jour sont chargées avec succès.

Comment vous gérez ces situations rares vous appartient. Vous pouvez envelopper l'appel dans un pcall() et avoir des valeurs par défaut dans votre code, montrer un message d'erreur au joueur et attendre que l'instantané se reconnecte, ou une autre solution.

Tester les configurations

ConfigService dispose de méthodes intégrées pour tester temporairement les 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 développeur. Les modifications des valeurs de test déclenchent une mise à jour de la configuration avec le signal ConfigSnapshot.UpdateAvailable. Tout comme une mise à jour de production, vous devez actualiser les instantanés existants pour obtenir la valeur de 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 pour la durée du serveur actuel et ne se propagent pas à d'autres serveurs. Dans Studio, elles s'appliquent à la session de jeu actuelle et n'affectent pas les serveurs en direct. Vous pouvez effacer manuellement les modifications de test avec ConfigService:ClearTestingValue().