Configurações de Experiência

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

• Ative ou desative recursos, como habilitar ou desabilitar uma nova masmorra de introdução.
• Ajuste valores dentro 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.
• Dê valores diferentes a diferentes jogadores, como fornecer armaduras extras para jogadores mais novos.

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 alterações 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 de Creator Hub Configurações para sua experiência, clique em Criar configuração.

2. Especifique uma chave, um tipo, um valor e, opcionalmente, uma descrição para ajudar você ou sua equipe a identificar mais tarde o propósito da configuração. Os tipos suportados são string, número, booleano e objeto JSON. Clique em Próximo.

3. (Opcional) Adicione condições e valores de direcionamento. As condições permitem que você aplique valores de configuração a usuários que correspondem (ou não correspondem) a certos critérios, como usuários que nunca jogaram seu jogo ou aqueles que falam português. Para saber mais, veja Direcionar configurações para jogadores específicos.

4. Copie o trecho de código gerado para um script de servidor em sua experiência, provavelmente em ServerScriptService. Para configurações "globais" que não diferem por jogador, o código pode ser algo assim:

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

   Para configurações condicionais e experimentos, o código é ligeiramente diferente:

   local ConfigService = game:GetService("ConfigService")
   local Players = game:GetService("Players")
   local MY_KEY = "my_key" -- opcional, armazene a chave de configuração como uma constante
   
   local function onPlayerAdded(player)
       local playerConfigSnapshot = ConfigService:GetConfigForPlayerAsync(player)
       local myValue = playerConfigSnapshot:GetValue(MY_KEY)
   end
   
   Players.PlayerAdded:Connect(onPlayerAdded)

5. Use o valor como faria com qualquer outra variável. As configurações não fazem nada a menos que você as utilize dentro do 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 que se torne publicamente disponível. As alterações em estágio estão disponíveis para você e sua equipe em sessões de jogo no Studio, não para jogadores em experiências ao vivo. A página Configurações no Creator Hub mostra todas as alterações ativas e em estágio.

1. Depois de testar suas alterações em estágio, clique em Publicar agora para publicar para todos os jogadores quase instantaneamente (aproximadamente entre 15 segundos e 1 minuto). Você também pode escolher Publicar em 15 min se preferir um período de lançamento mais longo e gradual. Em alguns casos, os clientes podem levar alguns minutos para refletir as alterações após a publicação.
2. (Recomendado) Adicione uma mensagem de publicação descritiva que indique o que você atualizou. Esta mensagem aparece na página Histórico e pode ajudar você e sua equipe a identificar mais tarde o propósito da alteração.

Direcionar configurações para jogadores específicos

Por padrão, uma configuração entrega o mesmo valor a todos. Configurações condicionais permitem que você entregue valores diferentes a diferentes jogadores com base em atributos do jogador (país, tempo de jogo, idioma, status de pagador, etc.).

As configurações condicionais têm três partes que determinam qual valor um jogador recebe:

• Regras condicionais definem quem corresponde. Cada regra é uma expressão lógica, como "pagadores ativos em seus primeiros 30 dias", que avalia atributos do jogador.
• Ordenação de regras define como escolher quando um jogador corresponde a mais de uma regra. O Roblox avalia as regras de cima para baixo e aplica o primeiro ramo correspondente. As regras são ordenadas globalmente, independentemente da ordem em que você adiciona valores condicionais a uma chave individual.
• Valores condicionais definem o que um jogador correspondente recebe. Para cada condição, você anexa um valor. Se um jogador corresponder a uma regra dentro dessa condição, ele recebe o valor associado; caso contrário, ele recebe o valor padrão da configuração.

Atributos suportados

As configurações condicionais suportam os seguintes atributos. Esses atributos compartilham as mesmas definições que os filtros e quebras equivalentes nos painéis de análise.

Criar valores condicionais

Você adiciona condições ao criar ou editar uma configuração. Na etapa Adicionar direcionamento, adicione uma condição:

1. Escolha uma condição existente ou clique em Criar uma nova.
2. Adicione uma ou mais regras.
3. Defina o valor que os jogadores correspondentes recebem.

Por exemplo, para dar uma experiência mais difícil aos principais pagadores ativos que começaram a jogar nos últimos 30 dias, você pode aumentar o valor de dynamicBossHealth.

Acessar valores direcionados no código

Para recuperar valores direcionados, use ConfigService:GetConfigForPlayerAsync(), que avalia as regras e a ordenação para um jogador individual. ConfigService:GetConfigAsync() não aplica direcionamento porque não é específico para um único jogador. Para mais informações, veja Adicionar configurações ao seu código.

Melhores práticas e limites

• Cada valor condicional deve corresponder ao tipo de dado (booleano, string, número ou JSON) do valor padrão da configuração.
• Você pode ter até 100 condições por jogo.
• Cada chave de configuração suporta até 20 condições.
• Verifique a ordenação das regras antes de publicar. Como as regras são ordenadas globalmente, confirme se sua ordem de avaliação está priorizada corretamente. Para revisar a ordem, clique na aba Condições.

Criar e editar configurações no Studio

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

Publicar configurações em outra experiência

No Studio, você pode publicar suas configurações em outra experiência, o que sobrescreve completamente as configurações para essa experiência. Isso pode ser especialmente útil para sincronizar configurações de uma experiência de estágio ou desenvolvimento para a experiência ao vivo.

1. No Roblox Studio, vá ao menu superior e selecione Arquivo > Abrir Configurações.

2. Na aba Publicadas do widget de Configurações, clique no ícone ⋮ e selecione Publicar Como.

   

3. Na caixa de diálogo que aparece, encontre e selecione a experiência alvo na lista de grupos onde você tem permissões de edição.

   

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 a hora e a data da alteração, quem fez a alteração e a mensagem de publicação.

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

A página Histórico também permite que você restaure configurações a um estado anterior:

1. Clique em Restaurar ao lado da alteração para preparar o valor "antes". Observe que restaurar uma configuração descarta quaisquer alterações em estágio existentes.
2. Retorne à 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 últimas chaves e valores para sua experiência. ConfigService está disponível apenas para scripts de servidor. Tentar chamar seus métodos a partir de um script de cliente resulta em um erro.

O primeiro passo para trabalhar com configurações é recuperar um ConfigSnapshot, os últimos valores para todas as configurações no momento atual. 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() busca configurações específicas do jogador para que jogadores diferentes possam obter valores diferentes. Use-o para configurações condicionais e experimentos.

  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.

Autocompletar

As configurações estão integradas ao autocompletar do Editor de Scripts. Quando você chama ConfigSnapshot:GetValue(), o editor sugere os nomes das chaves de configuração e exibe o tipo de cada configuração quando você passa o mouse sobre o nome da variável.

Se seu script usar o modo --!strict, o linter pode detectar e verificar o tipo para você.

O autocompletar também funciona com configurações que usam tipos JSON complexos e aninhados.

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 de uma configuração não se propagam automaticamente para os snapshots. Em um jogo de tiro competitivo, por exemplo, você pode querer apenas novos valores de configuração entre as rodadas para que os atributos das armas não flutuem durante a partida.

Para obter os últimos valores 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)

Depois de atualizar um snapshot, você pode usar ConfigSnapshot:GetValueChangedSignal() para ouvir mudanças 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 em que 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() retorna um snapshot com os últimos valores disponíveis. Esses snapshots tentam se reconectar e disparam o evento UpdateAvailable quando conseguem carregar novas atualizações.

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 ao jogador e esperar que o snapshot se reconecte, ou alguma outra solução.

Testar configurações

ConfigService possui métodos integrados para testar temporariamente alterações 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. Alterações 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!

As alterações de teste se aplicam durante a vida útil 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 alterações de teste com ConfigService:ClearTestingValue().