BattlePass
Overview
BattlePass adds a seasonal progression track to your server. A season has a start and an end date and is split into weeks; each week unlocks a list of quests. When a player completes one of those quests, they earn XP, and XP thresholds turn into levels. Rewards are grouped in tiers (for example a free tier and a premium tier guarded by a permission) and are claimed from a menu.
Everything is configured from one Battle Pass Definition entry in the web panel: tiers, rewards, weeks, XP thresholds, schedule, menu layout and button items. A reward is just a list of TypeWriter triggers, so it can give items, run commands, grant a cosmetic or anything else an action can do. Quests come from the TypeWriter Quest extension.
The extension runs on the BTC build of TypeWriter (BTC Core, Paper/Folia) and is documented here for reference. Progress is saved through a Battle Pass Data artifact, kept in a memory cache so menus and placeholders never wait for storage.
Features
- Seasons — optional start and end dates, a week duration in days and an IANA time zone (UTC by default).
- Weekly quests — weeks unlock automatically or on a chosen date, and each quest gives a fixed amount of XP when completed.
- XP and levels — a list of XP thresholds defines the levels, with an optional XP cap.
- Tiered rewards — each tier has a priority, an optional permission and rewards tied to a required level.
- Safe claiming — a claim is reserved before the triggers run, so a reward cannot be delivered twice.
- Configurable menus — slots, sizes and the item, name and lore of every button, or a full custom layout built on the GUI extension.
- Admin commands — add, remove or set XP and levels for yourself or other players, and read a player's progress.
- Placeholders — level, XP, reward counters and week information for scoreboards and menus.
- Editable messages — every chat message can be changed in a BattlePass Messages entry.
- Network ready — progress is stored through the MySQL extension, with cache invalidation over Redis when it is available.
Installation
- Install the TypeWriter Quest extension, the GUI extension (
GuiAndDialogsin the BTC build) and the MySQL extension. TypeWriter will not load BattlePass without them. - Put the BattlePass JAR in
plugins/Typewriter/extensions/and restart the server. - Create the quests you want to use with the Quest extension.
- If you want a premium tier, create the permission with your permissions plugin (the name is up to you, you type it in the tier).
Getting started
Create a four-week season with a free reward at level 1:
- In the TypeWriter web panel, open a manifest page and add a Battle Pass Data artifact. Leave
artifactIdas generated and keepstorage.modeonPLAYER. - Add a Battle Pass Definition entry on the same page. Give it a
name, setdatato the artifact, and choose aniconsuch asminecraft:book. - In
xp, filllevelswith increasing XP thresholds (for example100,250,500) and optionallymax. - In
weeks, add a week withnumber1, atitle, and inquestspick a Quest entry and give it anxpReward. Repeat for the next weeks. - In
schedule, setstart(for example2026-11-01T00:00:00),weekDurationDaysandtimezone(for exampleEurope/Paris). Weeks then unlock one after the other. - In
tiers, add a tier withlevel1, and inrewardsadd a reward withlevelRequired1and adisplayName. Link thetriggersthat give the reward, for example an action that gives an item. - Add an Open Battle Pass action pointing at your definition in
battlePass, and trigger it from an NPC, an item or a menu. Players can also type/tw battlepass. - Publish, complete a quest from the week, and open the menu to claim the reward.
A tier level is its number in the rewards menu and must be unique inside a definition. The player level needed to claim a reward is the reward's own levelRequired. A tier can carry a permission: players without it see its rewards as locked, which is how you build a premium track.
Each reward has an id. Leave it empty and the extension generates one from the tier level and the reward position (tier-1-reward-1), but if you move or insert rewards afterwards, the generated ids shift and players' claimed rewards no longer match. Set an explicit id on every reward before the season starts and never change it.
How it works
XP is earned only when a quest listed in one of the definition's weeks goes to COMPLETED, the week is marked available, the week is unlocked and the season is running. A quest with an xpReward of 0 gives nothing. The level is the number of xp.levels thresholds the player has reached.
A reward can be claimed when the season has started (claiming stays possible after the end), the player's level reaches levelRequired, and they have the tier permission if one is set. Rewards are claimed once. If a reward's triggers fail, the reward stays pending and is not retried by itself, because triggers may have side effects.
Menus
By default the extension opens its own inventory menus: a main menu listing the weeks, a quest menu for the selected week, and a rewards (tier) menu.
- Main menu — one button per week, previous and next week buttons, a rewards button, an info button and a close button.
- Quest menu — the week's quests with their state (locked, available, active, completed), page buttons, a sort button and a back button.
- Rewards menu — rewards of each tier with their state, page buttons and a back button; clicking an unlocked reward claims it.
Sizes and positions come from layout. Each size must be a multiple of 9 between 9 and 54, and each slot must fit inside it. Slots accept single numbers or ranges such as 10-16. Leave a slot empty to use the default position (54-slot layout with weeks on row 2, quests on rows 2 to 4, close on slot 49), or turn a button off with its ...Enabled field. Each button has an item, a name and a lore in buttons, where you can use placeholders in curly braces, such as {week_title}, {quest_name}, {tier_level} or {reward_state}. The field help in the panel lists the placeholders available for each button.
If you set baseMenuId, menuLayoutPool, menuViews or menuMainLayoutId, the pass opens inside your own GUI chassis instead, with three views (home, levels, quests) whose ids are set in menuHomeViewId, menuLevelsViewId and menuQuestsViewId. The GUI editor then offers battlepass_button: items: WEEK_SLOT, TIER_MENU, REWARD_SLOT, CLAIM, QUEST_SLOT, SORT, INFO, PAGE_NEXT, PAGE_PREV, BACK and CLOSE. The button type descriptions in the editor are in French.
Menu interactions are internal to the GUI session: they are not Bukkit commands and cannot be typed by players.
Commands
BattlePass commands are subcommands of the TypeWriter command, so they start with /typewriter or its alias /tw. The base permission is typewriter.battlepass. The <pass> argument is the id or the name of a Battle Pass Definition and is auto-completed. The optional [targets] argument is a player selector; without it the command applies to the sender.
| Command | Description |
|---|---|
/tw battlepass | Opens the menu of the first definition, sorted by id. |
/tw battlepass menu | Same as /tw battlepass. |
/tw battlepass open | Same as /tw battlepass. |
/tw battlepass <pass> xp add <amount> [targets] | Adds XP (the sign of the amount is ignored). |
/tw battlepass <pass> xp remove <amount> [targets] | Removes XP. |
/tw battlepass <pass> xp set <amount> [targets] | Sets XP (not below zero). |
/tw battlepass <pass> level add <amount> [targets] | Raises the level. |
/tw battlepass <pass> level remove <amount> [targets] | Lowers the level. |
/tw battlepass <pass> level set <amount> [targets] | Sets the level. |
/tw battlepass <pass> info [targets] | Shows a player's XP and level for the pass. |
Permissions
| Permission | Grants |
|---|---|
typewriter.battlepass | Every /tw battlepass command, including the menu and the admin subcommands. |
Tier permission | A permission of your choice, set on a tier, that is needed to claim that tier's rewards. |
Placeholders
These are MiniPlaceholders tags of the battlepass expansion, usable in any MiniMessage text that supports placeholders. Replace def with the id of the Battle Pass Definition entry. Counters are numbers; true or false values are returned as 1 or 0.
| Placeholder | Returns |
|---|---|
<battlepass_name:def> | The name of the pass. |
<battlepass_active:def> | 1 while players can earn XP (season running), otherwise 0. |
<battlepass_level:def> | The player's level. |
<battlepass_xp:def> | The player's XP. |
<battlepass_xp_max:def> | The XP cap, or the highest threshold when no cap is set. |
<battlepass_xp_next:def> | The XP threshold of the next level. |
<battlepass_xp_remaining:def> | XP missing to reach the next level. |
<battlepass_rewards:def> and <battlepass_rewards_total:def> | The total number of rewards. |
<battlepass_rewards_claimed:def> | Rewards already claimed. |
<battlepass_rewards_available:def> | Rewards the player can claim now. |
<battlepass_rewards_unclaimed:def> | Total rewards minus claimed rewards. |
<battlepass_rewards_pending:def> | Rewards reserved but not yet delivered. |
<battlepass_week_state:def:N> | The state label of week N. |
<battlepass_week_active:def:N> | 1 when week N is neither locked nor unavailable. |
<battlepass_week_available:def:N> | 1 when the week is marked available. |
<battlepass_week_title:def:N> | The title of week N. |
<battlepass_week_description:def:N> | The description of week N. |
<battlepass_week_release:def:N> | The unlock date of week N. |
<battlepass_week_release_in:def:N> | The time left before week N unlocks, empty once unlocked. |
Entries
5 entries, generated from the extension source.
Actions1
- Open Battle PassOpen a battle pass menu
Facts1
- Battle Pass Quest ActiveCheck if a battle pass week is active
Artifacts1
- Battle Pass Data ArtifactStore battle pass runtime data
Manifests1
- Battlepass DefinitionRegister a battle pass definition
Other entries1
- Battlepass MessagesBattlePass Messages
Troubleshooting
The extension does not load. BattlePass requires the Quest, GUI (GuiAndDialogs) and MySQL extensions. Check the TypeWriter startup log for a missing dependency.
The log says "Ignoring invalid battle pass definition". The definition failed validation, so it is not registered and /tw battlepass says "Aucun Battle Pass n'est actuellement chargé". The log line lists the problems: a blank name, a menu size that is not a multiple of 9 between 9 and 54, a slot outside the menu, duplicated tier levels, week numbers or reward ids, xp.levels not strictly increasing, or a schedule.start that is not before schedule.end.
Completing a quest gives no XP. The quest must be listed in a week of the definition with an xpReward above 0, the week must be available and unlocked, the season must be active, and the definition needs a data artifact (the log warns when it is missing). An unknown timezone falls back to UTC, and date strings that cannot be parsed are ignored.
A reward cannot be claimed. The level must reach levelRequired, the player needs the tier permission, the season must have started, and the reward must not be claimed or pending already. If its triggers failed, the log reports "remains pending after delivery failure" and the reward stays pending until an administrator decides what to do.
Claimed rewards reappear after editing the rewards. Reward ids that were generated from positions changed. Give every reward an explicit id and keep it unchanged.
Progress is not saved. The artifact's artifactId must stay a valid UUID generated by the web panel; the extension refuses to use anything else. Do not move or rename the stored files by hand.