BattlePass
Descripción general
BattlePass añade a tu servidor una línea de progresión por temporadas. Una temporada tiene una fecha de inicio y una de fin y se divide en semanas; cada semana desbloquea una lista de misiones. Cuando un jugador completa una de esas misiones, gana XP, y los umbrales de XP se convierten en niveles. Las recompensas se agrupan en tiers (por ejemplo, un tier gratuito y un tier premium protegido por un permiso) y se reclaman desde un menú.
Todo se configura desde una única entrada Battle Pass Definition en el panel web: tiers, recompensas, semanas, umbrales de XP, calendario, disposición del menú e items de los botones. Una recompensa es simplemente una lista de triggers de TypeWriter, por lo que puede dar objetos, ejecutar comandos, conceder un cosmético o cualquier otra cosa que pueda hacer una acción. Las misiones provienen de la extensión Quest de TypeWriter.
La extensión funciona en la compilación BTC de TypeWriter (BTC Core, Paper/Folia) y se documenta aquí como referencia. El progreso se guarda mediante un artefacto Battle Pass Data, mantenido en una caché en memoria para que los menús y los placeholders nunca esperen al almacenamiento.
Características
- Temporadas — fechas de inicio y fin opcionales, una duración de semana en días y una zona horaria IANA (UTC por defecto).
- Misiones semanales — las semanas se desbloquean automáticamente o en una fecha elegida, y cada misión da una cantidad fija de XP al completarse.
- XP y niveles — una lista de umbrales de XP define los niveles, con un tope de XP opcional.
- Recompensas por tiers — cada tier tiene una prioridad, un permiso opcional y recompensas vinculadas a un nivel requerido.
- Reclamación segura — una reclamación se reserva antes de que se ejecuten los triggers, de modo que una recompensa no puede entregarse dos veces.
- Menús configurables — ranuras, tamaños y el item, nombre y lore de cada botón, o un layout personalizado completo construido sobre la extensión GUI.
- Comandos de administración — añade, quita o establece XP y niveles para ti o para otros jugadores, y lee el progreso de un jugador.
- Placeholders — nivel, XP, contadores de recompensas e información de semanas para scoreboards y menús.
- Mensajes editables — cada mensaje de chat se puede cambiar en una entrada BattlePass Messages.
- Preparado para redes — el progreso se almacena mediante la extensión MySQL, con invalidación de caché por Redis cuando está disponible.
Instalación
- Instala la extensión Quest de TypeWriter, la extensión GUI (
GuiAndDialogsen la compilación BTC) y la extensión MySQL. TypeWriter no cargará BattlePass sin ellas. - Coloca el JAR de BattlePass en
plugins/Typewriter/extensions/y reinicia el servidor. - Crea las misiones que quieras usar con la extensión Quest.
- Si quieres un tier premium, crea el permiso con tu plugin de permisos (el nombre lo eliges tú, lo escribes en el tier).
Primeros pasos
Crea una temporada de cuatro semanas con una recompensa gratuita en el nivel 1:
- En el panel web de TypeWriter, abre una página de manifest y añade un artefacto Battle Pass Data. Deja
artifactIdtal como se generó y manténstorage.modeenPLAYER. - Añade una entrada Battle Pass Definition en la misma página. Dale un
name, establecedatacon el artefacto y elige uniconcomominecraft:book. - En
xp, rellenalevelscon umbrales de XP crecientes (por ejemplo100,250,500) y, opcionalmente,max. - En
weeks, añade una semana connumber1, untitley, enquests, elige una entrada Quest y dale unxpReward. Repite para las semanas siguientes. - En
schedule, establecestart(por ejemplo2026-11-01T00:00:00),weekDurationDaysytimezone(por ejemploEurope/Paris). Las semanas se desbloquean entonces una tras otra. - En
tiers, añade un tier conlevel1y, enrewards, añade una recompensa conlevelRequired1y undisplayName. Enlaza lostriggersque dan la recompensa, por ejemplo una acción que da un objeto. - Añade una acción Open Battle Pass que apunte a tu definición en
battlePass, y actívala desde un NPC, un objeto o un menú. Los jugadores también pueden escribir/tw battlepass. - Publica, completa una misión de la semana y abre el menú para reclamar la recompensa.
El level de un tier es su número en el menú de recompensas y debe ser único dentro de una definición. El nivel de jugador necesario para reclamar una recompensa es el levelRequired propio de la recompensa. Un tier puede llevar un permission: los jugadores que no lo tienen ven sus recompensas como bloqueadas, que es como se construye una línea premium.
Cada recompensa tiene un id. Si lo dejas vacío, la extensión genera uno a partir del nivel del tier y la posición de la recompensa (tier-1-reward-1), pero si después mueves o insertas recompensas, los ids generados cambian y las recompensas reclamadas de los jugadores dejan de coincidir. Establece un id explícito en cada recompensa antes de que empiece la temporada y no lo cambies nunca.
Cómo funciona
La XP se gana solo cuando una misión listada en una de las semanas de la definición pasa a COMPLETED, la semana está marcada como available, la semana está desbloqueada y la temporada está en curso. Una misión con un xpReward de 0 no da nada. El nivel es el número de umbrales de xp.levels que el jugador ha alcanzado.
Una recompensa se puede reclamar cuando la temporada ha empezado (reclamar sigue siendo posible tras el final), el nivel del jugador alcanza levelRequired y tiene el permission del tier si hay uno establecido. Las recompensas se reclaman una sola vez. Si los triggers de una recompensa fallan, la recompensa queda pendiente y no se reintenta por sí sola, porque los triggers pueden tener efectos secundarios.
Menús
Por defecto, la extensión abre sus propios menús de inventario: un menú principal que lista las semanas, un menú de misiones para la semana seleccionada y un menú de recompensas (tiers).
- Menú principal — un botón por semana, botones de semana anterior y siguiente, un botón de recompensas, un botón de información y un botón de cerrar.
- Menú de misiones — las misiones de la semana con su estado (bloqueada, disponible, activa, completada), botones de página, un botón de ordenar y un botón de volver.
- Menú de recompensas — recompensas de cada tier con su estado, botones de página y un botón de volver; al hacer clic en una recompensa desbloqueada, se reclama.
Los tamaños y posiciones provienen de layout. Cada tamaño debe ser un múltiplo de 9 entre 9 y 54, y cada ranura debe caber dentro de él. Las ranuras aceptan números sueltos o rangos como 10-16. Deja una ranura vacía para usar la posición por defecto (layout de 54 ranuras con las semanas en la fila 2, las misiones en las filas 2 a 4 y cerrar en la ranura 49), o desactiva un botón con su campo ...Enabled. Cada botón tiene un item, un name y un lore en buttons, donde puedes usar placeholders entre llaves, como {week_title}, {quest_name}, {tier_level} o {reward_state}. La ayuda de campo del panel lista los placeholders disponibles para cada botón.
Si estableces baseMenuId, menuLayoutPool, menuViews o menuMainLayoutId, el pase se abre dentro de tu propio chasis de GUI, con tres vistas (inicio, niveles, misiones) cuyos ids se establecen en menuHomeViewId, menuLevelsViewId y menuQuestsViewId. El editor de GUI ofrece entonces items battlepass_button:: WEEK_SLOT, TIER_MENU, REWARD_SLOT, CLAIM, QUEST_SLOT, SORT, INFO, PAGE_NEXT, PAGE_PREV, BACK y CLOSE. Las descripciones de los tipos de botón en el editor están en francés.
Las interacciones del menú son internas a la sesión de GUI: no son comandos de Bukkit y los jugadores no pueden escribirlas.
Comandos
Los comandos de BattlePass son subcomandos del comando de TypeWriter, por lo que empiezan por /typewriter o su alias /tw. El permiso base es typewriter.battlepass. El argumento <pass> es el id o el nombre de una Battle Pass Definition y se autocompleta. El argumento opcional [targets] es un selector de jugadores; sin él, el comando se aplica a quien lo ejecuta.
| Comando | Descripción |
|---|---|
/tw battlepass | Abre el menú de la primera definición, ordenada por id. |
/tw battlepass menu | Igual que /tw battlepass. |
/tw battlepass open | Igual que /tw battlepass. |
/tw battlepass <pass> xp add <amount> [targets] | Añade XP (se ignora el signo de la cantidad). |
/tw battlepass <pass> xp remove <amount> [targets] | Quita XP. |
/tw battlepass <pass> xp set <amount> [targets] | Establece la XP (no por debajo de cero). |
/tw battlepass <pass> level add <amount> [targets] | Sube el nivel. |
/tw battlepass <pass> level remove <amount> [targets] | Baja el nivel. |
/tw battlepass <pass> level set <amount> [targets] | Establece el nivel. |
/tw battlepass <pass> info [targets] | Muestra la XP y el nivel de un jugador para el pase. |
Permisos
| Permiso | Concede |
|---|---|
typewriter.battlepass | Todos los comandos /tw battlepass, incluidos el menú y los subcomandos de administración. |
permission del tier | Un permiso de tu elección, establecido en un tier, necesario para reclamar las recompensas de ese tier. |
Placeholders
Son etiquetas de MiniPlaceholders de la expansión battlepass, utilizables en cualquier texto MiniMessage que admita placeholders. Sustituye def por el id de la entrada Battle Pass Definition. Los contadores son números; los valores verdadero o falso se devuelven como 1 o 0.
| Placeholder | Devuelve |
|---|---|
<battlepass_name:def> | El nombre del pase. |
<battlepass_active:def> | 1 mientras los jugadores pueden ganar XP (temporada en curso), 0 en caso contrario. |
<battlepass_level:def> | El nivel del jugador. |
<battlepass_xp:def> | La XP del jugador. |
<battlepass_xp_max:def> | El tope de XP, o el umbral más alto cuando no hay tope establecido. |
<battlepass_xp_next:def> | El umbral de XP del siguiente nivel. |
<battlepass_xp_remaining:def> | La XP que falta para llegar al siguiente nivel. |
<battlepass_rewards:def> y <battlepass_rewards_total:def> | El número total de recompensas. |
<battlepass_rewards_claimed:def> | Recompensas ya reclamadas. |
<battlepass_rewards_available:def> | Recompensas que el jugador puede reclamar ahora. |
<battlepass_rewards_unclaimed:def> | Total de recompensas menos las reclamadas. |
<battlepass_rewards_pending:def> | Recompensas reservadas pero aún no entregadas. |
<battlepass_week_state:def:N> | La etiqueta de estado de la semana N. |
<battlepass_week_active:def:N> | 1 cuando la semana N no está bloqueada ni no disponible. |
<battlepass_week_available:def:N> | 1 cuando la semana está marcada como available. |
<battlepass_week_title:def:N> | El título de la semana N. |
<battlepass_week_description:def:N> | La descripción de la semana N. |
<battlepass_week_release:def:N> | La fecha de desbloqueo de la semana N. |
<battlepass_week_release_in:def:N> | El tiempo que falta para que se desbloquee la semana N, vacío una vez desbloqueada. |
Entradas
5 entradas, generadas a partir del código fuente de la extensión.
Acciones1
- Open Battle PassOpen a battle pass menu
Hechos1
- Battle Pass Quest ActiveCheck if a battle pass week is active
Artefactos1
- Battle Pass Data ArtifactStore battle pass runtime data
Manifiestos1
- Battlepass DefinitionRegister a battle pass definition
Otras entradas1
- Battlepass MessagesBattlePass Messages
Solución de problemas
La extensión no se carga. BattlePass requiere las extensiones Quest, GUI (GuiAndDialogs) y MySQL. Revisa el registro de inicio de TypeWriter por si falta una dependencia.
El registro dice "Ignoring invalid battle pass definition". La definición no superó la validación, por lo que no se registra y /tw battlepass dice "Aucun Battle Pass n'est actuellement chargé". La línea del registro lista los problemas: un name en blanco, un tamaño de menú que no es múltiplo de 9 entre 9 y 54, una ranura fuera del menú, niveles de tier, números de semana o ids de recompensa duplicados, xp.levels no estrictamente creciente, o un schedule.start que no es anterior a schedule.end.
Completar una misión no da XP. La misión debe estar listada en una semana de la definición con un xpReward superior a 0, la semana debe estar available y desbloqueada, la temporada debe estar activa y la definición necesita un artefacto data (el registro avisa cuando falta). Un timezone desconocido recurre a UTC, y las cadenas de fecha que no se pueden interpretar se ignoran.
No se puede reclamar una recompensa. El nivel debe alcanzar levelRequired, el jugador necesita el permission del tier, la temporada debe haber empezado y la recompensa no debe estar ya reclamada ni pendiente. Si sus triggers fallaron, el registro informa "remains pending after delivery failure" y la recompensa queda pendiente hasta que un administrador decide qué hacer.
Las recompensas reclamadas reaparecen tras editar las recompensas. Cambiaron los ids de recompensa que se generaron a partir de las posiciones. Da a cada recompensa un id explícito y mantenlo sin cambios.
El progreso no se guarda. El artifactId del artefacto debe seguir siendo un UUID válido generado por el panel web; la extensión se niega a usar cualquier otra cosa. No muevas ni renombres a mano los archivos almacenados.