Package de missions

Ce package de fonctionnalités est en version bêta.

Le package de fonctionnalités Missions offre une fonctionnalité prête à l'emploi pour créer des missions que les joueurs peuvent accomplir pour obtenir des récompenses et progresser dans votre jeu. Toutes les missions doivent avoir un ID, une catégorie et une liste de tâches que les joueurs doivent accomplir pour terminer la mission. Cependant, la liste des tâches peut être vide, permettant aux récompenses de la mission d'être réclamées immédiatement.

En utilisant les options de personnalisation du package, vous pouvez personnaliser toutes les missions pour répondre à vos exigences de gameplay uniques, telles que :

Créer des missions qui intègrent de nouveaux joueurs dans votre jeu et améliorent la rétention D1.
Cibler la rétention D7 et D30 en ajoutant des objectifs à moyen et long terme et un sens de progression.
Augmenter l'engagement en mettant en avant les différents systèmes de votre jeu et en récompensant les joueurs pour leur interaction avec eux.

Pour des informations sur la façon de fournir aux joueurs de nouveaux objectifs et incitations afin qu'ils soient motivés à jouer plus longtemps et à augmenter leur engagement, consultez Introduction à la conception de quêtes.

Obtenir le package

Le Creator Store est un onglet de la Toolbox que vous pouvez utiliser pour trouver tous les actifs créés par Roblox et la communauté Roblox pour une utilisation dans vos projets, y compris des modèles, des images, des maillages, des audio, des plugins, des vidéos et des polices. Vous pouvez utiliser le Creator Store pour ajouter un ou plusieurs actifs directement dans un jeu ouvert, y compris des packages de fonctionnalités !

Chaque package de fonctionnalités nécessite le package de fonctionnalités Core pour fonctionner correctement. Une fois les actifs des packages de fonctionnalités Core et Missions dans votre inventaire, vous pouvez les réutiliser dans n'importe quel projet sur la plateforme.

Pour obtenir les packages de votre inventaire dans votre jeu :

Ajoutez le Core et les Missions à votre inventaire dans Studio en cliquant sur le lien Ajouter à l'inventaire dans le jeu de composants suivant.

Package de fonctionnalités Core
Le package de fonctionnalités Core offre une logique de stockage de données partagées pour tous les packages de fonctionnalités.
Package de fonctionnalités Missions
Le package de fonctionnalités Missions offre une fonctionnalité pour créer des missions que les joueurs peuvent accomplir pour obtenir des récompenses et progresser dans votre jeu.
Dans le menu Fenêtre de Studio ou la barre d'outils de l'onglet Accueil, ouvrez la Toolbox.
Dans la fenêtre Toolbox, cliquez sur l'onglet Inventaire. Le tri Mes modèles s'affiche.
Cliquez sur le carreau Package de fonctionnalités Core, puis sur le carreau Package de fonctionnalités Missions. Les deux dossiers de package s'affichent dans la fenêtre Explorer.
Faites glisser les dossiers de package dans ReplicatedStorage.

Définir des missions

Chaque mission réalisable comprend un ensemble de tâches qui doivent être terminées pour compléter la mission, des options de configuration et des métadonnées d'affichage optionnelles, le tout pouvant être défini dans ReplicatedStorage.Missions.Configs.Missions, avec des types exportés depuis le script Types dans le même dossier.

Champs requis

Les champs suivants sont requis pour chaque mission.

Nom	Type	Description
missionId	string	La clé principale de la table Missions. Toutes les missions sont identifiées par leur propre chaîne unique.
categoryId	string	Les missions doivent appartenir à une catégorie et sont regroupées par catégorie dans l'interface utilisateur.
tasks	table	Une liste de tâches que le joueur doit terminer pour compléter la mission.

Conditions de déblocage

Par défaut, les missions sont déverrouillées pour les joueurs automatiquement et peuvent être complétées exactement une fois. Cependant, vous pouvez utiliser les options de configuration optionnelles suivantes pour modifier ce comportement.

Nom	Type	Description
prerequisites	table	Une liste d'autres missionIds qui doivent être complétées avant que la mission puisse être déverrouillée.
manualOnly	bool	Désactive le déverrouillage automatique de la mission. Au lieu de cela, une fonction doit être appelée pour déverrouiller la mission. Toutes les autres conditions de déverrouillage doivent également être remplies.
availableAfterUtc	bool	La mission ne peut pas être déverrouillée avant l'heure spécifiée en UTC.
availableBeforeUtc	bool	La mission ne peut pas être déverrouillée après l'heure spécifiée en UTC. Si elle est déverrouillée mais non complétée avant cette heure, la mission échouera.
repeatable	bool	La mission devient déverrouillée à nouveau après avoir été complétée.
repeatLimit	number	Si la mission est répétable, elle ne peut pas être répétée plus de ce nombre de fois.
repeatCooldownSeconds	number	Si la mission est répétable, il y a un délai avant qu'elle ne devienne déverrouillée.
expireSeconds	number	Si la mission est déverrouillée et non complétée dans le nombre de secondes spécifié, elle échouera à la place.
expireCountOffline	bool	Si la mission a expireSeconds et que expireCountOffline est défini sur vrai, le temps pendant lequel le joueur n'est pas réellement dans le jeu comptera pour l'expiration de la mission.

Métadonnées

Les missions ont des métadonnées qui spécifient comment elles seront affichées dans l'interface utilisateur des Missions. Vous pouvez utiliser les champs optionnels suivants pour personnaliser ses métadonnées.

Nom	Type	Description
displayName	string	Un nom à afficher pour la mission dans l'interface utilisateur au lieu de missionId.
description	string	Un bloc de texte plus long qui fournit des informations ou un contexte supplémentaires sur la mission.
visibleAfterComplete	bool	Si défini sur vrai, la mission apparaîtra dans la liste des missions même après avoir été complétée mais marquée comme complétée.
visibleAfterFailed	bool	Si défini sur vrai, la mission apparaîtra dans la liste des missions même après avoir échoué mais marquée comme échouée.
visibleBeforeUnlocked	bool	Si défini sur vrai, la mission sera visible mais verrouillée dans la liste des missions avant d'être disponible pour complétion.
invisibleWhileActive	bool	Si défini sur vrai, la mission sera invisible même pendant qu'elle est activement en cours.
rewards	table	Une liste d'informations d'affichage des récompenses. assetID (number) - L'ID de l'image qui s'affiche dans l'interface utilisateur des missions sous les récompenses pour une quête. Ceci est requis si une récompense est présente. displayName (string) - Le nom qui s'affiche dans l'interface utilisateur des missions sous l'icône.

Définir des tâches

Chaque mission peut avoir zéro ou plusieurs tâches. Si une mission n'a aucune tâche, elle est réclamable immédiatement après son déverrouillage ; si une mission a une ou plusieurs tâches, une fois les tâches terminées, le joueur peut collecter toutes les récompenses associées à la mission. Chaque tâche a un taskId, qui est la clé associée à la tâche pour une mission donnée.

Les tâches se présentent sous deux types :

Tâches chronométrées - Vous permet de démarrer et d'arrêter la tâche à différents moments. Un certain temps doit s'écouler pendant que le chronomètre de la tâche est en cours d'exécution, puis la tâche est terminée.
Tâches de comptage - Vous permet d'ajouter ou de définir la progression de la tâche. Lorsque la progression atteint une valeur définie, la tâche est terminée.

Les deux types de tâches partagent les champs suivants :

Nom	Type	Description
taskType	string	Spécifie si le type de tâche est de comptage ou chronométré.
counter	object	(Optionnel) Le compteur que cette tâche suit. Les compteurs sont un stockage persistant spécifique au joueur pour un nombre ou un chronomètre. Plusieurs tâches peuvent suivre un seul compteur ; par exemple, si plus d'une tâche suit combien de pièces un joueur a collectées, elles peuvent toutes partager le même compteur de "pièces". Ces tâches peuvent suivre indépendamment les nouvelles pièces collectées, en commençant à zéro, ou continuer à compter à partir de la valeur du compteur (toutes les pièces déjà collectées). counterId (string) - L'ID du compteur à suivre. Utilisez cet ID pour obtenir ou définir la valeur du compteur. continueFromCounter (Optionnel bool) - Si défini sur vrai, la progression de la tâche correspondra directement à la valeur du compteur plutôt qu'à la quantité qu'elle a augmentée.
metadata	object	(Optionnel) Informations sur la façon dont la tâche s'affiche dans l'interface utilisateur. displayName (string) - Nom de la tâche, utilisé lorsqu'il est affiché dans l'interface utilisateur. numericType (Optionnel string) - comment le nombre de progression dans la tâche doit être affiché. Fraction, ex. 5/10 ou 5k/50k Pourcentage, ex. 50% ou 10% LongFraction, ex. 5/10 ou 5000/50000 Booléen, ex. Incomplet
callToAction	object	(Optionnel) Un bouton qui déclenche une fonction de rappel. callback (function) - Fonction déclenchée par le bouton callToAction. buttonText (string) - Le texte qui s'affiche dans l'interface du bouton.

Champs des tâches de comptage

Les tâches de comptage ont une valeur requise. Lorsque la progression de la tâche atteint ce montant, la tâche est terminée.

Nom	Type	Description
goalCount	number	(Optionnel) La progression requise pour compléter la tâche.

Champs des tâches chronométrées

Les tâches chronométrées ont un montant cible de temps passé, et sont démarrées et arrêtées. Lorsque le montant cible de temps est atteint, la tâche est terminée.

Nom	Type	Description
goalSeconds	number	Le nombre de secondes qui doivent s'écouler pour compléter la tâche.
startImmediately	bool	Si la tâche doit commencer à compter le temps dès qu'elle est déverrouillée, plutôt qu'après avoir été démarrée.
includesOfflineTime	bool	Si la tâche doit inclure le temps passé pendant que le joueur n'est pas activement dans le jeu.

Configurer des catégories

Les catégories n'ont pas besoin d'être explicitement définies pour être utilisées, car la catégorie d'une mission a des valeurs par défaut qui seront utilisées. Cependant, vous pouvez configurer ces valeurs dans ReplicatedStorage.Missions.Configs.Categories pour ajouter des effets supplémentaires à la catégorie. Les catégories sont identifiées par des CategoryIds uniques, les mêmes que ceux référencés dans la configuration des missions.

Nom	Type	Description
repeatDelaySeconds	number	(Optionnel) Si défini, toutes les missions de la catégorie sont réinitialisées chaque fois que le temps spécifié s'écoule, et peuvent être déverrouillées, complétées et leurs récompenses réclamées à nouveau. Ceci est séparé des missions répétables, qui sont répétables dans une catégorie donnée.

Intégrer la logique serveur

Jetez un œil à ReplicatedStorage.Missions.Server.Examples.MissionsExample, qui montre comment votre serveur interagira avec le package de fonctionnalités Missions.

Vous devez principalement connecter quatre choses une fois que vous avez glissé le package de fonctionnalités Missions dans votre jeu :

Définir des missions dans votre configuration de missions.

Ajouter de la logique à votre jeu pour mettre à jour la progression des tâches ou les compteurs auxquels la progression est liée.

README

-- Augmente la progression sur une mission Saut avec une tâche Sauts
Missions.addProgressToTask(player, "Saut", "Sauts", 1)

-- Démarre le chronomètre sur une mission TempsDeCombat avec une tâche TempsEnCombat
Missions.startTimedTask(player, "TempsDeCombat", "TempsEnCombat")

-- Arrête le chronomètre sur une mission TempsDeCombat avec une tâche TempsEnCombat
Missions.stopTimedTask(player, "TempsDeCombat", "TempsEnCombat")

-- Augmente la progression sur toutes les tâches liées au compteur Sauts
CounterSystem.addCounter(player, "Sauts", 1)

-- Démarre le chronomètre sur toutes les tâches chronométrées liées au compteur TempsEnCombat
CounterSystem.startTimer(player, "TempsEnCombat")

-- Arrête le chronomètre sur toutes les tâches chronométrées liées au compteur TempsEnCombat
CounterSystem.stopTimer(player, "TempsEnCombat")

Définir des gestionnaires de complétion de mission, et éventuellement des gestionnaires de déverrouillage ou d'échec. Utilisez le gestionnaire de complétion pour récompenser les récompenses de la mission dans votre jeu.

README

local function completeHandler(player: Player, missionId: Types.MissionId)
     print(`{player} a complété la mission {missionId}`)
     -- Récompensez le joueur avec ses récompenses.
 end

Missions.setCompletionHandler(missionId, completeHandler)

Déverrouiller les missions qui ne sont pas déverrouillées automatiquement. La logique du package de fonctionnalités Missions garantit que toutes les exigences de mission sont remplies avant que la mission ne soit complète, et que ses récompenses soient collectables.
README
Missions.unlockMission(player, "Manuel")

Configurer des constantes

Les constantes pour le package de fonctionnalités Core se trouvent à deux endroits :

Les constantes partagées se trouvent dans ReplicatedStorage.FeaturePackagesCore.Configs.SharedConstants.
Les constantes spécifiques au package, dans ce cas le package de fonctionnalités Missions, se trouvent dans ReplicatedStorage.Missions.Configs.Constants.

De plus, vous pouvez trouver des chaînes pour la traduction regroupées en un seul endroit : ReplicatedStorage.FeaturePackagesCore.Configs.TranslationStrings.

Personnaliser les composants de l'interface utilisateur

En modifiant les objets du package, tels que les couleurs, la police et la transparence, vous pouvez ajuster la présentation visuelle de votre interface utilisateur des missions. Par exemple, dans ReplicatedStorage.Missions.Configs.Constants, vous pouvez activer SingleTaskMode pour afficher une barre de progression pour une tâche directement sur la mission elle-même pour les missions qui n'ont qu'une seule tâche.

Si vous déplacez des objets dans la hiérarchie, le code ne pourra pas les trouver, et vous devrez apporter des ajustements dans MissionsUI.

De plus, si votre jeu a déjà une interface utilisateur existante que vous souhaitez intégrer avec le package de fonctionnalités Missions, le ModuleScript client MissionsClient contient toutes les fonctions nécessaires pour obtenir les informations sur les missions d'un joueur envoyées depuis le serveur.

Package de fonctionnalités Core

Package de fonctionnalités Missions