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 tu juego. Todas las misiones deben tener un ID, una 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.

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

Crear misiones que introduzcan a nuevos jugadores en tu juego y mejoren la retención D1.
Apuntar a la retención D7 y D30 añadiendo objetivos a medio y largo plazo y un sentido de progresión.
Aumentar el compromiso al resaltar los diversos sistemas en tu juego y recompensar a los jugadores por interactuar con ellos.

Para obtener información sobre cómo proporcionar a los jugadores nuevos objetivos e incentivos para que estén motivados a jugar 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 que son creados por Roblox y la comunidad de Roblox para su uso dentro de 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 un juego abierto, ¡incluyendo paquetes de características!

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

Para obtener los paquetes de tu inventario en tu juego:

Agrega 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 almacenamiento de datos compartidos 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 juego.
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 la clasificación Mis Modelos.
Haz clic en el mosaico Paquete de Características Core, luego en el mosaico Paquete de Características de Misiones. Ambas carpetas de paquetes se muestran en la ventana Explorador.
Arrastra las carpetas de paquetes a ReplicatedStorage.

Definir misiones

Cada misión completable incluye un conjunto de tareas que deben finalizarse para completar la misión, opciones de configuración y metadatos de visualización opcionales, todos los cuales se pueden definir 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 propia cadena única.
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 usar 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 la misión pueda desbloquearse.
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 cumplirse.
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 completarse.
repeatLimit	number	Si la misión es repetible, no puede repetirse 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á en su lugar.
expireCountOffline	bool	Si la misión tiene expireSeconds y expireCountOffline está configurado en verdadero, el tiempo mientras el jugador no está realmente en el juego 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 sus metadatos.

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 o contexto adicional sobre la misión.
visibleAfterComplete	bool	Si se establece en verdadero, la misión aparecerá en la lista de misiones incluso después de completarse, 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 fallida.
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 completarse.
invisibleWhileActive	bool	Si se establece en verdadero, la misión será invisible incluso mientras está en progreso activo.
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 de 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 ícono.

Definir tareas

Cada misión puede tener cero o más tareas. Si una misión tiene cero tareas, se puede reclamar inmediatamente después de desbloquearse; si una misión tiene una o más tareas, una vez que las tareas estén completas, 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 permite iniciar y detener la tarea en diferentes momentos. Debe transcurrir una cierta cantidad de tiempo mientras el temporizador de la tarea está en funcionamiento, luego la tarea se completa.
Tareas de Conteo - Te permite agregar o establecer el progreso de la tarea. Cuando el progreso alcanza un valor establecido, la tarea se 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 temporizada.
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 recolectado un jugador, todas pueden compartir el mismo contador de “monedas”. Estas tareas pueden rastrear de forma independiente nuevas monedas recolectadas, comenzando desde cero, o continuar contando desde el valor del contador (todas las monedas ya recolectadas). counterId (string) - El ID del contador que se va 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 se debe mostrar 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 retorno de llamada. callback (function) - Función activada por el botón callToAction. buttonText (string) - El texto que se muestra en la interfaz 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 se 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 detienen. Cuando se cumple la cantidad objetivo de tiempo, la tarea se 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 que se inicie.
includesOfflineTime	bool	Si la tarea debe incluir el tiempo transcurrido mientras el jugador no está activamente en el juego.

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 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 repetición de categoría dada.

Integrar lógica del servidor

Echa un vistazo a 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 juego:

Define misiones en tu configuración de misiones.

Agrega lógica a tu juego 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 Saltando con una tarea de Saltos
Missions.addProgressToTask(player, "Saltando", "Saltos", 1)

-- Inicia el temporizador en una misión TiempoDeBatalla con una tarea de TiempoEnBatalla
Missions.startTimedTask(player, "TiempoDeBatalla", "TiempoEnBatalla")

-- Detiene el temporizador en una misión TiempoDeBatalla con una tarea de TiempoEnBatalla
Missions.stopTimedTask(player, "TiempoDeBatalla", "TiempoEnBatalla")

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

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

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

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

README

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

Missions.setCompletionHandler(missionId, completeHandler)

Desbloquea 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 sean coleccionables.
README
Missions.unlockMission(player, "Manual")

Configurar constantes

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

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

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

Personalizar componentes de la interfaz de usuario

Al modificar los objetos del paquete, como colores, fuentes y transparencia, puedes ajustar la presentación visual de la interfaz de usuario de tus 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 misiones que solo tienen una tarea.

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

Además, si tu juego 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 la información sobre las misiones de un jugador enviadas desde el servidor.

Paquete de Características Core

Paquete de Características de Misiones