Configurations d'expérience

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

• Activer ou désactiver des fonctionnalités, comme l'activation ou la désactivation d'un nouveau donjon d'intégration.
• Ajuster les valeurs en jeu telles que la santé des boss, le gain d'expérience ou les prix des objets.
• Lancer du contenu temporaire, comme un événement d'Halloween qui commence à minuit.
• Donner des valeurs différentes à différents joueurs, comme donner aux nouveaux joueurs une armure supplémentaire.

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, en option, 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. Cliquez sur Suivant.

3. (Optionnel) Ajoutez des conditions et des valeurs de ciblage. Les conditions vous permettent d'appliquer des valeurs de configuration aux utilisateurs qui correspondent (ou ne correspondent pas) à certains critères, tels que les utilisateurs qui n'ont jamais joué à votre jeu ou ceux qui parlent portugais. Pour en savoir plus, voir Cibler des configurations pour des joueurs spécifiques.

4. Copiez le code généré dans un script serveur de votre expérience, probablement dans ServerScriptService. Pour les configurations "globales" qui ne diffèrent pas selon le joueur, le code pourrait 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)

   Pour les configurations conditionnelles et les expériences, le code est légèrement différent :

   local ConfigService = game:GetService("ConfigService")
   local Players = game:GetService("Players")
   local MY_KEY = "my_key" -- optionnel, stockez la clé de configuration comme une constante
   
   local function onPlayerAdded(player)
       local playerConfigSnapshot = ConfigService:GetConfigForPlayerAsync(player)
       local myValue = playerConfigSnapshot:GetValue(MY_KEY)
   end
   
   Players.PlayerAdded:Connect(onPlayerAdded)

5. 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, voir Ajouter des configurations à votre code.

Modifier une configuration n'est pas différent de la création d'une. 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 en attente afin que vous puissiez la tester avant qu'elle ne devienne disponible publiquement. Les modifications en attente 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 en attente.

1. Après avoir testé vos modifications en attente, cliquez sur Publier maintenant pour publier à tous les joueurs presque instantanément (environ entre 15 secondes et 1 minute). Vous pouvez également choisir Publier sur 15 min si vous préférez une période de déploiement plus longue et plus progressive. Dans certains cas, les clients peuvent prendre quelques minutes pour refléter les modifications après publication.
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 aider vous et votre équipe à identifier plus tard l'objectif du changement.

Cibler des configurations pour des joueurs spécifiques

Par défaut, une configuration délivre la même valeur à tout le monde. Les configurations conditionnelles vous permettent de délivrer des valeurs différentes à différents joueurs en fonction des attributs des joueurs (pays, ancienneté, langue, statut de payeur, etc.).

Les configurations conditionnelles ont trois parties qui déterminent quelle valeur un joueur reçoit :

• Règles conditionnelles définissent qui correspond. Chaque règle est une expression logique, comme "payeurs actifs dans leurs 30 premiers jours", qui évalue les attributs des joueurs.
• Ordre des règles définit comment choisir lorsque un joueur correspond à plus d'une règle. Roblox évalue les règles de haut en bas et applique la première branche correspondante. Les règles sont ordonnées globalement, indépendamment de l'ordre dans lequel vous ajoutez des valeurs conditionnelles à une clé individuelle.
• Valeurs conditionnelles définissent ce qu'un joueur correspondant obtient. Pour chaque condition, vous attachez une valeur. Si un joueur correspond à une règle dans cette condition, il reçoit la valeur associée ; sinon, il reçoit la valeur par défaut de la configuration.

Attributs pris en charge

Les configurations conditionnelles prennent en charge les attributs suivants. Ces attributs partagent les mêmes définitions que les filtres et découpages équivalents dans les tableaux de bord d'analyse.

Créer des valeurs conditionnelles

Vous ajoutez des conditions lorsque vous créez ou modifiez une configuration. À l'étape Ajouter un ciblage, ajoutez une condition :

1. Choisissez une condition existante ou cliquez sur Créer une nouvelle.
2. Ajoutez une ou plusieurs règles.
3. Définissez la valeur que les joueurs correspondants reçoivent.

Par exemple, pour donner une expérience plus difficile aux meilleurs payeurs actifs qui ont commencé à jouer dans les 30 derniers jours, vous pourriez augmenter leur valeur dynamicBossHealth.

Accéder aux valeurs ciblées dans le code

Pour récupérer les valeurs ciblées, utilisez ConfigService:GetConfigForPlayerAsync(), qui évalue les règles et l'ordre pour un joueur individuel. ConfigService:GetConfigAsync() ne s'applique pas au ciblage car il n'est pas spécifique à un seul joueur. Pour plus d'informations, voir Ajouter des configurations à votre code.

Meilleures pratiques et limites

• Chaque valeur conditionnelle doit correspondre au type de données (booléen, chaîne, nombre ou JSON) de la valeur par défaut de la configuration.
• Vous pouvez avoir jusqu'à 100 conditions par jeu.
• Chaque clé de configuration prend en charge jusqu'à 20 conditions.
• Vérifiez l'ordre des règles avant de publier. Étant donné que les règles sont ordonnées globalement, confirmez que votre ordre d'évaluation est correctement priorisé. Pour revoir l'ordre, cliquez sur l'onglet Conditions.

Créer et modifier des configurations dans Studio

Si vous le souhaitez, vous pouvez créer, modifier, mettre en attente 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 attente et tester de nouvelles valeurs.

Publier des configurations vers une autre expérience

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 des configurations d'une expérience de mise en attente ou de développement vers l'expérience en direct.

1. Dans Roblox Studio, allez dans le menu supérieur et sélectionnez Fichier > Ouvrir les configurations.

2. Dans l'onglet Publié du widget Configurations, cliquez sur l'icône ⋮ et sélectionnez Publier sous.

   

3. Dans la boîte de dialogue qui apparaît, trouvez et sélectionnez l'expérience cible dans la liste des groupes où vous avez des permissions d'édition.

   

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 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 attente la valeur "avant". Notez que restaurer une configuration annule toutes les modifications en attente 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 les scripts serveur. Tenter 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 pour les configurations globales que vous souhaitez appliquer à tous les joueurs dans l'expérience :

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

• ConfigService:GetConfigForPlayerAsync() récupère des configurations spécifiques au joueur afin que différents joueurs puissent obtenir des valeurs différentes. Utilisez-le pour les configurations conditionnelles et les expériences.

  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.

Autocomplétion

Les configurations sont intégrées dans l'autocomplétion de l'éditeur de script. Lorsque vous appelez ConfigSnapshot:GetValue(), l'éditeur suggère vos noms de clés de configuration et affiche le type de chaque configuration lorsque vous survolez le nom de la variable.

Si votre script utilise le mode --!strict, le linter peut détecter et vérifier le type pour vous.

L'autocomplétion fonctionne également avec des configurations qui utilisent des types JSON imbriqués complexes.

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 vouloir que les nouvelles valeurs de configuration n'arrivent qu'entre les rounds afin que les attributs des armes ne fluctuent pas en plein 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() lance 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 lorsqu'ils chargent avec succès de nouvelles mises à jour.

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

Tester des 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() depuis un script serveur ou via la Console de développement. Les modifications des valeurs de test déclenchent une mise à jour de la configuration ainsi que 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 pendant 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().