BattlePass
Vue d'ensemble
BattlePass ajoute une piste de progression saisonnière à votre serveur. Une saison a une date de début et de fin et se découpe en semaines ; chaque semaine débloque une liste de quêtes. Lorsqu'un joueur termine l'une de ces quêtes, il gagne de l'XP, et des seuils d'XP se transforment en niveaux. Les récompenses sont regroupées en paliers (par exemple un palier gratuit et un palier premium protégé par une permission) et se récupèrent depuis un menu.
Tout se configure à partir d'une seule entrée Battle Pass Definition dans le panel web : paliers, récompenses, semaines, seuils d'XP, calendrier, disposition du menu et objets des boutons. Une récompense est simplement une liste de triggers TypeWriter : elle peut donc donner des objets, exécuter des commandes, accorder un cosmétique ou tout ce qu'une action peut faire. Les quêtes proviennent de l'extension Quest de TypeWriter.
L'extension fonctionne sur la version BTC de TypeWriter (BTC Core, Paper/Folia) et est documentée ici à titre de référence. La progression est enregistrée via un artefact Battle Pass Data, conservé dans un cache mémoire pour que les menus et placeholders n'attendent jamais le stockage.
Fonctionnalités
- Saisons — dates de début et de fin facultatives, une durée de semaine en jours et un fuseau horaire IANA (UTC par défaut).
- Quêtes hebdomadaires — les semaines se débloquent automatiquement ou à une date choisie, et chaque quête donne une quantité fixe d'XP une fois terminée.
- XP et niveaux — une liste de seuils d'XP définit les niveaux, avec un plafond d'XP facultatif.
- Récompenses par paliers — chaque palier a une priorité, une permission facultative et des récompenses liées à un niveau requis.
- Récupération sûre — une récupération est réservée avant l'exécution des triggers : une récompense ne peut donc pas être remise deux fois.
- Menus configurables — emplacements, tailles et objet, nom et lore de chaque bouton, ou une disposition entièrement personnalisée construite sur l'extension GUI.
- Commandes d'administration — ajoutez, retirez ou définissez de l'XP et des niveaux pour vous-même ou d'autres joueurs, et lisez la progression d'un joueur.
- Placeholders — niveau, XP, compteurs de récompenses et informations de semaine pour les scoreboards et les menus.
- Messages modifiables — chaque message de chat peut être modifié dans une entrée BattlePass Messages.
- Prêt pour le réseau — la progression est stockée via l'extension MySQL, avec invalidation du cache via Redis lorsqu'il est disponible.
Installation
- Installez l'extension TypeWriter Quest, l'extension GUI (
GuiAndDialogsdans la version BTC) et l'extension MySQL. TypeWriter ne chargera pas BattlePass sans elles. - Placez le JAR de BattlePass dans
plugins/Typewriter/extensions/et redémarrez le serveur. - Créez les quêtes que vous voulez utiliser avec l'extension Quest.
- Si vous voulez un palier premium, créez la permission avec votre plugin de permissions (le nom vous appartient, vous le saisissez dans le palier).
Premiers pas
Créez une saison de quatre semaines avec une récompense gratuite au niveau 1 :
- Dans le panel web TypeWriter, ouvrez une page manifest et ajoutez un artefact Battle Pass Data. Laissez
artifactIdtel que généré et gardezstorage.modesurPLAYER. - Ajoutez une entrée Battle Pass Definition sur la même page. Donnez-lui un
name, définissezdatasur l'artefact, et choisissez uneicontelle queminecraft:book. - Dans
xp, renseignezlevelsavec des seuils d'XP croissants (par exemple100,250,500) et éventuellementmax. - Dans
weeks, ajoutez une semaine avecnumber1, untitle, et dansquestschoisissez une entrée Quest et donnez-lui unxpReward. Répétez pour les semaines suivantes. - Dans
schedule, définissezstart(par exemple2026-11-01T00:00:00),weekDurationDaysettimezone(par exempleEurope/Paris). Les semaines se débloquent alors l'une après l'autre. - Dans
tiers, ajoutez un palier aveclevel1, et dansrewardsajoutez une récompense aveclevelRequired1et undisplayName. Reliez lestriggersqui donnent la récompense, par exemple une action qui donne un objet. - Ajoutez une action Open Battle Pass pointant vers votre définition dans
battlePass, et déclenchez-la depuis un PNJ, un objet ou un menu. Les joueurs peuvent aussi saisir/tw battlepass. - Publiez, terminez une quête de la semaine, puis ouvrez le menu pour récupérer la récompense.
Le level d'un palier est son numéro dans le menu des récompenses et doit être unique au sein d'une définition. Le niveau de joueur nécessaire pour récupérer une récompense est le levelRequired propre à la récompense. Un palier peut porter une permission : les joueurs qui ne l'ont pas voient ses récompenses comme verrouillées, c'est ainsi que vous construisez une piste premium.
Chaque récompense a un id. Laissez-le vide et l'extension en génère un à partir du niveau du palier et de la position de la récompense (tier-1-reward-1), mais si vous déplacez ou insérez des récompenses ensuite, les identifiants générés se décalent et les récompenses déjà récupérées par les joueurs ne correspondent plus. Définissez un id explicite sur chaque récompense avant le début de la saison et ne le changez jamais.
Fonctionnement
L'XP n'est gagnée que lorsqu'une quête listée dans l'une des semaines de la définition passe à COMPLETED, que la semaine est marquée available, que la semaine est débloquée et que la saison est en cours. Une quête avec un xpReward de 0 ne donne rien. Le niveau correspond au nombre de seuils xp.levels que le joueur a atteints.
Une récompense peut être récupérée lorsque la saison a commencé (la récupération reste possible après la fin), que le niveau du joueur atteint levelRequired, et qu'il possède la permission du palier si elle est définie. Les récompenses ne se récupèrent qu'une fois. Si les triggers d'une récompense échouent, la récompense reste en attente et n'est pas retentée d'elle-même, car les triggers peuvent avoir des effets de bord.
Menus
Par défaut, l'extension ouvre ses propres menus d'inventaire : un menu principal listant les semaines, un menu de quêtes pour la semaine sélectionnée, et un menu de récompenses (paliers).
- Menu principal — un bouton par semaine, des boutons semaine précédente et suivante, un bouton de récompenses, un bouton d'informations et un bouton de fermeture.
- Menu de quêtes — les quêtes de la semaine avec leur état (verrouillée, disponible, active, terminée), des boutons de page, un bouton de tri et un bouton retour.
- Menu de récompenses — les récompenses de chaque palier avec leur état, des boutons de page et un bouton retour ; cliquer sur une récompense déverrouillée la récupère.
Les tailles et positions proviennent de layout. Chaque taille doit être un multiple de 9 compris entre 9 et 54, et chaque emplacement doit tenir à l'intérieur. Les emplacements acceptent des nombres seuls ou des plages comme 10-16. Laissez un emplacement vide pour utiliser la position par défaut (disposition de 54 emplacements avec les semaines sur la ligne 2, les quêtes sur les lignes 2 à 4, la fermeture sur l'emplacement 49), ou désactivez un bouton avec son champ ...Enabled. Chaque bouton a un item, un name et un lore dans buttons, où vous pouvez utiliser des placeholders entre accolades, tels que {week_title}, {quest_name}, {tier_level} ou {reward_state}. L'aide des champs dans le panel liste les placeholders disponibles pour chaque bouton.
Si vous définissez baseMenuId, menuLayoutPool, menuViews ou menuMainLayoutId, le pass s'ouvre à la place dans votre propre châssis GUI, avec trois vues (accueil, niveaux, quêtes) dont les identifiants sont définis dans menuHomeViewId, menuLevelsViewId et menuQuestsViewId. L'éditeur GUI propose alors des objets battlepass_button: : WEEK_SLOT, TIER_MENU, REWARD_SLOT, CLAIM, QUEST_SLOT, SORT, INFO, PAGE_NEXT, PAGE_PREV, BACK et CLOSE. Les descriptions des types de boutons dans l'éditeur sont en français.
Les interactions de menu sont internes à la session GUI : ce ne sont pas des commandes Bukkit et les joueurs ne peuvent pas les saisir.
Commandes
Les commandes de BattlePass sont des sous-commandes de la commande TypeWriter : elles commencent donc par /typewriter ou son alias /tw. La permission de base est typewriter.battlepass. L'argument <pass> est l'identifiant ou le nom d'une Battle Pass Definition et est complété automatiquement. L'argument facultatif [targets] est un sélecteur de joueurs ; sans lui, la commande s'applique à l'émetteur.
| Commande | Description |
|---|---|
/tw battlepass | Ouvre le menu de la première définition, triée par identifiant. |
/tw battlepass menu | Identique à /tw battlepass. |
/tw battlepass open | Identique à /tw battlepass. |
/tw battlepass <pass> xp add <amount> [targets] | Ajoute de l'XP (le signe de la quantité est ignoré). |
/tw battlepass <pass> xp remove <amount> [targets] | Retire de l'XP. |
/tw battlepass <pass> xp set <amount> [targets] | Définit l'XP (pas en dessous de zéro). |
/tw battlepass <pass> level add <amount> [targets] | Augmente le niveau. |
/tw battlepass <pass> level remove <amount> [targets] | Diminue le niveau. |
/tw battlepass <pass> level set <amount> [targets] | Définit le niveau. |
/tw battlepass <pass> info [targets] | Affiche l'XP et le niveau d'un joueur pour le pass. |
Permissions
| Permission | Autorise |
|---|---|
typewriter.battlepass | Toutes les commandes /tw battlepass, y compris le menu et les sous-commandes d'administration. |
permission d'un palier | Une permission de votre choix, définie sur un palier, nécessaire pour récupérer les récompenses de ce palier. |
Placeholders
Ce sont des balises MiniPlaceholders de l'extension battlepass, utilisables dans tout texte MiniMessage qui prend en charge les placeholders. Remplacez def par l'identifiant de l'entrée Battle Pass Definition. Les compteurs sont des nombres ; les valeurs vrai ou faux sont renvoyées sous la forme 1 ou 0.
| Placeholder | Renvoie |
|---|---|
<battlepass_name:def> | Le nom du pass. |
<battlepass_active:def> | 1 tant que les joueurs peuvent gagner de l'XP (saison en cours), sinon 0. |
<battlepass_level:def> | Le niveau du joueur. |
<battlepass_xp:def> | L'XP du joueur. |
<battlepass_xp_max:def> | Le plafond d'XP, ou le seuil le plus élevé lorsqu'aucun plafond n'est défini. |
<battlepass_xp_next:def> | Le seuil d'XP du niveau suivant. |
<battlepass_xp_remaining:def> | L'XP manquante pour atteindre le niveau suivant. |
<battlepass_rewards:def> et <battlepass_rewards_total:def> | Le nombre total de récompenses. |
<battlepass_rewards_claimed:def> | Les récompenses déjà récupérées. |
<battlepass_rewards_available:def> | Les récompenses que le joueur peut récupérer maintenant. |
<battlepass_rewards_unclaimed:def> | Total des récompenses moins les récompenses récupérées. |
<battlepass_rewards_pending:def> | Les récompenses réservées mais pas encore remises. |
<battlepass_week_state:def:N> | Le libellé d'état de la semaine N. |
<battlepass_week_active:def:N> | 1 lorsque la semaine N n'est ni verrouillée ni indisponible. |
<battlepass_week_available:def:N> | 1 lorsque la semaine est marquée available. |
<battlepass_week_title:def:N> | Le titre de la semaine N. |
<battlepass_week_description:def:N> | La description de la semaine N. |
<battlepass_week_release:def:N> | La date de déblocage de la semaine N. |
<battlepass_week_release_in:def:N> | Le temps restant avant le déblocage de la semaine N, vide une fois débloquée. |
Entrées
5 entrées, générées depuis la source de l'extension.
Actions1
- Open Battle PassOpen a battle pass menu
Faits1
- Battle Pass Quest ActiveCheck if a battle pass week is active
Artefacts1
- Battle Pass Data ArtifactStore battle pass runtime data
Manifestes1
- Battlepass DefinitionRegister a battle pass definition
Autres entrées1
- Battlepass MessagesBattlePass Messages
Dépannage
L'extension ne se charge pas. BattlePass nécessite les extensions Quest, GUI (GuiAndDialogs) et MySQL. Consultez le journal de démarrage de TypeWriter pour repérer une dépendance manquante.
Le journal indique « Ignoring invalid battle pass definition ». La définition a échoué à la validation : elle n'est donc pas enregistrée et /tw battlepass affiche « Aucun Battle Pass n'est actuellement chargé ». La ligne du journal liste les problèmes : un name vide, une taille de menu qui n'est pas un multiple de 9 compris entre 9 et 54, un emplacement hors du menu, des niveaux de paliers, numéros de semaines ou identifiants de récompenses en double, xp.levels non strictement croissant, ou un schedule.start qui n'est pas antérieur à schedule.end.
Terminer une quête ne donne pas d'XP. La quête doit être listée dans une semaine de la définition avec un xpReward supérieur à 0, la semaine doit être available et débloquée, la saison doit être active, et la définition a besoin d'un artefact data (le journal avertit lorsqu'il manque). Un timezone inconnu se rabat sur UTC, et les chaînes de date qui ne peuvent pas être analysées sont ignorées.
Une récompense ne peut pas être récupérée. Le niveau doit atteindre levelRequired, le joueur a besoin de la permission du palier, la saison doit avoir commencé, et la récompense ne doit pas être déjà récupérée ou en attente. Si ses triggers ont échoué, le journal indique « remains pending after delivery failure » et la récompense reste en attente jusqu'à ce qu'un administrateur décide quoi faire.
Des récompenses récupérées réapparaissent après modification des récompenses. Les identifiants de récompenses générés à partir des positions ont changé. Donnez un id explicite à chaque récompense et conservez-le inchangé.
La progression n'est pas enregistrée. L'artifactId de l'artefact doit rester un UUID valide généré par le panel web ; l'extension refuse tout autre format. Ne déplacez ni ne renommez les fichiers stockés à la main.