Paquete de Misiones

Este paquete de características está en beta.

El paquete de características de Misiones ofrece funcionalidad lista para usar para crear misiones que los jugadores pueden completar para obtener recompensas y progresar en su experiencia. Todas las misiones deben tener un ID, categoría y una lista de tareas que los jugadores deben completar para finalizar la misión. Sin embargo, la lista de tareas puede estar vacía, lo que permite que las recompensas de la misión se reclamen de inmediato.

Usando las opciones de personalización del paquete, puedes personalizar todas las misiones para cumplir con tus requisitos únicos de juego, tales como:

Crear misiones que integren a nuevos jugadores en tu experiencia y mejoren la retención D1.
Apuntar a la retención D7 y D30 al añadir objetivos a medio y largo plazo y un sentido de progreso.
Aumentar el compromiso al hacer visibles los diferentes sistemas en tu juego y recompensar a los jugadores por interactuar con ellos.

Para obtener información sobre cómo proporcionar a los jugadores objetivos e incentivos frescos para que se sientan motivados a jugar por más tiempo y aumentar su compromiso, consulta Introducción al Diseño de Misiones.

Obtener paquete

La Tienda de Creadores es una pestaña de la Caja de Herramientas que puedes usar para encontrar todos los activos creados por Roblox y la comunidad de Roblox para usar en tus proyectos, incluyendo modelos, imágenes, mallas, audio, complementos, videos y activos de fuentes. Puedes usar la Tienda de Creadores para agregar uno o más activos directamente en una experiencia abierta, ¡incluidos los paquetes de características!

Cada paquete de características requiere el paquete de características Core para funcionar correctamente. Una vez que los activos del paquete de características Core y Misiones estén en tu inventario, podrás reutilizarlos en cualquier proyecto en la plataforma.

Para llevar los paquetes de tu inventario a tu experiencia:

Agrega el Core y Misiones a tu inventario dentro de Studio haciendo clic en el enlace Agregar al Inventario en el siguiente conjunto de componentes.

Paquete de Características Core
El paquete de características Core ofrece lógica de tienda de datos compartida para todos los paquetes de características.
Paquete de Características de Misiones
El Paquete de Características de Misiones ofrece funcionalidad para crear misiones que los jugadores pueden completar para obtener recompensas y progresar en tu experiencia.
Desde el menú Ventana de Studio o la barra de herramientas de la pestaña Inicio, abre la Caja de Herramientas.
En la ventana de la Caja de Herramientas, haz clic en la pestaña Inventario. Se muestra el orden Mis Modelos.
Haz clic en el mosaico Paquete de Características Core, luego en el mosaico Paquete de Características de Misiones. Ambos carpetas de paquetes se mostrarán en la ventana de Explorador.
Arrastra las carpetas de paquetes a ReplicatedStorage.

Definir misiones

Cada misión completable incluye un conjunto de tareas que deben completarse para finalizar la misión, opciones de configuración y metadatos de visualización opcionales, todo lo cual puede definirse dentro de ReplicatedStorage.Missions.Configs.Missions, con tipos exportados desde el script Types en la misma carpeta.

Campos requeridos

Los siguientes campos son obligatorios para cada misión.

Nombre	Tipo	Descripción
missionId	string	La clave principal de la tabla de Misiones. Todas las misiones se identifican por su propio string único.
categoryId	string	Las misiones deben pertenecer a una categoría, y se agrupan por categoría en la interfaz de usuario.
tasks	table	Una lista de tareas que el jugador debe finalizar para completar la misión.

Condiciones de desbloqueo

Por defecto, las misiones se desbloquean automáticamente para los jugadores y se pueden completar exactamente una vez. Sin embargo, puedes utilizar las siguientes opciones de configuración opcionales para alterar este comportamiento.

Nombre	Tipo	Descripción
prerequisites	table	Una lista de otros missionIds que deben completarse antes de que se pueda desbloquear la misión.
manualOnly	bool	Desactiva el desbloqueo automático de la misión. En su lugar, se debe llamar a una función para desbloquear la misión. Cualquier otra condición de desbloqueo también debe ser cumplida.
availableAfterUtc	bool	La misión no puede desbloquearse antes de la hora especificada en UTC.
availableBeforeUtc	bool	La misión no puede desbloquearse después de la hora especificada en UTC. Si se desbloquea pero no se completa antes de esta hora, la misión fallará.
repeatable	bool	La misión se desbloquea nuevamente después de completarla.
repeatLimit	number	Si la misión es repetible, no se puede repetir más de esta cantidad de veces.
repeatCooldownSeconds	number	Si la misión es repetible, hay un retraso antes de que se desbloquee.
expireSeconds	number	Si la misión está desbloqueada y no se completa dentro del número especificado de segundos, entonces fallará.
expireCountOffline	bool	Si la misión tiene expireSeconds y expireCountOffline está configurado como verdadero, el tiempo mientras el jugador no esté en la experiencia contará para la expiración de la misión.

Metadatos

Las misiones tienen metadatos que especifican cómo se mostrarán en la interfaz de usuario de Misiones. Puedes usar los siguientes campos opcionales para personalizar su metadato.

Nombre	Tipo	Descripción
displayName	string	Un nombre para mostrar para la misión en la interfaz de usuario en lugar del missionId.
description	string	Un bloque de texto más largo que proporciona información adicional o contexto sobre la misión.
visibleAfterComplete	bool	Si se establece en verdadero, la misión aparecerá en la lista de misiones incluso después de completarla, pero marcada como completada.
visibleAfterFailed	bool	Si se establece en verdadero, la misión aparecerá en la lista de misiones incluso después de fallar, pero marcada como fallada.
visibleBeforeUnlocked	bool	Si se establece en verdadero, la misión será visible pero estará bloqueada en la lista de misiones antes de estar disponible para completar.
invisibleWhileActive	bool	Si se establece en verdadero, la misión será invisible incluso mientras esté en progreso activamente.
rewards	table	Una lista de información de visualización de recompensas. assetID (number) - El ID de la imagen que se muestra en la interfaz de usuario de misiones bajo las recompensas para una misión. Esto es obligatorio si hay una recompensa presente. displayName (string) - El nombre que se muestra en la interfaz de usuario de misiones bajo el icono.

Definir tareas

Cada misión puede tener cero o más tareas. Si una misión no tiene tareas, se puede reclamar inmediatamente después de que se desbloquee; si una misión tiene una o más tareas, una vez que se completen las tareas, el jugador puede recoger cualquier recompensa asociada con la misión. Cada tarea tiene un taskId, que es la clave asociada con la tarea para una misión dada.

Las tareas vienen en dos tipos:

Tareas Temporizadas - Te permiten iniciar y detener la tarea en diferentes momentos. Debe transcurrir un cierto tiempo mientras el temporizador de la tarea está corriendo, luego la tarea está completa.
Tareas de Conteo - Te permiten añadir o establecer el progreso de la tarea. Cuando el progreso alcanza un valor establecido, la tarea está completa.

Ambos tipos de tareas comparten los siguientes campos:

Nombre	Tipo	Descripción
taskType	string	Especifica si el tipo de tarea es de conteo o temporizado.
counter	object	(Opcional) El contador que esta tarea rastrea. Los contadores son almacenamiento persistente específico del jugador para un número o un temporizador. Varias tareas pueden rastrear un solo contador; por ejemplo, si más de una tarea rastrea cuántas monedas ha recogido un jugador, todas pueden compartir el mismo contador de "monedas". Estas tareas pueden rastrear independientemente las nuevas monedas recogidas, comenzando desde cero, o continuar contando desde el valor del contador (todas las monedas ya recogidas). counterId (string) - El ID del contador a rastrear. Usa este ID para obtener o establecer el valor del contador. continueFromCounter (Opcional bool) - Si se establece en verdadero, el progreso de la tarea coincidirá directamente con el valor del contador en lugar de la cantidad que ha aumentado.
metadata	object	(Opcional) Información sobre cómo se muestra la tarea en la interfaz de usuario. displayName (string) - Nombre de la tarea, utilizado cuando se muestra en la interfaz de usuario. numericType (Opcional string) - cómo debe mostrarse el número de progreso en la tarea. Fracción, ej. 5/10 o 5k/50k Porcentaje, ej. 50% o 10% FracciónLarga, ej. 5/10 o 5000/50000 Booleano, ej. Incompleto
callToAction	object	(Opcional) Un botón que activa una función de retroalimentación. callback (function) - Función activada por el botón callToAction. buttonText (string) - El texto que se muestra en la interfaz de usuario del botón.

Campos de tareas de conteo

Las tareas de conteo tienen un valor requerido. Cuando el progreso de la tarea cumple con esta cantidad, la tarea está completa.

Nombre	Tipo	Descripción
goalCount	number	(Opcional) El progreso requerido para completar la tarea.

Campos de tareas temporizadas

Las tareas temporizadas tienen una cantidad objetivo de tiempo transcurrido, y se inician y se detienen. Cuando se cumple la cantidad objetivo de tiempo, la tarea está completa.

Nombre	Tipo	Descripción
goalSeconds	number	El número de segundos que deben transcurrir para completar la tarea.
startImmediately	bool	Si la tarea debe comenzar a contar el tiempo tan pronto como se desbloquee, en lugar de solo después de iniciarse.
includesOfflineTime	bool	Si la tarea debe incluir el tiempo transcurrido mientras el jugador no está activamente en la experiencia.

Configurar categorías

Las categorías no tienen que definirse explícitamente para ser utilizadas, ya que la categoría de una misión tiene valores predeterminados que se utilizarán. Sin embargo, puedes configurar estos valores en ReplicatedStorage.Missions.Configs.Categories para agregar efectos adicionales a la categoría. Las categorías se identifican por CategoryIds únicos, los mismos que se mencionan en la configuración de las misiones.

Nombre	Tipo	Descripción
repeatDelaySeconds	number	(Opcional) Si se establece, todas las misiones en la categoría se restablecen cada vez que transcurre la cantidad de tiempo especificada, y pueden desbloquearse, completarse y sus recompensas reclamarse nuevamente. Esto es independiente de las misiones repetibles, que son repetibles dentro de un reinicio de categoría dado.

Integrar lógica del servidor

Revisa ReplicatedStorage.Missions.Server.Examples.MissionsExample, que muestra cómo tu servidor interactuará con el paquete de características Misiones.

Principalmente necesitas conectar cuatro cosas una vez que arrastres el paquete de características Misiones a tu experiencia:

Define las misiones en la configuración de misiones.

Agrega lógica a tu experiencia para actualizar el progreso de las tareas o los contadores a los que está vinculado el progreso.

README
-- Aumenta el progreso en una misión Jumping con una tarea Jumps
Missions.addProgressToTask(player, "Jumping", "Jumps", 1)

-- Inicia el temporizador en una misión BattlingTime con una tarea TimeInBattle
Missions.startTimedTask(player, "BattlingTime", "TimeInBattle")

-- Detiene el temporizador en una misión BattlingTime con una tarea TimeInBattle
Missions.stopTimedTask(player, "BattlingTime", "TimeInBattle")

-- Aumenta el progreso en todas las tareas vinculadas al contador Jumps
CounterSystem.addCounter(player, "Jumps", 1)

-- Inicia el temporizador en todas las tareas temporizadas vinculadas al contador TimeInBattle
CounterSystem.startTimer(player, "TimeInBattle")

-- Detiene el temporizador en todas las tareas temporizadas vinculadas al contador TimeInBattle
CounterSystem.stopTimer(player, "TimeInBattle")

Establece los controladores de finalización de misión y, opcionalmente, los controladores de desbloqueo o fallo. Usa el controlador de finalización para otorgar las recompensas de la misión en tu experiencia.

README
local function completeHandler(player: Player, missionId: Types.MissionId)
     print(`{player} completó la misión {missionId}`)
     -- Otorgar al jugador sus recompensas.
 end

Missions.setCompletionHandler(missionId, completeHandler)

Desbloquea las misiones que no se desbloquean automáticamente. La lógica del paquete de características Misiones asegura que se cumplan todos los requisitos de la misión antes de que la misión esté completa, y sus recompensas se puedan recoger.
```
README
Missions.unlockMission(player, "Manual")
```

Configurar constantes

Las constantes para el paquete de características Core viven en dos lugares:

Las constantes compartidas se encuentran en ReplicatedStorage.FeaturePackagesCore.Configs.SharedConstants.
Las constantes específicas del paquete, en este caso el paquete de características Misiones, se encuentran en ReplicatedStorage.Missions.Configs.Constants.

Además, puedes encontrar cadenas para traducción separadas en un solo lugar: ReplicatedStorage.FeaturePackagesCore.Configs.TranslationStrings.

Personalizar componentes de UI

Al modificar los objetos del paquete, como colores, fuente y transparencia, puedes ajustar la presentación visual de tu interfaz de usuario de misiones. Por ejemplo, en ReplicatedStorage.Missions.Configs.Constants, puedes habilitar SingleTaskMode para mostrar una barra de progreso para una tarea directamente en la misión misma para las misiones que solo tienen una tarea única.

Si mueves cualquiera de los objetos jerárquicamente, el código no podrá encontrarlos, y deberás hacer ajustes en MissionsUI.

Además, si tu experiencia ya tiene una interfaz de usuario existente que te gustaría integrar con el paquete de características Misiones, el ModuleScript del cliente MissionsClient contiene todas las funciones necesarias para obtener información sobre las misiones de un jugador enviada desde el servidor.

Paquete de Características Core

Paquete de Características de Misiones