Configuraciones de experiencia

Configuraciones de experiencia te permiten actualizar valores en el juego en tiempo real sin reiniciar servidores:

• Activar y desactivar funciones, como habilitar o deshabilitar una nueva mazmorras de introducción.
• Ajustar valores en el juego como la salud de los jefes, la ganancia de experiencia o los precios de los objetos.
• Lanzar contenido por tiempo limitado, como un evento de Halloween que comienza a medianoche.
• Dar diferentes valores a diferentes jugadores, como dar a los jugadores más nuevos armaduras adicionales.

Las configuraciones toman la forma de claves y valores. En lugar de usar constantes codificadas en tu código, puedes usar la clave para obtener un valor (cadena, número, booleano u objeto JSON) y luego actualizar ese valor cuando lo desees sin publicar una nueva versión de tu experiencia. Los cambios de código requeridos son mínimos:

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

Puedes tener hasta 1,000 configuraciones activas en cualquier momento y gestionarlas en Creator Hub o en Roblox Studio.

Crear y editar configuraciones

1. En la página de Creator Hub Configuraciones para tu experiencia, haz clic en Crear configuración.

2. Especifica una clave, un tipo, un valor y, opcionalmente, una descripción para ayudarte a ti o a tu equipo a identificar más tarde el propósito de la configuración. Los tipos admitidos son cadena, número, booleano y objeto JSON. Haz clic en Siguiente.

3. (Opcional) Agrega condiciones y valores de segmentación. Las condiciones te permiten aplicar valores de configuración a usuarios que coincidan (o no coincidan) con ciertos criterios, como usuarios que nunca han jugado tu juego o aquellos que hablan portugués. Para obtener más información, consulta Dirigir configuraciones a jugadores específicos.

4. Copia el fragmento de código generado en un script del servidor en tu experiencia, probablemente en ServerScriptService. Para configuraciones "globales" que no difieren por jugador, el código podría verse algo así:

   local ConfigService = game:GetService("ConfigService")
   
   local configSnapshot = ConfigService:GetConfigAsync()
   local MY_KEY = "my_key" -- opcional, almacenar la clave de configuración como una constante
   local myValue = configSnapshot:GetValue(MY_KEY)

   Para configuraciones condicionales y experimentos, el código es ligeramente diferente:

   local ConfigService = game:GetService("ConfigService")
   local Players = game:GetService("Players")
   local MY_KEY = "my_key" -- opcional, almacenar la clave de configuración como una constante
   
   local function onPlayerAdded(player)
       local playerConfigSnapshot = ConfigService:GetConfigForPlayerAsync(player)
       local myValue = playerConfigSnapshot:GetValue(MY_KEY)
   end
   
   Players.PlayerAdded:Connect(onPlayerAdded)

5. Usa el valor como lo harías con cualquier otra variable. Las configuraciones no hacen nada a menos que las uses dentro de tu código.

Para obtener más información sobre cómo trabajar con configuraciones en tus scripts, consulta Agregar configuraciones a tu código.

Editar una configuración no es diferente de crear una. Haz clic en el botón Editar y actualiza el valor y la descripción según desees.

Límites

Los valores de configuración tienen los siguientes límites por tipo.

Publicar configuraciones

Después de crear una configuración, se mueve a un estado en etapa para que puedas probarla antes de que esté disponible públicamente. Los cambios en etapa están disponibles para ti y tu equipo en sesiones de juego de Studio, no para los jugadores en experiencias en vivo. La página de Configuraciones en Creator Hub muestra todos los cambios activos y en etapa.

1. Después de probar tus cambios en etapa, haz clic en Publicar ahora para publicar a todos los jugadores casi instantáneamente (aproximadamente entre 15 segundos y 1 minuto). También puedes elegir Publicar en 15 min si prefieres un período de lanzamiento más largo y gradual. En algunos casos, los clientes pueden tardar unos minutos en reflejar los cambios después de la publicación.
2. (Recomendado) Agrega un mensaje de publicación descriptivo que indique lo que actualizaste. Este mensaje aparece en la página de Historial y puede ayudarte a ti y a tu equipo a identificar más tarde el propósito del cambio.

Dirigir configuraciones a jugadores específicos

Por defecto, una configuración entrega el mismo valor a todos. Las configuraciones condicionales te permiten entregar diferentes valores a diferentes jugadores según los atributos del jugador (país, antigüedad, idioma, estado de pago, etc.).

Las configuraciones condicionales tienen tres partes que determinan qué valor recibe un jugador:

• Reglas condicionales definen quién coincide. Cada regla es una expresión lógica, como "pagadores activos en sus primeros 30 días", que evalúa los atributos del jugador.
• Orden de las reglas define cómo elegir cuando un jugador coincide con más de una regla. Roblox evalúa las reglas de arriba hacia abajo y aplica la primera rama coincidente. Las reglas están ordenadas globalmente, independientemente del orden en que agregues valores condicionales a una clave individual.
• Valores condicionales definen lo que recibe un jugador coincidente. Para cada condición, adjuntas un valor. Si un jugador coincide con una regla dentro de esa condición, recibe el valor asociado; de lo contrario, recibe el valor predeterminado de la configuración.

Atributos admitidos

Las configuraciones condicionales admiten los siguientes atributos. Estos atributos comparten las mismas definiciones que los filtros y desglose equivalentes en los paneles de análisis.

Crear valores condicionales

Agregas condiciones cuando creas o editas una configuración. En el paso de Agregar segmentación, agrega una condición:

1. Elige una condición existente o haz clic en Crear una nueva.
2. Agrega una o más reglas.
3. Establece el valor que reciben los jugadores coincidentes.

Por ejemplo, para dar una experiencia más difícil a los principales pagadores activos que comenzaron a jugar en los últimos 30 días, podrías aumentar su valor de dynamicBossHealth.

Acceder a valores dirigidos en el código

Para recuperar valores dirigidos, usa ConfigService:GetConfigForPlayerAsync(), que evalúa las reglas y el orden para un jugador individual. ConfigService:GetConfigAsync() no aplica segmentación porque no es específico para un solo jugador. Para obtener más información, consulta Agregar configuraciones a tu código.

Mejores prácticas y límites

• Cada valor condicional debe coincidir con el tipo de datos (booleano, cadena, número o JSON) del valor predeterminado de la configuración.
• Puedes tener hasta 100 condiciones por juego.
• Cada clave de configuración admite hasta 20 condiciones.
• Verifica el orden de las reglas antes de publicar. Dado que las reglas están ordenadas globalmente, confirma que tu orden de evaluación esté priorizado correctamente. Para revisar el orden, haz clic en la pestaña Condiciones.

Crear y editar configuraciones en Studio

Si lo prefieres, puedes crear, editar, poner en etapa y publicar configuraciones en Roblox Studio. Haz clic en Archivo > Abrir Configuraciones para abrir el widget. La interfaz de Studio es particularmente conveniente para poner en etapa y probar nuevos valores.

Publicar configuraciones en otra experiencia

En Studio, puedes publicar tus configuraciones en otra experiencia, lo que sobrescribe completamente las configuraciones para esa experiencia. Esto puede ser especialmente útil para sincronizar configuraciones de una experiencia de etapa o desarrollo a la experiencia en vivo.

1. En Roblox Studio, ve al menú superior y selecciona Archivo > Abrir Configuraciones.

2. En la pestaña Publicadas del widget de Configuraciones, haz clic en el ícono ⋮ y selecciona Publicar como.

   

3. En el cuadro de diálogo que aparece, busca y selecciona la experiencia objetivo de la lista de grupos donde tienes permisos de edición.

   

Ver historial y restaurar configuraciones

En la página de Configuraciones, haz clic en Historial para ver actualizaciones pasadas. Cada actualización tiene la hora y la fecha del cambio, quién realizó el cambio y el mensaje de publicación.

• Expande cada fila para ver la clave, el valor antes del cambio y el valor después de este.
• Usa el cuadro Buscar clave para buscar claves, no descripciones o valores, solo claves.

La página de Historial también te permite restaurar configuraciones a un estado anterior:

1. Haz clic en Restaurar junto al cambio para poner en etapa el valor "anterior". Ten en cuenta que restaurar una configuración descarta cualquier cambio en etapa existente.
2. Regresa a la página de Configuraciones y publica la configuración.

Agregar configuraciones a tu código

La clase principal para trabajar con configuraciones es ConfigService, que obtiene las últimas claves y valores para tu experiencia. ConfigService solo está disponible para scripts del servidor. Intentar llamar a sus métodos desde un script del cliente resulta en un error.

El primer paso para trabajar con configuraciones es recuperar un ConfigSnapshot, los últimos valores para todas las configuraciones en el momento actual. Hay dos métodos para obtener un snapshot:

• ConfigService:GetConfigAsync() es para configuraciones globales que deseas aplicar a todos los jugadores en la experiencia:

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

• ConfigService:GetConfigForPlayerAsync() obtiene configuraciones específicas del jugador para que diferentes jugadores puedan obtener diferentes valores. Úsalo para configuraciones condicionales y 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)

En cualquier caso, si la clave no existe, ConfigSnapshot:GetValue() devuelve nil.

Autocompletar

Las configuraciones están integradas en la función de autocompletar del Editor de Scripts. Cuando llamas a ConfigSnapshot:GetValue(), el editor sugiere los nombres de tus claves de configuración y muestra el tipo de cada configuración cuando pasas el cursor sobre el nombre de la variable.

Si tu script utiliza el modo --!strict, el linter puede detectar y verificar el tipo por ti.

La autocompletar también funciona con configuraciones que utilizan tipos JSON anidados complejos.

Actualizar snapshots

ConfigSnapshots representan un punto en el tiempo, el estado de la configuración cuando solicitaste el snapshot. Para evitar interrumpir la jugabilidad, las actualizaciones a una configuración no se propagan automáticamente a los snapshots. En un shooter competitivo, por ejemplo, solo podrías querer nuevos valores de configuración entre rondas para que los atributos de las armas no fluctúen en medio de la partida.

Para obtener los últimos valores manualmente, usa el método ConfigSnapshot:Refresh(). Opcionalmente, conecta una función al evento ConfigSnapshot.UpdateAvailable para actualizar automáticamente:

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

Después de actualizar un snapshot, puedes usar ConfigSnapshot:GetValueChangedSignal() para escuchar cambios en una clave específica para que puedas actualizar el código de tu experiencia:

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

Manejo de errores

En raras ocasiones, cuando la configuración no se carga y nunca se ha cargado antes, ConfigService:GetConfigAsync() lanza un error.

Si ConfigService pierde la conexión con los servidores de Roblox después de haber sido cargado previamente, ConfigService:GetConfigAsync() devuelve un snapshot con los últimos valores disponibles. Estos snapshots intentan reconectarse y activan el evento UpdateAvailable cuando cargan nuevas actualizaciones con éxito.

Cómo manejes estas situaciones poco comunes depende de ti. Puedes envolver la llamada en un pcall() y tener valores de respaldo en tu código, mostrar un error al jugador y esperar a que el snapshot se reconecte, o alguna otra solución.

Probar configuraciones

ConfigService tiene métodos integrados para probar temporalmente cambios en la configuración tanto en Studio como en servidores en vivo sin afectar toda la experiencia.

Para establecer un valor de prueba local, llama a ConfigService:SetTestingValue() desde un script del servidor o a través de la Consola del Desarrollador. Los cambios en los valores de prueba desencadenan una actualización de configuración junto con la señal ConfigSnapshot.UpdateAvailable. Al igual que una actualización de producción, debes actualizar los snapshots existentes para obtener el valor de prueba:

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

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

Los cambios de prueba se aplican durante la vida útil del servidor actual y no se propagan a otros servidores. En Studio, se aplican a la sesión de juego actual y no afectan a los servidores en vivo. Puedes borrar manualmente los cambios de prueba con ConfigService:ClearTestingValue().