Configurações de experiência

Configurações de experiência permitem que você atualize valores do jogo em tempo real sem reiniciar servidores:

• Ative ou desative recursos, como habilitar ou desabilitar um novo masmorra de integração.
• Ajuste valores do jogo, como saúde de chefes, ganho de experiência ou preços de itens.
• Lance conteúdo temporizado, como um evento de Halloween que começa à meia-noite.

As configurações assumem a forma de chaves e valores. Em vez de usar constantes codificadas em seu código, você pode usar a chave para obter um valor (string, número, booleano ou objeto JSON) e, em seguida, atualizar esse valor sempre que desejar, sem publicar uma nova versão de sua experiência. As mudanças de código necessárias são mínimas:

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

Você pode ter até 1.000 configurações ativas a qualquer momento e gerenciá-las no Creator Hub ou no Roblox Studio.

Criar e editar configurações

1. Na página Configurações do Creator Hub para sua experiência, clique em Criar configuração.

2. Especifique uma chave, um tipo, um valor e, opcionalmente, uma descrição para ajudá-lo ou sua equipe a identificar o propósito da configuração mais tarde. Os tipos suportados são string, número, booleano e objeto JSON.

3. Copie o trecho de código gerado para um script de servidor em sua experiência, provavelmente em ServerScriptService. O código deve parecer com algo assim:

   local ConfigService = game:GetService("ConfigService")
   
   local configSnapshot = ConfigService:GetConfigAsync()
   local MY_KEY = "my_key" -- opcional, armazene a chave da configuração como uma constante
   local myValue = configSnapshot:GetValue(MY_KEY)

4. Use o valor como faria com qualquer outra variável. As configurações não fazem nada a menos que você as utilize dentro de seu código.

Para mais informações sobre como trabalhar com configurações em seus scripts, veja Adicionar configurações ao seu código.

Editar uma configuração não é diferente de criar uma. Clique no botão Editar e atualize o valor e a descrição conforme desejado.

Limites

Os valores de configuração têm os seguintes limites por tipo.

Publicar configurações

Depois de criar uma configuração, ela se move para um estado em estágio para que você possa testá-la antes de se tornar publicamente disponível. As mudanças em estágio estão disponíveis para você e sua equipe nas sessões de jogo do Studio, mas não para jogadores em experiências ao vivo. A página Configurações no Creator Hub mostra todas as mudanças ativas e em estágio.

1. Depois de testar suas mudanças em estágio, clique em Publicar agora para publicar para todos os jogadores dentro de cinco minutos. Você também pode escolher Publicar ao longo de 15 min se preferir um período de rollout mais longo.
2. (Recomendado) Adicione uma mensagem de publicação descritiva que indique o que você atualizou. Essa mensagem aparece na página Histórico e pode ajudar você e sua equipe a identificar o propósito da mudança posteriormente.

Criar e editar configurações no Studio

Se preferir, você pode criar, editar, colocar em estágio e publicar configurações no Roblox Studio. Clique em Arquivo > Abrir Configurações. A interface do Studio é particularmente conveniente para colocar em estágio e testar novos valores.

Ver histórico e restaurar configurações

Na página Configurações, clique em Histórico para ver atualizações passadas. Cada atualização tem o horário e a data da mudança, quem fez a mudança e a mensagem de publicação.

• Expanda cada linha para ver a chave, o valor antes da mudança e o valor depois dela.
• Use a caixa Buscar Chave para pesquisar chaves — não descrições ou valores, apenas chaves.

A página Histórico também permite restaurar configurações para um estado anterior:

1. Clique em Restaurar ao lado da mudança para colocar em estágio o valor "antes". Observe que restaurar uma configuração descarta quaisquer mudanças em estágio existentes.
2. Volte para a página Configurações e publique a configuração.

Adicionar configurações ao seu código

A classe principal para trabalhar com configurações é ConfigService, que busca as chaves e valores mais recentes para sua experiência. O ConfigService só está disponível para scripts de servidor. Tentar chamar seus métodos a partir de um script de cliente resultará em um erro.

O primeiro passo para trabalhar com configurações é recuperar um ConfigSnapshot, os valores mais recentes para todas as configurações no ponto atual no tempo. Existem dois métodos para obter um snapshot:

• ConfigService:GetConfigAsync() é para configurações globais que você deseja aplicar a todos os jogadores na experiência:

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

• ConfigService:GetConfigForPlayerAsync() é para experimentos. Ele busca configurações específicas do jogador para que jogadores diferentes possam receber valores diferentes.

  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)

Em qualquer um dos casos, se a chave não existir, ConfigSnapshot:GetValue() retorna nil.

Atualizar snapshots

ConfigSnapshots representam um ponto no tempo, o estado da configuração quando você solicitou o snapshot. Para evitar interromper a jogabilidade, as atualizações para uma configuração não se propagam automaticamente para snapshots. Em um jogo de tiro competitivo, por exemplo, você pode desejar apenas novos valores de configuração entre as rodadas para que os atributos das armas não flutuem durante a partida.

Para obter os valores mais recentes manualmente, use o método ConfigSnapshot:Refresh(). Opcionalmente, conecte uma função ao evento ConfigSnapshot.UpdateAvailable para atualizar automaticamente:

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

Após atualizar um snapshot, você pode usar ConfigSnapshot:GetValueChangedSignal() para escutar alterações em uma chave específica para que você possa atualizar o código de sua experiência:

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

Tratamento de erros

Em casos raros, quando a configuração falha ao carregar e nunca foi carregada antes, ConfigService:GetConfigAsync() lança um erro.

Se ConfigService perder a conexão com os servidores Roblox após ter sido carregado anteriormente, ConfigService:GetConfigAsync() retornará um snapshot com os valores mais recentes disponíveis. Esses snapshots tentam se reconectar e disparam o evento UpdateAvailable quando carregam novas atualizações com sucesso.

Como você lida com essas situações incomuns depende de você. Você pode envolver a chamada em um pcall() e ter valores de fallback em seu código, mostrar um erro para o jogador e aguardar o snapshot se reconectar, ou alguma outra solução.

Testar configurações

ConfigService possui métodos integrados para testar temporariamente mudanças de configuração tanto no Studio quanto em servidores ao vivo, sem impactar toda a experiência.

Para definir um valor de teste local, chame ConfigService:SetTestingValue() a partir de um script de servidor ou através do Console do Desenvolvedor. As mudanças nos valores de teste acionam uma atualização de configuração junto com o sinal ConfigSnapshot.UpdateAvailable. Assim como uma atualização de produção, você deve atualizar os snapshots existentes para obter o valor de teste:

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

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

Mudanças de teste se aplicam durante a duração do servidor atual e não se propagam para outros servidores. No Studio, elas se aplicam à sessão de jogo atual e não afetam servidores ao vivo. Você pode limpar manualmente as mudanças de teste com ConfigService:ClearTestingValue().