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.

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 siempre que 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.

3. Copia el fragmento de código generado en un script del servidor en tu experiencia, probablemente en ServerScriptService. El código debería verse algo así:

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

4. 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 las 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.

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 icono ⋮ 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() es para experimentos. Obtiene configuraciones específicas del jugador para que diferentes jugadores puedan obtener diferentes valores.

  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, es posible que solo desees 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, utiliza 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 disparan 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().